rustaceanvim.txt

==============================================================================
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.
 ':RustAnalyzer target <target_arch>' - Set the target architecture for the LSP client.
 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.

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)
                                                  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[])
                                                                                                                   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`
        {status_notify_level?}   (rustaceanvim.server.status_notify_level)
                                                                                                                   Server status warning level to notify at.
                                                                                                                   Default: 'error'


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<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: ~
        


                                                   *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: ~
        {settings_file_pattern}  (string|nil)
                                               (deprecated) 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: