============================================================================== 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 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. 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. 'expandMacro' - Expand macros recursively. 'moveItem {up|down}' - Move items up or down. 'hover {actions|range}' - Hover actions, or hover over visually selected range. 'explainError {cycle?|current?}' - Display a hover window with explanations form 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 |current|: Searches for diagnostics only in the current cursor line. 'renderDiagnostic {cycle?|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 |current|: Searches for diagnostics only in the current cursor line. '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. 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 `RustaceanOpts` 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. - `server.settings`, by default, is a function that looks for a `rust-analyzer.json` file in the project root, to load settings from it. It falls back to an empty table. rustaceanvim.Opts *rustaceanvim.Opts* Fields: ~ {tools?} (rustaceanvim.tools.Opts) Plugin options {server?} (rustaceanvim.lsp.ClientOpts) Language server client options {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)) 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 {hover_actions?} (rustaceanvim.hover-actions.Opts) Options for hover actions {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. 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.hover-actions.Opts *rustaceanvim.hover-actions.Opts* Fields: ~ {replace_builtin_hover?} (boolean) Whether to replace Neovim's built-in `vim.lsp.buf.hover` with hover actions. Default: `true` 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` 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) Overide 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[]) Command and arguments for starting rust-analyzer {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. {settings?} (table|fun(project_root:string|nil,default_settings:table):table) Setting passed to rust-analyzer. Defaults to a function that looks for a `rust-analyzer.json` file or returns an empty table. See https://rust-analyzer.github.io/manual.html#configuration. {standalone?} (boolean) Standalone file support (enabled by default). Disabling it may improve rust-analyzer's startup time. {logfile?} (string) The path to the rust-analyzer log file. {load_vscode_settings?} (boolean) Whether to search (upward from the buffer) for rust-analyzer settings in .vscode/settings json. If found, loaded settings will override configured options. Default: true See: ~ |vim.lsp.ClientConfig| rustaceanvim.dap.Opts *rustaceanvim.dap.Opts* Fields: ~ {autoload_configurations} (boolean) Whether to autoload nvim-dap configurations when rust-analyzer has attached? Default: `true`. rustaceanvim.disable *rustaceanvim.disable* Type: ~ false 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 : 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: ~ *M.get_codelldb_adapter* M.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: ~ {settings_file_pattern} (string|nil) File name or pattern to search for. Defaults to 'rust-analyzer.json' {default_settings} (table|nil) Default settings to merge the loaded settings into *server.load_rust_analyzer_settings* server.load_rust_analyzer_settings({project_root}, {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: ~ {project_root} (string|nil) The project root {opts} (rustaceanvim.LoadRASettingsOpts|nil) Returns: ~ (table) server_settings See: ~ |https://rust-analyzer.github.io/manual.html#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: