506 lines
25 KiB
Plaintext
506 lines
25 KiB
Plaintext
==============================================================================
|
|
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<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: ~
|
|
|
|
|
|
|
|
*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:
|