Deprecation of lsp_installer.on_server_ready()

[williamboman]

edit(2022-05-11): The deprecation notices that were shown when starting neovim has been temporarily removed. The deprecation still applies, but until a substitute has been implemented and is available these methods will remain and will not print any deprecation warnings.

Deprecation of lsp_installer.on_server_ready()

Until this point, nvim-lsp-installer has provided a proprietary way of setting up servers, primarily through the suggested lsp_installer.on_server_ready() API. This has led to confusion and quite odd interoperability with other LSP plugins.

From now on, nvim-lsp-installer will suggest a new, preferred, way of setting up LSP servers where the required interactions with nvim-lsp-installer is reduced to a single line:

require("nvim-lsp-installer").setup {}

Then, to actually set up your servers, you'd do so the "lspconfig way", like so:

require("nvim-lsp-installer").setup {}
local lspconfig = require("lspconfig")

lspconfig.sumneko_lua.setup {}
lspconfig.tsserver.setup {}
-- ... and so on

In short - make sure to call nvim-lsp-installer's .setup() function, then pretend it doesn't exist!

This shifts back the responsibility to lspconfig (and other auxiliary plugins such as rust-tools.nvim), which will
consolidate support efforts across the LSP plugins but also making it easier to drive future changes and improvements in neovim's LSP ecosystem.

How does this work?

When calling require("nvim-lsp-installer").setup {}, a hook will be registered with lspconfig. This hook will be invoked every time you set up a server, for example:

lspconfig.sumneko_lua.setup {} --  nvim-lsp-installer's hook will be called for this server
lspconfig.tsserver.setup {} -- nvim-lsp-installer's hook will be called for this server

In this hook, nvim-lsp-installer will enhance the config table with the necessary changes, allowing the builtin LSP client to locate the server executable.

More information

• Refer to the README
• :h nvim-lsp-installer
• :h lspconfig - for how to setup servers

Drawbacks

Note that this does come with a few drawbacks, such as:

• Installed servers will no longer automatically be set up for you, you will need to explicitly set them up via
  lspconfig in your config. If you're installing a brand new server, this means you'll have to make changes to your
  config and then restart neovim.
• Unless you customize the way you setup servers, they will now always be set up, even if the server hasn't been
  installed yet. This may cause you to start seeing warning messages from lspconfig, stating that it's unable to find
  the command. To fix this, simply install the missing server(s). Note that you will have to manually trigger a
  FileType (or BufReadPost) autocmd after installation for lspconfig to attach your currently opened buffers (this
  is most easily done by issuing the :e command).

Example setup

Example new setup, for illustration purposes only (click to expand)

require("nvim-lsp-installer").setup {}
local lspconfig = require("lspconfig")

local function on_attach()
  -- setup buffer keymaps etc.
end

lspconfig.sumneko_lua.setup {
  on_attach = on_attach,
  settings = {
    Lua = {
      format = {
        enable = false
      },
      diagnostics = {
        globals = { "P" },
      },
    }
  }
}

local tsutils = require "nvim-lsp-ts-utils"
lspconfig.tsserver.setup {
  init_options = {
    hostInfo = "neovim",
    preferences = {
      includeInlayParameterNameHints = "none",
      includeInlayParameterNameHintsWhenArgumentMatchesName = false,
      includeInlayFunctionParameterTypeHints = false,
      includeInlayVariableTypeHints = true,
      includeInlayPropertyDeclarationTypeHints = true,
      includeInlayFunctionLikeReturnTypeHints = true,
      includeInlayEnumMemberValueHints = true,
    },
  },
  on_attach = function(client, bufnr)
    on_attach(client, bufnr)
    tsutils.setup {}
    tsutils.setup_client(client)
  end,
}

require("rust-tools").setup {}

for _, server in ipairs { "clangd", "eslint", "ltex" } do
  lspconfig[server].setup { on_attach = on_attach }
end

Migrating from lsp_installer.on_server_ready()

When migrating to the new structure, the only important thing is to make sure to call require("nvim-lsp-installer").setup {} before interacting with lspconfig. Then, simply set up your servers as you would if you were only using lspconfig. There's an example migration PR here, for reference.

[robbienohra]

What will this mean for configs we'd like to be applied to every language server?

For example:

local capabilities = require("cmp_nvim_lsp").update_capabilities(vim.lsp.protocol.make_client_capabilities())

Passing this in the nvim-lsp-installer setup function appears not to work:

require("nvim-lsp-installer").setup({
  capabilities = capabilities,
})

Will we need to manually add these to every language server now?

[robbienohra]

Ah I see your dot files are available here
Taking a look now 👀

[williamboman]

I use a setup hook instead. But I gave the global config override a try earlier and didn't run into any issues:

local util = require "lspconfig.util"

util.default_config = vim.tbl_extend(
    "force",
    util.default_config,
    {
        autostart = false,
        capabilities = { my_capabilities = "here" }
    }
)

[robbienohra]

thanks, man! will keep debugging 👌

[robbienohra]

I see where my mistake was 🤦 When I was trying to override the default config I inadvertently failed to still make the empty setup call .setup({}) for the underlying server. Also the order of operations seems to matter, i.e. needing to call the capabilities overrides after the server setup call (which makes sense).

Works now, thanks a bunch! This is a much cleaner setup, kudos for the amazing work on this plugin!

[williamboman]

Nice 👌!

[kylo252]

How about headless support? is the plan to remove that as well?

Because it's still useful either way to have some means of controlling the flow once the installation of a server (or multiple) has completed. A more appropriate name could be on_install_done(), or if it's a global then on_installer_done(). That would be in a similar vein to on_packer_done() for example.

[williamboman]

Do you mean :LspInstall --sync? That's not going anywhere :)

[kylo252]

I guess it's trivial to create ensure_installed_sync()

sync implementation

---@param server_identifiers string[]
local function ensure_installed_sync(server_identifiers)
    for _, server_identifier in ipairs(server_identifiers) do
        local server_name, version = servers.parse_server_identifier(server_identifier)
        local ok, server = servers.get_server(server_name)
        if ok and not server:is_installed() then
            notify("Installing LSP server: " server_name)
            server:install_sync(version)
        end
    end
end

but what I mentioned as well, is the ability to detect when all installations are complete, and as far as I can tell, we can rely on JobExecutionPool

on_done implementation

---@param server_identifiers string[]
local function ensure_installed(server_identifiers, on_done)
    local candidates = {}
    local JobExecutionPool = require "nvim-lsp-installer.jobs.pool"
    local job_pool = JobExecutionPool:new {
        size = settings.current.max_concurrent_installers,
    }
    for _, server_identifier in ipairs(server_identifiers) do
        local server_name, version = servers.parse_server_identifier(server_identifier)
        local ok, server = servers.get_server(server_name)
        if ok and not server:is_installed() then
            table.insert(candidates, server_name)
            -- server:install(version)
            job_pool:supply(function(cb)
                server:install_attached({
                    requested_server_version = requested_version,
                    -- there are probably more parameters needed..
                }, function(success)
                    candidates = candidates - 1
                    if candidates == 0 then
                        if type(on_done) == "function" then
                            on_done(success)
                        else
                            print "we're done!!"
                        end
                    end
                end)
            end)
        end
    end
    if #candidates > 0 then
        notify("Installing LSP servers: " .. table.concat(candidates, ", "))
    end
end

wdyt? there's probably a much cleaner way to write this, but hopefully you get the idea 😄

[williamboman]

I think we could utilize the async module for this, something along the lines of:

function ensure_installed(servers, on_done)
  local maybe_some_result = a.run_blocking(function()
      return a.wait_all(vim.tbl_map(function (server)
         return a.promisify(server.install)(server)
      end, servers))
  end)
  on_done(maybe_some_result)
end)

But I'm not following how this is related to these deprecations, or what the actual use case is?

But this sound unrelated to the

[Slotos]

I think my request kinda fits into this thread.

Installed servers will no longer automatically be set up for you, you will need to explicitly set them up via lspconfig in your config. If you're installing a brand new server, this means you'll have to make changes to your config and then restart neovim.

This is one of the selling points of lsp-installer for me. Yes, some servers can use extra configuration once I settle with them, but I can add a server and check if I want to stick with it without restarting neovim right now.

With a generic install/uninstall callback I'd be able to loop over the list of get_installed_servers to implement the same behaviour myself.

[neevek]

I have the following setup with on_server_ready where I can get the server object from the function argument. Where do I put the following code with the new API:

    if server.name == "rust_analyzer" then
      local opts = { ... some other opts ... }
      opts.settings = {
        ["rust-analyzer"] = {
          diagnostics = {
            disabled = { 'inactive-code' }
          }
        }
      }
      
      require("rust-tools").setup {
        server = vim.tbl_deep_extend("force", server:get_default_options(), opts),
      }
      server:attach_buffers()
      require("rust-tools").start_standalone_if_required()
    else
      server:setup(opts)
    end

[williamboman]

I pushed an example for rust-tools to the demo migration here: #635. In short, this is what you need:

local rust_tools = require("rust-tools")
rust_tools.setup {
    server = { on_attach = on_attach }
}

[neevek]

This works.
But I am curious that setting up rust-tools this way seems different in terms of timing of plugin loading from the old way, require('rust-tools') and its setup function will always be called when lspconfig is loaded even if it's not a rust file, am I right? with the old way there's a if statement to check for rust_analyzer server only. Will this cause unexpected performance hit?

[williamboman]

With the old way, it'd still always set up the rust-tools package. I haven't looked into rust-tools source too much but I'm confident that setting it up carries close to 0 overhead.

[AlexanderRichey]

I actually kind of liked the on_server_ready idea after I figured it out. I think people had difficulties with it because it wasn't obvious that server:setup{} actually calls lspconfig[server].setup{} with what you pass to server:setup{}. I know that this is indicated in the docs, but I missed it after copy/pasting some example code, before I actually read the docs.

Here's how I refactored my init.lua to deal with the deprecation. Hopefully this helps someone. It took me a bit to figure this out for myself. What I had working in the first place, after reading the docs and understanding what server:setup{} does, was this:

require'nvim-lsp-installer'.on_server_ready(function(server)
  server:setup({
    on_attach = function()
      nmap('gD', '<cmd>lua vim.lsp.buf.declaration()<CR>')
      nmap('gd', '<cmd>lua vim.lsp.buf.definition()<CR>')
      nmap('K', '<cmd>lua vim.lsp.buf.signature_help()<CR>')
      nmap('gi', '<cmd>lua vim.lsp.buf.implementation()<CR>')
      nmap('<space>D', '<cmd>lua vim.lsp.buf.type_definition()<CR>')
      nmap('<space>rn', '<cmd>lua vim.lsp.buf.rename()<CR>')
      nmap('<space>ca', '<cmd>lua vim.lsp.buf.code_action()<CR>')
      nmap('gr', '<cmd>lua vim.lsp.buf.references()<CR>')
      nmap('<space>e', '<cmd>lua vim.diagnostic.open_float()<CR>')
      nmap('<space>f', '<cmd>lua vim.lsp.buf.formatting()<CR>')
    end,

    flags = {
      debounce_text_changes = 150,
    },

    capabilities = require('cmp_nvim_lsp').update_capabilities(
      vim.lsp.protocol.make_client_capabilities()
    )
  })
end)

To get something like the same behavior (but without auto setup after installing new servers), I refactored to the following, which takes advantage of get_installed_servers():

local lspinstaller = require'nvim-lsp-installer'
local lspconfig = require'lspconfig'

lspinstaller.setup{}

local capabilities = vim.lsp.protocol.make_client_capabilities()

for _, server in ipairs(lspinstaller.get_installed_servers()) do
  lspconfig[server.name].setup{
    on_attach = function()
      nmap('gD', '<cmd>lua vim.lsp.buf.declaration()<CR>')
      nmap('gd', '<cmd>lua vim.lsp.buf.definition()<CR>')
      nmap('K', '<cmd>lua vim.lsp.buf.signature_help()<CR>')
      nmap('gi', '<cmd>lua vim.lsp.buf.implementation()<CR>')
      nmap('<space>D', '<cmd>lua vim.lsp.buf.type_definition()<CR>')
      nmap('<space>rn', '<cmd>lua vim.lsp.buf.rename()<CR>')
      nmap('<space>ca', '<cmd>lua vim.lsp.buf.code_action()<CR>')
      nmap('gr', '<cmd>lua vim.lsp.buf.references()<CR>')
      nmap('<space>e', '<cmd>lua vim.diagnostic.open_float()<CR>')
      nmap('<space>f', '<cmd>lua vim.lsp.buf.formatting()<CR>')
    end,

    flags = {
      debounce_text_changes = 150,
    },

    capabilities = require('cmp_nvim_lsp').update_capabilities(capabilities)
  }
end

If you have a bunch of custom configurations, I can see why spelling out each server explicitly would be better than doing it all in a loop as I do.

[btstream]

This does not work with automatic_installation=true

[fooage]

I find that on_attach and capabilities should be set by @AlexanderRichey's way, but some options for installer itself like ui and install_root_dir could be the params in lsp_installer.setup(). It seems that global overloading of handler is not currently supported.

lsp_installer.setup({
  -- A list of servers to automatically install if they're not already installed. Example: { "rust_analyzer", "sumneko_lua" }
  -- This setting has no relation with the `automatic_installation` setting.
  ensure_installed = {},

  ui = {
    -- some settings for ui
  },

  -- The directory in which to install all servers.
  install_root_dir = vim.fn.stdpath("data") .. "/lsp_servers",
})


-- Alternatively, you may also register handlers on specific server instances
-- instead (see example below).
for _, server in ipairs(lsp_installer.get_installed_servers()) do
  lsp_config[server.name].setup {
    -- set on_attach and capabilities handler for each server
    on_attach = require("lsp.handlers").on_attach,
    capabilities = require("lsp.handlers").capabilities,
  }
end

require("lsp.handlers").setup()

And it really does not work with automatic_installation=true. Is there any global setup solution for automatic installation?

[akim-13]

Is there a way to suppress this suggestion every time nvim is launched?

[williamboman]

Hello! I've temporarily removed the notices shown when starting neovim. Note that this method is still deprecated, but until a substitute of its behaviors are available it will remain and no notices will be shown.

[kylo252]

@williamboman, how about using vim.deprecate() or vim.notify_once(), and maybe combine it with the creation of a marker file that the function has fired at least once and shouldn't complain again until that file is deleted?

[williamboman]

Ah cool didn't know vim.deprecate was a thing. Looks like it's in HEAD only, so will hold off on using it until after next release.

Yeah I thought about keeping state for viewed and "acked" notices, but there's just too much ceremony around implementing that on a plugin level.

[mattr-]

Installed servers will no longer automatically be set up for you, you will need to explicitly set them up via
lspconfig in your config. If you're installing a brand new server, this means you'll have to make changes to your
config and then restart neovim.

This was exactly why I chose to move my config over to this plugin. Is there a way to emulate this functionality with extra config without having to configure every server manually?

[williamboman]

Hello! I wasn't sure how much value those parts actually added, I only ever saw negativity around the way it was implemented (which I can totally agree with) so I decided to start to completely get rid of it (deprecation being step 1). I'll have to rethink how to do it in a way that is less intrusive and not try to hijack the setup process itself.

In the meantime, I've reverted the notifications until a substitute is available! So feel free to keep whatever you had before until something else comes along!

[mattr-]

Thanks! I'm excited to see what happens in the future and appreciate you being so open to feedback. ❤️

[shibotto]

Sorry, but I've been stuck on this migration for hours and I need help. Right now I'm more or less at:

use {
	"williamboman/nvim-lsp-installer",
	"neovim/nvim-lspconfig",

	config = function()
		require("nvim-lsp-installer").setup {}

		local lspconfig = require("lspconfig")
		lspconfig.pyright.setup {}
	end
}

:LspPrintInstalled reports pyright to be there, however it doesn't get attached to any Python buffer. I'm sure I misinterpreted something but I really can't figure out what it is. Could you please point me in the right direction?

[bryant-the-coder]

@shibotto take a look at
my lsp config file
lsp_installer config file

[williamboman]

Have you recompiled Packer after making the changes? :PackerCompile

[shibotto]

Sorry for the late reply and thank you both. I think don't understand how Packer and lua itself work yet, but I remade the config like this

use { "williamboman/nvim-lsp-installer" }
use {
	"neovim/nvim-lspconfig",

	config = function()
		require("nvim-lsp-installer").setup {}

		local lspconfig = require("lspconfig")
		lspconfig.pyright.setup {}
	end
}

, reinstalled the servers (most likely unnecessary) and now it works fine 😃

Maybe I could do a better job and take a look at requires= and after=, but... *insert lazy.gif*

Have you recompiled Packer after making the changes? :PackerCompile

Since I have the habit of putting everything in config=, recompiling Packer kinda became muscle memory by now 👍🤣

[ta3pks]

this really seems too much work for not much benefit i think i will be simply using old config and nvim-lsp-installer instead of mason and simply use the old global install method without the installer we had a good run tho thanks for this plugin its sad to see it go this way

[Cyberlane]

Tjena tjena :)

I am looking into migrating my config over to mason but have one snippet that I am uncertain about how to solve...

  local lsp_installer = require'nvim-lsp-installer'
  lsp_installer.on_server_ready(function(server)
    local capabilities = require('cmp_nvim_lsp').update_capabilities(
      vim.lsp.protocol.make_client_capabilities()
    )
    local opts = {capabilities = capabilities}
    if language_servers[server.name] then
      opts = language_servers[server.name].config(opts)
    end
    server:setup(opts)
  end)

I've seen some mention of the capabilities part in earlier discussions above, but no clear answers from anybody.

I also haven't seen any discussion about the server param being used, so I would love your thoughts on how I should rewrite this? :)

[chancez]

A lot of people are having trouble switching from the old method, especially when using custom on_attach hooks. I've got a single commit where I adapted my config to use mason.nvim and I think it should help a lot of people:

Main thing to know that you can't see from the diff:

• I have a table of LSP servers in the local servers variable, keyed by name, and value contains parameters to the lspconfig setup() method.
• I iterate over servers, installing them if they are not installed, and then configure them.

To switch to mason:

• I get the keys from servers and pass that to ensure_installed in require("mason-lspconfig").setup({ ... })
• I use require("mason-lspconfig").setup_handlers to define a callback to invoke on with each server's name to do the per-server setup using lspconfig directly, as the mason-lspconfig documentation recommends.

The change (diff using Split View is easier to understand):
chancez/dotfiles@8257f38?diff=split

Unfortunately, mason.nvim isn't opening when it installs the servers, so there's no feedback when you open neovim it's doing anything. I'm still working on that.

[chancez]

https://github.com/chancez/dotfiles/compare/f3f92b9d40cfdb1b2f188863f7ede6563c7630ee...8257f38876e130f3e227932295cb40058c080049?diff=split is slightly better with the new commit, instead of using the handlers, I just loop over the servers like I used to, and set them up and use the mason automatic_installation option instead.