==============================================================================
Table of Contents *rustaceanvim.contents*
Introduction ·············································· |rustaceanvim.intro|
································································ |rustaceanvim|
plugin configuration ····································· |rustaceanvim.config|
LSP configuration utility ························· |rustaceanvim.config.server|
························································ |rustaceanvim.neotest|
···························································· |rustaceanvim.dap|
==============================================================================
Introduction *rustaceanvim.intro*
This plugin automatically configures the `rust-analyzer` builtin LSP client
and integrates with other rust tools.
==============================================================================
*rustaceanvim*
Commands:
*:RustAnalyzer*
':RustAnalyzer start' - Start the LSP client.
':RustAnalyzer stop' - Stop the LSP client.
':RustAnalyzer restart' - Restart the LSP client.
':RustAnalyzer reloadSettings' - Reload settings for the LSP client.
':RustAnalyzer target <target_arch>' - Set the target architecture for the LSP client.
':RustAnalyzer config <lua_table>' - Configure rust-analyzer on the fly.
Takes a Lua table as an argument.
Example: `:RustAnalyzer config { checkOnSave = false }`
WARNING: This command does not validate the Lua config table.
The ':RustAnalyzer target' command can take a valid rustc target,
such as 'wasm32-unknown-unknown', or it can be left empty to set the LSP client
to use the default target architecture for the operating system.
*:RustLsp*
The ':RustLsp[!]' command is available after the LSP client has initialized.
It accepts the following subcommands:
'runnables {args[]}?' - Run tests, executables, etc.
':RustLsp!' means run the last runnable (ignores any args).
`args[]` allows you to override the executable's arguments.
'run {args[]}?' - Like 'runnables', but runs the target at the current cursor position.
'debuggables {args[]}?' - Debug tests, executables, etc. (requires |nvim-dap|).
':RustLsp!' means run the last debuggable (ignores any args).
`args[]` allows you to override the executable's arguments.
'debug {args[]}?' - Like 'debuggables', but debugs the target at the current cursor position.
'testables {args[]}?' - Run tests
':RustLsp!' means run the last testable (ignores any args).
`args[]` allows you to override the executable's arguments.
'relatedTests' - Open the tests rust-analyzer associates with the symbol under the cursor.
'expandMacro {float?|horizontal?|vertical?}' - Expand macros recursively.
'moveItem {up|down}' - Move items up or down.
'codeAction' - Sometimes, rust-analyzer groups code actions by category,
which is not supported by Neovim's built-in |vim.lsp.buf.codeAction|.
This command provides a command with a UI that does.
If you set the option `vim.g.rustaceanvim.tools.code_actions.ui_select_fallback`
to `true` (defaults to `false`), it will fall back to |vim.ui.select|
if there are no grouped code actions.
'hover {actions|range}' - Hover actions, or hover over visually selected range.
You can invoke a hover action by switching to the hover window and entering `<CR>`
on the respective line, or with a keymap for the `<Plug>RustHoverAction` mapping,
which accepts a `<count>` prefix as the (1-based) index of the hover action to invoke.
For example, if you set the keymap: `vim.keymap.set('n', '<space>a', '<Plug>RustHoverAction')`,
you can invoke the third hover action with `3<space>a`.
'explainError {cycle?|cycle_prev?|current?}' - Display a hover window with explanations from the Rust error index.
- If called with |cycle| or no args:
Like |vim.diagnostic.goto_next|,
|explainError| will cycle diagnostics,
starting at the cursor position,
until it can find a diagnostic with an error code.
- If called with |cycle_prev|:
Like |vim.diagnostic.goto_prev|,
searches backwards for a diagnostic with an error code.
- If called with |current|:
Searches for diagnostics only in the
current cursor line.
'renderDiagnostic {cycle?|cycle_prev?|current?}' - Display a hover window with the rendered diagnostic,
as displayed during |cargo build|.
- If called with |cycle| or no args:
Like |vim.diagnostic.goto_next|,
|renderDiagnostic| will cycle diagnostics,
starting at the cursor position,
until it can find a diagnostic with rendered data.
- If called with |cycle_prev|:
Like |vim.diagnostic.goto_prev|,
searches backwards for a diagnostic with rendered data.
- If called with |current|:
Searches for diagnostics only in the
current cursor line.
'relatedDiagnostics' - Jump to diagnostics that are related to the one under the cursor.
If more than one diagnostic is found, this will populate and open
the quickfix list.
'openCargo' - Open the Cargo.toml file for the current package.
'openDocs' - Open docs.rs documentation for the symbol under the cursor.
'parentModule' - Open the current module's parent module.
'workspaceSymbol {onlyTypes?|allSymbols?} {query?}'
Filtered workspace symbol search.
When run with a bang (`:RustLsp! workspaceSymbol ...`),
rust-analyzer will include dependencies in the search.
You can also configure rust-analyzer so that |vim.lsp.buf.workspace_symbol|
supports filtering (with a # suffix to the query) or searching dependencies.
'joinLines' - Join adjacent lines.
'ssr {query}' - Structural search and replace.
Searches the entire buffer in normal mode.
Searches the selected region in visual mode.
'crateGraph {backend}' - Create and view a crate graph with graphviz.
'syntaxTree' - View the syntax tree.
'view {mir|hir}' - View MIR or HIR.
'flyCheck' {run?|clear?|cancel?}
- Run `cargo check` or another compatible command (f.x. `clippy`)
in a background thread and provide LSP diagnostics based on
the output of the command.
Useful in large projects where running `cargo check` on each save
can be costly.
Defaults to `flyCheck run` if called without an argument.
'logFile' - Open the rust-analyzer log file.
*:Rustc*
The ':Rustc' command can be used to interact with rustc.
It accepts the following subcommands:
'unpretty {args[]}' - Opens a buffer with a textual representation of the MIR or others things,
of the function closest to the cursor.
Achieves an experience similar to Rust Playground.
NOTE: This currently requires a tree-sitter parser for Rust,
and a nightly compiler toolchain.
==============================================================================
plugin configuration *rustaceanvim.config*
rustaceanvim is a filetype plugin, and does not need
a `setup` function to work.
To configure rustaceanvim, set the variable `vim.g.rustaceanvim`,
which is a |rustaceanvim.Opts| table, in your neovim configuration.
Example:
>lua
---@type rustaceanvim.Opts
vim.g.rustaceanvim = {
---@type rustaceanvim.tools.Opts
tools = {
-- ...
},
---@type rustaceanvim.lsp.ClientOpts
server = {
on_attach = function(client, bufnr)
-- Set keybindings, etc. here.
end,
default_settings = {
-- rust-analyzer language server configuration
['rust-analyzer'] = {
},
},
-- ...
},
---@type rustaceanvim.dap.Opts
dap = {
-- ...
},
}
<
Notes:
- `vim.g.rustaceanvim` can also be a function that returns a |rustaceanvim.Opts| table.
- You can also configure the rust-analyzer LSP client via |vim.lsp.config()|
(using the `'*'` or `'rust-analyzer'` key).
rustaceanvim.Opts *rustaceanvim.Opts*
Fields: ~
{tools?} (rustaceanvim.tools.Opts)
Plugin options.
{server?} (rustaceanvim.lsp.ClientOpts)
Language server client options.
Some fields can also be set using |vim.lsp.config()| for "rust-analyzer" or "*".
If both the `server` table and a `vim.lsp.config["rust-analyzer"]` are defined,
rustaceanvim merges |vim.lsp.config()| settings into the `server` table,
giving them precedence over existing settings.
Note that |vim.lsp.config()| expects a |vim.lsp.ClientConfig|.
Although you can also pass in |rustaceanvim.lsp.ClientOpts|, doing so is not
officially supported and may not be possible in the future.
{dap?} (rustaceanvim.dap.Opts)
Debug adapter options
rustaceanvim.tools.Opts *rustaceanvim.tools.Opts*
Fields: ~
{executor?} (rustaceanvim.Executor|rustaceanvim.executor_alias)
The executor to use for runnables/debuggables
{test_executor?} (rustaceanvim.Executor|rustaceanvim.test_executor_alias)
The executor to use for runnables that are tests / testables
{crate_test_executor?} (rustaceanvim.Executor|rustaceanvim.test_executor_alias)
The executor to use for runnables that are crate test suites (--all-targets)
{cargo_override?} (string)
Set this to override the 'cargo' command for runnables, debuggables (etc., e.g. to 'cross').
If set, this takes precedence over 'enable_nextest'.
{enable_nextest?} (boolean)
Whether to enable nextest. If enabled, `cargo test` commands will be transformed to `cargo nextest run` commands.
Defaults to `true` if cargo-nextest is detected. Ignored if `cargo_override` is set.
{enable_clippy?} (boolean)
Whether to enable clippy checks on save if a clippy installation is detected.
Default: `true`
{on_initialized?} (fun(health:rustaceanvim.RAInitializedStatus,client_id:integer))
Function that is invoked when the LSP server has finished initializing
{reload_workspace_from_cargo_toml?} (boolean)
Automatically call `RustReloadWorkspace` when writing to a Cargo.toml file
{code_actions?} (rustaceanvim.code-action.Opts) Options for code actions
{float_win_config?} (rustaceanvim.FloatWinConfig)
Options applied to floating windows.
See |api-win_config|.
{create_graph?} (rustaceanvim.crate-graph.Opts)
Options for showing the crate graph based on graphviz and the dot
{open_url?} (fun(url:string):nil)
If set, overrides how to open URLs
{rustc?} (rustaceanvim.rustc.Opts)
Options for `rustc`
rustaceanvim.Executor *rustaceanvim.Executor*
Fields: ~
{execute_command} (fun(cmd:string,args:string[],cwd:string|nil,opts?:rustaceanvim.ExecutorOpts))
rustaceanvim.ExecutorOpts *rustaceanvim.ExecutorOpts*
Fields: ~
{bufnr?} (integer)
The buffer from which the executor was invoked.
{env?} (table<string,string>) The environment variables to set for the command.
rustaceanvim.FloatWinConfig *rustaceanvim.FloatWinConfig*
Fields: ~
{auto_focus?} (boolean)
{open_split?} ("horizontal"|"vertical")
See: ~
|vim.lsp.util.open_floating_preview.Opts|
|vim.api.nvim_open_win|
rustaceanvim.executor_alias *rustaceanvim.executor_alias*
Type: ~
"termopen"|"quickfix"|"toggleterm"|"vimux"
rustaceanvim.test_executor_alias *rustaceanvim.test_executor_alias*
Type: ~
rustaceanvim.executor_alias|"background"|"neotest"
rustaceanvim.code-action.Opts *rustaceanvim.code-action.Opts*
Fields: ~
{group_icon?} (string)
Text appended to a group action
{ui_select_fallback?} (boolean)
Whether to fall back to `vim.ui.select` if there are no grouped code actions.
Default: `false`
{keys} (rustaceanvim.code-action.Keys)
rustaceanvim.code-action.Keys *rustaceanvim.code-action.Keys*
Fields: ~
{confirm?} (string|string[])
The key or keys with which to confirm a code action
Default: `"<CR>"`.
{quit?} (string)
The key or keys with which to close a code action window
Default: `{ "q", "<Esc>" }`.
rustaceanvim.lsp_server_health_status *rustaceanvim.lsp_server_health_status*
Type: ~
"ok"|"warning"|"error"
rustaceanvim.RAInitializedStatus *rustaceanvim.RAInitializedStatus*
Fields: ~
{health} (rustaceanvim.lsp_server_health_status)
rustaceanvim.crate-graph.Opts *rustaceanvim.crate-graph.Opts*
Fields: ~
{backend?} (string)
Backend used for displaying the graph.
See: https://graphviz.org/docs/outputs/
Defaults to `"x11"` if unset.
{output?} (string)
Where to store the output. No output if unset.
Relative path from `cwd`.
{enabled_graphviz_backends?} (string[])
Override the enabled graphviz backends list, used for input validation and autocompletion.
{pipe?} (string)
Override the pipe symbol in the shell command.
Useful if using a shell that is not supported by this plugin.
rustaceanvim.rustc.Opts *rustaceanvim.rustc.Opts*
Fields: ~
{default_edition?} (string)
The default edition to use if it cannot be auto-detected.
See https://rustc-dev-guide.rust-lang.org/guides/editions.html.
Default '2021'.
rustaceanvim.lsp.ClientOpts *rustaceanvim.lsp.ClientOpts*
Fields: ~
{auto_attach?} (boolean|fun(bufnr:integer):boolean)
Whether to automatically attach the LSP client.
Defaults to `true` if the `rust-analyzer` executable is found.
{cmd?} (string[]|fun():string[]|fun(dispatchers:vim.lsp.rpc.Dispatchers):vim.lsp.rpc.Client)
Command and arguments for starting rust-analyzer
Can be a list of arguments, a function that returns a list of arguments,
or a function that returns an LSP RPC client factory (see |vim.lsp.rpc.connect|).
{root_dir?} (string|fun(filename:string,default:fun(filename:string):string|nil):string|nil)
The directory to use for the attached LSP.
Can be a function, which may return nil if no server should attach.
The second argument contains the default implementation, which can be used for fallback behavior.
{lspmux?} (rustaceanvim.lspmux.Opts)
Options for connecting to lspmux.
rustaceanvim.lspmux.Opts *rustaceanvim.lspmux.Opts*
Fields: ~
{enable?} (boolean)
Whether to enable lspmux auto-discovery.
Default: `true` if `server.cmd` is not set, otherwise `false`.
If enabled, rustaceanvim will try to detect if an lspmux server is running
and connect to it (Linux and MacOS only).
If auto-discovery does not work, you can set `server.cmd` to a function that
returns an LSP RPC client factory (see |vim.lsp.rpc.connect|).
{host?} (string)
The host to connect to. Default: '127.0.0.1'
{port?} (integer)
The port to connect to. Default: 27631
*rustaceanvim.server.status_notify_level*
rustaceanvim.server.status_notify_level
Type: ~
"error"|"warning"|rustaceanvim.disable
rustaceanvim.disable *rustaceanvim.disable*
Type: ~
false
rustaceanvim.dap.Opts *rustaceanvim.dap.Opts*
Fields: ~
{autoload_configurations?} (boolean)
Whether to autoload nvim-dap configurations when rust-analyzer has attached?
Default: `true`
{adapter?} (rustaceanvim.dap.executable.Config|rustaceanvim.dap.server.Config|rustaceanvim.disable|fun():rustaceanvim.dap.executable.Config|rustaceanvim.dap.server.Config|rustaceanvim.disable)
Defaults to creating the `rt_lldb` adapter, which is a |rustaceanvim.dap.server.Config|
if `codelldb` is detected, and a |rustaceanvim.dap.executable.Config|` if `lldb` is detected.
Set to `false` to disable.
{configuration?} (rustaceanvim.dap.client.Config|rustaceanvim.disable|fun():rustaceanvim.dap.client.Config|rustaceanvim.disable)
Dap client configuration. Defaults to a function that looks for a `launch.json` file
or returns a |rustaceanvim.dap.executable.Config| that launches the `rt_lldb` adapter.
Set to `false` to disable.
{add_dynamic_library_paths?} (boolean|fun():boolean)
Accommodate dynamically-linked targets by passing library paths to lldb.
Default: `true`.
{auto_generate_source_map?} (fun():boolean|boolean)
Whether to auto-generate a source map for the standard library.
{load_rust_types?} (fun():boolean|boolean)
Whether to get Rust types via initCommands (rustlib/etc/lldb_commands, lldb only).
Default: `true`.
rustaceanvim.dap.Command *rustaceanvim.dap.Command*
Type: ~
string
rustaceanvim.dap.executable.Config *rustaceanvim.dap.executable.Config*
Fields: ~
{type} (rustaceanvim.dap.adapter.types.executable)
The type of debug adapter.
{command} (string) Default: `"lldb-vscode"`.
{args?} (string) Default: unset.
{name?} (string) Default: `"lldb"`.
rustaceanvim.dap.server.Config *rustaceanvim.dap.server.Config*
Fields: ~
{type} (rustaceanvim.dap.adapter.types.server) The type of debug adapter.
{host?} (string) The host to connect to.
{port} (string) The port to connect to.
{executable} (rustaceanvim.dap.Executable) The executable to run
{name?} (string)
rustaceanvim.dap.Executable *rustaceanvim.dap.Executable*
Fields: ~
{command} (string) The executable.
{args} (string[]) Its arguments.
*rustaceanvim.dap.adapter.types.executable*
rustaceanvim.dap.adapter.types.executable
Type: ~
rustaceanvim.dap.adapter.types.server *rustaceanvim.dap.adapter.types.server*
Type: ~
*rustaceanvim.dap.client.Config*
rustaceanvim.dap.client.Config : dap.Configuration
Fields: ~
{type} (string) The dap adapter to use
{name} (string)
{request} (rustaceanvim.dap.config.requests.launch|rustaceanvim.dap.config.requests.attach|rustaceanvim.dap.config.requests.custom) The type of dap session
{cwd?} (string) Current working directory
{program?} (string) Path to executable for most DAP clients
{args?} (string[]) Optional args to DAP client, not valid for all client types
{env?} (rustaceanvim.EnvironmentMap) Environmental variables
{initCommands?} (string[]) Initial commands to run, `lldb` clients only
{coreConfigs?} (table)
Essential config values for `probe-rs` client, see https://probe.rs/docs/tools/debugger/
rustaceanvim.EnvironmentMap *rustaceanvim.EnvironmentMap*
Type: ~
table<string,string[]>
*rustaceanvim.dap.config.requests.launch*
rustaceanvim.dap.config.requests.launch
Type: ~
*rustaceanvim.dap.config.requests.attach*
rustaceanvim.dap.config.requests.attach
Type: ~
*rustaceanvim.dap.config.requests.custom*
rustaceanvim.dap.config.requests.custom
Type: ~
*config.get_codelldb_adapter*
config.get_codelldb_adapter({codelldb_path}, {liblldb_path})
For the heroes who want to use it.
Parameters: ~
{codelldb_path} (string) Path to the codelldb executable
{liblldb_path} (string) Path to the liblldb dynamic library
Returns: ~
(rustaceanvim.dap.server.Config)
==============================================================================
LSP configuration utility *rustaceanvim.config.server*
rustaceanvim.LoadRASettingsOpts *rustaceanvim.LoadRASettingsOpts*
Fields: ~
{default_settings} (table|nil)
Default settings to merge the loaded settings into.
*server.load_rust_analyzer_settings*
server.load_rust_analyzer_settings({_}, {opts})
Load rust-analyzer settings from a JSON file,
falling back to the default settings if none is found or if it cannot be decoded.
Parameters: ~
{_} (string|nil) The project root (ignored)
{opts} (rustaceanvim.LoadRASettingsOpts|nil)
Returns: ~
(table) server_settings
See: ~
|https://rust-analyzer.github.io/book/configuration|
server.create_client_capabilities() *server.create_client_capabilities*
Returns: ~
(lsp.ClientCapabilities)
==============================================================================
*rustaceanvim.neotest*
A |neotest| adapter for rust, powered by rustaceanvim.
If you add this to neotest:
>
require('neotest').setup {
-- ...,
adapters = {
-- ...,
require('rustaceanvim.neotest')
},
}
<
this plugin will configure itself to use |neotest|
as a test executor, and |neotest| will use rust-analyzer
for test discovery and command construction.
Note: If you use this adapter, do not add the neotest-rust adapter
(another plugin).
==============================================================================
*rustaceanvim.dap*
The DAP integration requires `nvim-dap` https://github.com/mfussenegger/nvim-dap
(Please read the plugin's documentation, see |dap-adapter|)
and a debug adapter (e.g. `lldb` https://lldb.llvm.org/
or `codelldb` https://github.com/vadimcn/codelldb).
By default, this plugin will silently attempt to autoload |dap-configuration|s
when the LSP client attaches.
You can call them with `require('dap').continue()` or `:DapContinue` once
they have been loaded. The feature can be disabled by setting
`vim.g.rustaceanvim.dap.autoload_configurations = false`.
- `:RustLsp debuggables` will only load debug configurations
created by `rust-analyzer`.
- `require('dap').continue()` will load all Rust debug configurations,
including those specified in a `.vscode/launch.json`
(see |dap-launch.json|)
IMPORTANT: Note that rustaceanvim may only be able to load DAP configurations
when rust-analyzer has finished initializing (which may be after
the client attaches, in large projects). This means that the
DAP configurations may not be loaded immediately upon startup.
vim:tw=78:ts=8:noet:ft=help:norl: