411 lines
19 KiB
Plaintext
411 lines
19 KiB
Plaintext
==============================================================================
|
|
Table of Contents *rustaceanvim.contents*
|
|
|
|
Introduction ··························································· |intro|
|
|
································································ |rustaceanvim|
|
|
plugin configuration ····································· |rustaceanvim.config|
|
|
LSP configuration utility ························· |rustaceanvim.config.server|
|
|
························································ |rustaceanvim.neotest|
|
|
|
|
==============================================================================
|
|
Introduction *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' - Display a hover window with explanations form the Rust error index.
|
|
Like |vim.diagnostic.goto_next|, |explainError| will cycle diagnostics,
|
|
starting at the cursor position, until it can find a diagnostic with
|
|
an error code.
|
|
'renderDiagnostic' - Display a hover window with the rendered diagnostic,
|
|
as displayed during `cargo build`.
|
|
Like |vim.diagnostic.goto_next|, |renderDiagnostic| will cycle diagnostics,
|
|
starting at the cursor position, until it can find a diagnostic with
|
|
rendered data.
|
|
'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 RustaceanOpts
|
|
vim.g.rustaceanvim = {
|
|
---@type RustaceanToolsOpts
|
|
tools = {
|
|
-- ...
|
|
},
|
|
---@type RustaceanLspClientOpts
|
|
server = {
|
|
on_attach = function(client, bufnr)
|
|
-- Set keybindings, etc. here.
|
|
end,
|
|
default_settings = {
|
|
-- rust-analyzer language server configuration
|
|
['rust-analyzer'] = {
|
|
},
|
|
},
|
|
-- ...
|
|
},
|
|
---@type RustaceanDapOpts
|
|
dap = {
|
|
-- ...
|
|
},
|
|
}
|
|
<
|
|
|
|
Notes:
|
|
|
|
- `vim.g.rustaceanvim` can also be a function that returns a `RustaceanOpts` 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.
|
|
|
|
|
|
RustaceanOpts *RustaceanOpts*
|
|
|
|
Fields: ~
|
|
{tools?} (RustaceanToolsOpts) Plugin options
|
|
{server?} (RustaceanLspClientOpts) Language server client options
|
|
{dap?} (RustaceanDapOpts) Debug adapter options
|
|
|
|
|
|
RustaceanToolsOpts *RustaceanToolsOpts*
|
|
|
|
Fields: ~
|
|
{executor?} (RustaceanExecutor|executor_alias) The executor to use for runnables/debuggables
|
|
{test_executor?} (RustaceanExecutor|test_executor_alias) The executor to use for runnables that are tests / testables
|
|
{crate_test_executor?} (RustaceanExecutor|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:RustAnalyzerInitializedStatus)) 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?} (RustaceanHoverActionsOpts) Options for hover actions
|
|
{code_actions?} (RustaceanCodeActionOpts) Options for code actions
|
|
{float_win_config?} (FloatWinConfig) Options applied to floating windows. See |api-win_config|.
|
|
{create_graph?} (RustaceanCrateGraphConfig) 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?} (RustcOpts) Options for `rustc`
|
|
|
|
|
|
RustaceanExecutor *RustaceanExecutor*
|
|
|
|
Fields: ~
|
|
{execute_command} (fun(cmd:string,args:string[],cwd:string|nil,opts?:RustaceanExecutorOpts))
|
|
|
|
|
|
RustaceanExecutorOpts *RustaceanExecutorOpts*
|
|
|
|
Fields: ~
|
|
{bufnr?} (integer) The buffer from which the executor was invoked.
|
|
|
|
|
|
FloatWinConfig *FloatWinConfig*
|
|
|
|
Fields: ~
|
|
{auto_focus?} (boolean)
|
|
{open_split?} ("horizontal"|"vertical")
|
|
|
|
See: ~
|
|
|vim.lsp.util.open_floating_preview.Opts|
|
|
|vim.api.nvim_open_win|
|
|
|
|
|
|
executor_alias *executor_alias*
|
|
|
|
Type: ~
|
|
"termopen"|"quickfix"|"toggleterm"|"vimux"|"neotest"
|
|
|
|
|
|
test_executor_alias *test_executor_alias*
|
|
|
|
Type: ~
|
|
executor_alias|"background"
|
|
|
|
|
|
RustaceanHoverActionsOpts *RustaceanHoverActionsOpts*
|
|
|
|
Fields: ~
|
|
{replace_builtin_hover?} (boolean) Whether to replace Neovim's built-in `vim.lsp.buf.hover` with hover actions. Default: `true`
|
|
|
|
|
|
RustaceanCodeActionOpts *RustaceanCodeActionOpts*
|
|
|
|
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`
|
|
|
|
|
|
lsp_server_health_status *lsp_server_health_status*
|
|
|
|
Type: ~
|
|
"ok"|"warning"|"error"
|
|
|
|
|
|
RustAnalyzerInitializedStatus *RustAnalyzerInitializedStatus*
|
|
|
|
Fields: ~
|
|
{health} (lsp_server_health_status)
|
|
|
|
|
|
RustaceanCrateGraphConfig *RustaceanCrateGraphConfig*
|
|
|
|
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.
|
|
|
|
|
|
RustcOpts *RustcOpts*
|
|
|
|
Fields: ~
|
|
{edition} (string) The edition to use. See https://rustc-dev-guide.rust-lang.org/guides/editions.html. Default '2021'.
|
|
|
|
|
|
RustaceanLspClientOpts *RustaceanLspClientOpts*
|
|
|
|
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: false
|
|
|
|
|
|
RustaceanDapOpts *RustaceanDapOpts*
|
|
|
|
Fields: ~
|
|
{adapter?} (DapExecutableConfig|DapServerConfig|disable|fun():DapExecutableConfig|DapServerConfig|disable) @field autoload_configurations boolean Whether to autoload nvim-dap configurations when rust-analyzer has attached? Default: `true`.
|
|
|
|
|
|
disable *disable*
|
|
|
|
Type: ~
|
|
false
|
|
|
|
|
|
DapCommand *DapCommand*
|
|
|
|
Type: ~
|
|
string
|
|
|
|
|
|
DapExecutableConfig *DapExecutableConfig*
|
|
|
|
Fields: ~
|
|
{type} (dap_adapter_type_executable) The type of debug adapter.
|
|
{command} (string) Default: `"lldb-vscode"`.
|
|
{args?} (string) Default: unset.
|
|
{name?} (string) Default: `"lldb"`.
|
|
|
|
|
|
DapServerConfig *DapServerConfig*
|
|
|
|
Fields: ~
|
|
{type} (dap_adapter_type_server) The type of debug adapter.
|
|
{host?} (string) The host to connect to.
|
|
{port} (string) The port to connect to.
|
|
{executable} (DapExecutable) The executable to run
|
|
{name?} (string)
|
|
|
|
|
|
DapExecutable *DapExecutable*
|
|
|
|
Fields: ~
|
|
{command} (string) The executable.
|
|
{args} (string[]) Its arguments.
|
|
|
|
|
|
dap_adapter_type_executable *dap_adapter_type_executable*
|
|
|
|
Type: ~
|
|
|
|
|
|
|
|
dap_adapter_type_server *dap_adapter_type_server*
|
|
|
|
Type: ~
|
|
|
|
|
|
|
|
DapClientConfig : Configuration *DapClientConfig*
|
|
|
|
Fields: ~
|
|
{type} (string) The dap adapter to use
|
|
{name} (string)
|
|
{request} (dap_config_request_launch|dap_config_request_attach|dap_config_request_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?} (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/
|
|
|
|
|
|
EnvironmentMap *EnvironmentMap*
|
|
|
|
Type: ~
|
|
table<string,string[]>
|
|
|
|
|
|
dap_config_request_launch *dap_config_request_launch*
|
|
|
|
Type: ~
|
|
|
|
|
|
|
|
dap_config_request_attach *dap_config_request_attach*
|
|
|
|
Type: ~
|
|
|
|
|
|
|
|
dap_config_request_custom *dap_config_request_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: ~
|
|
(DapServerConfig)
|
|
|
|
|
|
==============================================================================
|
|
LSP configuration utility *rustaceanvim.config.server*
|
|
|
|
LoadRASettingsOpts *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} (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).
|
|
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|