diff options
| author | William Boman <william@redwill.se> | 2022-07-06 19:41:43 +0200 |
|---|---|---|
| committer | William Boman <william@redwill.se> | 2022-07-07 00:39:59 +0200 |
| commit | 5f634e0c37e723fc0c33e06b4fd5c2180178db40 (patch) | |
| tree | fa4f09363adefa8259e23e4d1ea036db628b1243 /doc | |
| parent | feat(health): use stderr for java version, also check for JAVA_HOME (#765) (diff) | |
| download | mason-5f634e0c37e723fc0c33e06b4fd5c2180178db40.tar mason-5f634e0c37e723fc0c33e06b4fd5c2180178db40.tar.gz mason-5f634e0c37e723fc0c33e06b4fd5c2180178db40.tar.bz2 mason-5f634e0c37e723fc0c33e06b4fd5c2180178db40.tar.lz mason-5f634e0c37e723fc0c33e06b4fd5c2180178db40.tar.xz mason-5f634e0c37e723fc0c33e06b4fd5c2180178db40.tar.zst mason-5f634e0c37e723fc0c33e06b4fd5c2180178db40.zip | |
mason.nvim
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/mason.txt | 241 | ||||
| -rw-r--r-- | doc/nvim-lsp-installer.txt | 487 |
2 files changed, 241 insertions, 487 deletions
diff --git a/doc/mason.txt b/doc/mason.txt new file mode 100644 index 00000000..e698a006 --- /dev/null +++ b/doc/mason.txt @@ -0,0 +1,241 @@ +*mason.nvim* + +Minimum version of neovim: 0.7.0 + +Author: William Boman + +============================================================================== +INTRODUCTION *mason-introduction* + +`mason.nvim` is a Neovim plugin that allow you to easily manage external +editor tooling such as LSP servers, DAP servers, linters, and formatters +through a single interface. It runs everywhere Neovim runs (across Linux, +macOS, Windows, etc.), with only a small set of [external +requirements](#requirements) needed. + +Packages are installed to Neovim's `:h stdpath` by default. Executables are +linked to a single `bin/` directory, which `mason.nvim` will add to the +Neovim's PATH during setup, allowing easy access for the builtin +shell/terminal as well as other 3rd party plugins. + +============================================================================== +REQUIREMENTS *mason-requirements* + +`mason.nvim` relaxes the minimum requirements by attempting multiple different +utilities (for example, `wget`, `curl`, and `Invoke-WebRequest` are all +perfect substitutes). The _minimum_ recommended requirements are: + +- neovim `>= 0.7.0` +- For Unix systems: `git(1)`, `curl(1)` or `wget(1)`, `unzip(1)`, `tar(1)`, + `gzip(1)` +- For Windows systems: powershell, git, tar, and 7zip or peazip or archiver + or winzip or WinRAR + +Note that `mason.nvim` will regularly shell out to external package managers, +such as `cargo` and `npm`. Depending on your personal usage, some of these +will also need to be installed. Refer to `:checkhealth mason` for a full list. + +============================================================================== +QUICK START *mason-quickstart* + +The only thing needed to get started with mason.nvim is to make sure +to call the `setup()` function: + + require("mason").setup {} + +This will enhance the Neovim session's PATH environment with the location of +executables installed with mason.nvim. + +To view the UI for mason, run: + :Mason + +Install a package via `:MasonInstall`, for example: + :MasonInstall stylua + +You may also install multiple languages at a time: + :MasonInstall stylua lua-language-server + +To install a specific version of a package, you may provide it as part of the +package name, like so: + + :MasonInstall rust-analyzer@nightly + +Please refer to each package's own release pages to find which versions are +available. + +============================================================================== +COMMANDS *mason-commands* + + *:Mason* +:Mason + +Opens the graphical status window. + + *:MasonInstall* +:MasonInstall <package> ... + +Installs the provided packages. + + *:MasonUninstall* +:MasonUninstall <package> ... + +Uninstalls the provided packages. + + *:MasonUninstallAll* +:MasonUninstallAll + +Uninstalls all installed packages. + + *:MasonLog* +:MasonLog + +Opens the log file in a new tab window. + +============================================================================== +SETTINGS *mason-settings* + +You can configure certain behavior of mason when calling the `.setup()` +function. + +Refer to the |mason-default-settings| for all available settings. + +Example: + + require("mason").setup({ + ui = { + icons = { + package_installed = "✓", + package_pending = "➜", + package_uninstalled = "✗" + } + } + }) + + *mason-default-settings* + + local DEFAULT_SETTINGS = { + ui = { + -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|. + border = "none", + + icons = { + -- The list icon to use for installed packages. + package_installed = "◍", + -- The list icon to use for packages that are installing, or queued for installation. + package_pending = "◍", + -- The list icon to use for packages that are not installed. + package_uninstalled = "◍", + }, + + keymaps = { + -- Keymap to expand a package + toggle_package_expand = "<CR>", + -- Keymap to install the package under the current cursor position + install_package = "i", + -- Keymap to reinstall/update the package under the current cursor position + update_package = "u", + -- Keymap to check for new version for the package under the current cursor position + check_package_version = "c", + -- Keymap to update all installed packages + update_all_packages = "U", + -- Keymap to check which installed packages are outdated + check_outdated_packages = "C", + -- Keymap to uninstall a package + uninstall_package = "X", + -- Keymap to cancel a package installation + cancel_installation = "<C-c>", + -- Keymap to apply language filter + apply_language_filter = "<C-f>", + }, + }, + + -- The directory in which to install packages. + install_root_dir = path.concat { vim.fn.stdpath "data", "mason" }, + + pip = { + -- These args will be added to `pip install` calls. Note that setting extra args might impact intended behavior + -- and is not recommended. + -- + -- Example: { "--proxy", "https://proxyserver" } + install_args = {}, + }, + + -- Controls to which degree logs are written to the log file. It's useful to set this to vim.log.levels.DEBUG when + -- debugging issues with server installations. + log_level = vim.log.levels.INFO, + + -- Limit for the maximum amount of servers to be installed at the same time. Once this limit is reached, any further + -- servers that are requested to be installed will be put in a queue. + max_concurrent_installers = 4, + + github = { + -- The template URL to use when downloading assets from GitHub. + -- The placeholders are the following (in order): + -- 1. The repository (e.g. "rust-lang/rust-analyzer") + -- 2. The release version (e.g. "v0.3.0") + -- 3. The asset name (e.g. "rust-analyzer-v0.3.0-x86_64-unknown-linux-gnu.tar.gz") + download_url_template = "https://github.com/%s/releases/download/%s/%s", + }, + } + +============================================================================== +DOWNLOAD MIRRORS *mason-download-mirrors* + +------------------------------------------------------------------------------ +GITHUB MIRROR *mason-download-mirror-github* + + It's possible to customize the download URL used when downloading assets + from GitHub releases by setting the `github.download_url_template` + settings during setup, like so: + + require("mason").setup { + github = { + -- The template URL to use when downloading assets from GitHub. + -- The placeholders are the following (in order): + -- 1. The repository (e.g. "rust-lang/rust-analyzer") + -- 2. The release version (e.g. "v0.3.0") + -- 3. The asset name (e.g. "rust-analyzer-v0.3.0-x86_64-unknown-linux-gnu.tar.gz") + download_url_template = "https://my.mirror.com/%s/releases/download/%s/%s", + }, + } + + +============================================================================== +INSTALLATION ERRORS *mason-errors* + + *mason-errors-github-api* +For some installers, the GitHub API is used to fetch information about +releases. This API imposes a rate limit that may be triggered, causing +installations to fail. The reasons why a rate limit is triggered are many, for +example being behind a public API, or using other software that also send +requests to the GitHub API. + +To circumvent this, mason will utilize the GitHub CLI when +available, leading to API requests being subject to a much higher rate limit +threshold when authenticated. Should you run into errors with communicating +with GitHub's API, it's recommended to install, and authenticate, the GitHub +CLI: https://cli.github.com/. + +============================================================================== +DEBUGGING *mason-debugging* + +To help with debugging issues with installing/uninstalling packages, please +make sure to set mason's log level to DEBUG or TRACE, like so: + + require("mason").setup { + log_level = vim.log.levels.DEBUG + } + +You may find the logs by entering the command `:MasonLog`. Providing the +contents of this file when reporting an issue will help tremendously. Remember +to redo whatever is failing after changing the log level in order to capture +new log entries. + +============================================================================== +Lua module: mason + + *mason.setup()* +setup({config}) + Sets up mason with the provided {config} (see |mason-settings|). + + vim:tw=78:ft=help:norl:expandtab:sw=4 diff --git a/doc/nvim-lsp-installer.txt b/doc/nvim-lsp-installer.txt deleted file mode 100644 index a769166b..00000000 --- a/doc/nvim-lsp-installer.txt +++ /dev/null @@ -1,487 +0,0 @@ -*nvim-lsp-installer* - -Minimum version of neovim: 0.7.0 - -Author: William Boman - -============================================================================== -INTRODUCTION *nvim-lsp-installer-introduction* - -Neovim plugin that allow you to manage LSP servers (servers are installed -inside `stdpath("data")` by default). It works in tandem with -nvim-lspconfig[1] by registering a hook that enhances the `PATH` environment -variable, allowing neovim's LSP client to locate the server executable -installed by nvim-lsp-installer.[2] - -On top of just providing commands for installing & uninstalling LSP servers, it: - -- provides a graphical UI -- provides the ability to check for, and upgrade to, new server versions through a single interface -- supports installing custom versions of LSP servers (for example `:LspInstall rust_analyzer@nightly`) -- relaxes the minimum requirements by attempting multiple different utilities (for example, only one of `wget`, `curl`, or `Invoke-WebRequest` is required for HTTP requests) -- hosts a suite of system tests for all supported servers -- has full support for Windows - -[1] https://github.com/neovim/nvim-lspconfig - While lspconfig is the main target, this plugin may also be used for other - use cases. -[2] Some servers don't provide an executable, in which case the full command - to spawn the server is provided instead. - -============================================================================== -REQUIREMENTS *nvim-lsp-installer-requirements* - -Requires neovim `>= 0.7.0` and [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig). - - *nvim-lsp-installer-requirements-minimum* -The minimum recommended requirements are: - -- For Unix systems: git(1), curl(1) or wget(1), unzip(1), tar(1), gzip(1) -- For Windows systems: powershell, git, tar, and 7zip or peazip or archiver or winzip or WinRAR - - *nvim-lsp-installer-requirements-additional* -Additional requirements to install & run all servers are (depending on usage): - -- Node.js (LTS) & npm -- Python3 & pip3 -- go >= 1.17 -- cargo -- Ruby & gem -- PHP & Composer -- JDK -- Julia -- dotnet -- ghcup -- luarocks -- meson -- ninja -- pwsh -- rebar3 -- valac - -============================================================================== -QUICK START *nvim-lsp-installer-quickstart* - -The only thing needed to get started with nvim-lsp-installer is to make sure -to call the `setup()` function _before_ you set up any servers: - - require("nvim-lsp-installer").setup {} - - -Next, in your initialization files |init.lua|, setup the servers you want to use. -Refer to |lspconfig| for more information! For example: - - require("nvim-lsp-installer").setup {} - local lspconfig = require("lspconfig") - - local function on_attach(client, bufnr) - -- set up buffer keymaps, etc. - end - - lspconfig.sumneko_lua.setup { on_attach = on_attach } - lspconfig.tsserver.setup { on_attach = on_attach } - - -To view the UI for nvim-lsp-installer, run: - - :LspInstallInfo - - -Install a language server via `:LspInstall`, for example: - - :LspInstall tsserver - - -You may also install multiple languages at a time: - - :LspInstall tsserver graphql rust_analyzer - - -To install a specific version of a language server, you may provide it as part -of the server name, like so: - - :LspInstall tsserver@0.6.3 graphql@latest rust_analyzer@nightly - - -To install a server associated with the filetype of the currently opened -buffer, simply just run: - - :LspInstall - - -Please refer to each server's own release page to find which versions are available. - -============================================================================== -COMMANDS *nvim-lsp-installer-commands* - - *:LspInstallInfo* -:LspInstallInfo - -Opens the UI for nvim-lsp-installer. - - *:LspInstall* -:LspInstall [--sync] [server_name] ... - -Installs language servers. If the `--sync` argument is passed, the command will -be blocking until all installations complete. This is useful for headless -installations, for example: - - $ nvim --headless -c "LspInstall --sync rust_analyzer clangd clojure_lsp" -c q - - -If no server names are provided (`:LspInstall`), you will be prompted to -select which server associated with the currently opened buffer's filetype you -want to install. If none are associated, an error message will be printed -instead. - - *:LspUninstall* -:LspUninstall [--sync] {server_name} ... - -Uninstalls language servers. If the `--sync` argument is passed, the command will -be blocking until all installations complete. This is useful for headless -installations, for example: - - $ nvim --headless -c "LspUninstall --sync rust_analyzer clangd clojure_lsp" -c q - - - *:LspUninstallAll* -:LspUninstallAll [--no-confirm] - -Uninstalls all installed language servers. If the --no-confirm argument is -passed, there will be no confirmation prompt before uninstalling all servers. - - *:LspInstallLog* -:LspInstallLog - -Opens the log file in a new tab window. - - *:LspPrintInstalled* -:LspPrintInstalled - -Prints all installed language servers. - - -============================================================================== -SETTINGS *nvim-lsp-installer-settings* - -You can configure certain behavior of nvim-lsp-installer when calling the -`.setup()` function. - -Refer to the |nvim-lsp-installer-default-settings| for all available settings. - -Example: - - require("nvim-lsp-installer").setup({ - automatic_installation = true, -- automatically detect which servers to install (based on which servers are set up via lspconfig) - ui = { - icons = { - server_installed = "✓", - server_pending = "➜", - server_uninstalled = "✗" - } - } - }) - - *nvim-lsp-installer-default-settings* - -The following settings are applied by default. - - local DEFAULT_SETTINGS = { - -- 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 = {}, - - -- Whether servers that are set up (via lspconfig) should be automatically installed if they're not already installed. - -- This setting has no relation with the `ensure_installed` setting. - -- Can either be: - -- - false: Servers are not automatically installed. - -- - true: All servers set up via lspconfig are automatically installed. - -- - { exclude: string[] }: All servers set up via lspconfig, except the ones provided in the list, are automatically installed. - -- Example: automatic_installation = { exclude = { "rust_analyzer", "solargraph" } } - automatic_installation = false, - - ui = { - -- Whether to automatically check for outdated servers when opening the UI window. - check_outdated_servers_on_open = true, - - -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|. - border = "none", - - icons = { - -- The list icon to use for installed servers. - server_installed = "◍", - -- The list icon to use for servers that are pending installation. - server_pending = "◍", - -- The list icon to use for servers that are not installed. - server_uninstalled = "◍", - }, - keymaps = { - -- Keymap to expand a server in the UI - toggle_server_expand = "<CR>", - -- Keymap to install the server under the current cursor position - install_server = "i", - -- Keymap to reinstall/update the server under the current cursor position - update_server = "u", - -- Keymap to check for new version for the server under the current cursor position - check_server_version = "c", - -- Keymap to update all installed servers - update_all_servers = "U", - -- Keymap to check which installed servers are outdated - check_outdated_servers = "C", - -- Keymap to uninstall a server - uninstall_server = "X", - }, - }, - - -- The directory in which to install all servers. - install_root_dir = path.concat { vim.fn.stdpath "data", "lsp_servers" }, - - pip = { - -- These args will be added to `pip install` calls. Note that setting extra args might impact intended behavior - -- and is not recommended. - -- - -- Example: { "--proxy", "https://proxyserver" } - install_args = {}, - }, - - -- Controls to which degree logs are written to the log file. It's useful to set this to vim.log.levels.DEBUG when - -- debugging issues with server installations. - log_level = vim.log.levels.INFO, - - -- Limit for the maximum amount of servers to be installed at the same time. Once this limit is reached, any further - -- servers that are requested to be installed will be put in a queue. - max_concurrent_installers = 4, - - github = { - -- The template URL to use when downloading assets from GitHub. - -- The placeholders are the following (in order): - -- 1. The repository (e.g. "rust-lang/rust-analyzer") - -- 2. The release version (e.g. "v0.3.0") - -- 3. The asset name (e.g. "rust-analyzer-v0.3.0-x86_64-unknown-linux-gnu.tar.gz") - download_url_template = "https://github.com/%s/releases/download/%s/%s", - }, - } - - -============================================================================== -DOWNLOAD MIRRORS *nvim-lsp-installer-download-mirrors* - ------------------------------------------------------------------------------- -GITHUB MIRROR *nvim-lsp-installer-download-mirror-github* - - It's possible to customize the download URL used when downloading assets - from GitHub releases by setting the `github.download_url_template` - settings during setup, like so: - - require("nvim-lsp-installer").setup { - github = { - -- The template URL to use when downloading assets from GitHub. - -- The placeholders are the following (in order): - -- 1. The repository (e.g. "rust-lang/rust-analyzer") - -- 2. The release version (e.g. "v0.3.0") - -- 3. The asset name (e.g. "rust-analyzer-v0.3.0-x86_64-unknown-linux-gnu.tar.gz") - download_url_template = "https://my.mirror.com/%s/releases/download/%s/%s", - }, - } - - -============================================================================== -INSTALLATION ERRORS *nvim-lsp-installer-errors* - - *nvim-lsp-installer-errors-github-api* -For some installers, the GitHub API is used to fetch information about -releases. This API imposes a rate limit that may be triggered, causing -installations to fail. The reasons why a rate limit is triggered are many, for -example being behind a public API, or using other software that also send -requests to the GitHub API. - -To circumvent this, nvim-lsp-installer will utilize the GitHub CLI when -available, leading to API requests being subject to a much higher rate limit -threshold when authenticated. Should you run into errors with communicating -with GitHub's API, it's recommended to install, and authenticate, the GitHub -CLI: https://cli.github.com/. - -============================================================================== -DEBUGGING *nvim-lsp-installer-debugging* - -To help with debugging issues with installing/uninstall servers, please make -sure to set nvim-lsp-installer's log level to DEBUG or TRACE, like so: - - require("nvim-lsp-installer").setup { - log_level = vim.log.levels.DEBUG - } - -You may find the logs by entering the command `:LspInstallLog`. Providing the -contents of this file when reporting an issue will help tremendously. Remember -to redo whatever is failing after changing the log level in order to capture -new log entries. - -============================================================================== -Lua module: nvim-lsp-installer - - *nvim-lsp-installer.setup()* -setup({config}) - Sets up nvim-lsp-installer with the provided {config} (see - |nvim-lsp-installer-settings|). - - *nvim-lsp-installer.install()* -install({server_name}) - Installs the provided {server_name}. If {server_name} is already - installed, it is reinstalled. Note that you may also provide the - desired version of the server here, through the @version notation, for - example `"rust_analyzer@nightly"`. - - This will also open the `:LspInstallInfo` UI window. To install a - server without opening the window, see |nvim-lsp-installer.Server|. - - Parameters: ~ - {server_name} (string) The server to install. - - *nvim-lsp-installer.uninstall()* -uninstall({server_name}) - Uninstalls the provided {server_name}. - - Parameters: ~ - {server_name} (string) The server to uninstall. - - *nvim-lsp-installer.on_server_ready()* -on_server_ready({cb}) - DEPRECATED - setup servers directly via lspconfig instead - - Registers a callback to be executed each time a server is ready to be - initiated. - - When called, all currently installed servers will be considered ready - to be initiated and will each individually be invoked on {cb}. - - Parameters: ~ - {cb} (function) Function to be invoked when a server is ready to - be initiated. - - Return: ~ - Returns a function which when called will de-register the {cb} - from any future dispatches. - - *nvim-lsp-installer.info_window.open()* -info_window.open() - Opens the `:LspInstallInfo` UI window. - - *nvim-lsp-installer.info_window.close()* -info_window.close() - Closes the `:LspInstallInfo` UI window. - - *nvim-lsp-installer.get_available_servers()* -get_available_servers() - Return: ~ - |lsp_installer.Server|[] A list containing all available language servers. - - *nvim-lsp-installer.get_installed_servers()* -get_installed_servers() - Return: ~ - |lsp_installer.Server|[] A list of servers that are currently installed. - - *nvim-lsp-installer.get_uninstalled_servers()* -get_uninstalled_servers() - Return: ~ - |lsp_installer.Server|[] A list of servers that are not installed. - - *nvim-lsp-installer.register()* -register({server}) - Registers a {server} instance with nvim-lsp-installer. - - {server} must be an instance of |lsp_installer.Server|. - - Parameters: ~ - {server} (|lsp_installer.Server|) The server to register. - - *nvim-lsp-installer.get_server()* -get_server({server_name}) - Parameters: ~ - {server_name} (string) The server instance to retrieve. - - Return: ~ - ok: boolean, server: |lsp_installer.Server| - - Example: ~ - local lsp_installer = require'nvim-lsp-installer' - local ok, rust_server = lsp_installer.get_server("rust_analyzer") - if ok then - rust_server:install() - end - - -============================================================================== -Lua module: nvim-lsp-installer.server *nvim-lsp-installer.server* - - *nvim-lsp-installer.Server* -class: Server - This class enables installing, uninstalling, and setting up language - servers. - - Methods: ~ - - setup({opts}) - DEPRECATED - setup servers directly via lspconfig instead - - Sets up the language server and attaches all open buffers. - - See: - - setup_lsp({opts}) - - attach_buffers() - - Parameters: ~ - {opts} (table) The lspconfig server configuration. - See https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md - - - setup_lsp({opts}) - DEPRECATED - setup servers directly via lspconfig instead - - Sets up the language server via lspconfig. - This function has the same signature as the setup function - in nvim-lspconfig. - - Parameters: ~ - {opts} (table) The lspconfig server configuration. - See https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md - - - attach_buffers() - DEPRECATED - setup servers directly via lspconfig instead - - Attaches this server to all current open buffers with a - 'filetype' that matches the server's configured filetypes. - - - get_default_options() - Returns a deep copy of the default options provided to - lspconfig in the setup({opts}) method. - Note: These only include the options provided by - nvim-lsp-installer, and not the default options provided - by lspconfig. - - - on_ready({handler}) - DEPRECATED - setup servers directly via lspconfig instead - - Registers the provided {handler} to be called when the - server is ready to be setup. - - Make sure not to use this method as well as the - "catch-all" |nvim-lsp-installer.on_server_ready()| - function to setup servers, as this would cause servers to - be set up more than once. - - Parameters: ~ - {handler} (function) Function to be called when the - server is ready. - - - is_installed() - Returns {true} is server is installed, else returns {false}. - - - install({version}) - Installs this instance of an LSP server. - - Parameters: ~ - {version} (string|nil) The version of the server to - install. If nil, the latest version will be installed. - - - uninstall() - Uninstalls this instance of an LSP server. - - vim:tw=78:ft=help:norl:expandtab:sw=4 |
