rustaceanvim.txt

==============================================================================
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 {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 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"


test_executor_alias                                        *test_executor_alias*

    Type: ~
        executor_alias|"background"|"neotest"


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

    See: ~
        |vim.lsp.ClientConfig|


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: