============================================================================== 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 ' - Set the target architecture for the LSP client. ':RustAnalyzer config ' - 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' - 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 `` on the respective line, or with a keymap for the `RustHoverAction` mapping, which accepts a `` prefix as the (1-based) index of the hover action to invoke. For example, if you set the keymap: `vim.keymap.set('n', 'a', 'RustHoverAction')`, you can invoke the third hover action with `3a`. '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) 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: `""`. {quit?} (string) The key or keys with which to close a code action window Default: `{ "q", "" }`. 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 *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: