.vim/bundle/ale/doc/ale-rust.txt

   1 ===============================================================================
   2 ALE Rust Integration                                         *ale-rust-options*
   3                                                          *ale-integration-rust*
   4
   5 ===============================================================================
   6 Integration Information
   7
   8   If Vim does not detect the Rust file type out-of-the-box, you need the runtime
   9   files for Rust distributed in Vim >=8.0.0501 or upstream:
  10   https://github.com/rust-lang/rust.vim
  11
  12   Note that there are several possible linters and fixers for Rust files:
  13
  14   1. rustc -- The Rust compiler is used to check the currently edited file.
  15      So, if your project consists of multiple files, you will get some errors
  16      when you use e.g. a struct which is defined in another file. You can use
  17      |g:ale_rust_ignore_error_codes| to ignore some of these errors.
  18   2. cargo -- If your project is managed by Cargo, the whole project is
  19      checked. That means that all errors are properly shown, but cargo can
  20      only operate on the files written on disk, so errors will not be reported
  21      while you type.
  22   3. rls -- If you have `rls` installed, you might prefer using this linter
  23      over cargo. rls implements the Language Server Protocol for incremental
  24      compilation of Rust code, and can check Rust files while you type. `rls`
  25      requires Rust files to be contained in Cargo projects.
  26   4. analyzer -- If you have rust-analyzer installed, you might prefer using
  27      this linter over cargo and rls. rust-analyzer also implements the
  28      Language Server Protocol for incremental compilation of Rust code, and is
  29      the next iteration of rls. rust-analyzer either requires Rust files to be
  30      contained in Cargo projects or requires the project to be described in
  31      the rust-project.json format:
  32      https://rust-analyzer.github.io/manual.html#non-cargo-based-projects
  33   5. rustfmt -- If you have `rustfmt` installed, you can use it as a fixer to
  34      consistently reformat your Rust code.
  35
  36   Only cargo and rust-analyze are enabled by default. To switch to using rustc
  37   instead of cargo, configure |b:ale_linters| in your ftplugin file
  38   appropriately: >
  39
  40   " See the help text for the option for more information.
  41   let b:ale_linters = ['analyzer', 'rustc']
  42 <
  43   Or in Lua: >
  44
  45   require("ale").setup.buffer({linters = {"analyzer", "rustc"}})
  46 <
  47   Also note that rustc 1.18. or later is needed.
  48
  49
  50 ===============================================================================
  51 analyzer                                                    *ale-rust-analyzer*
  52
  53                                          *ale-options.rust_analyzer_executable*
  54                                                *g:ale_rust_analyzer_executable*
  55                                                *b:ale_rust_analyzer_executable*
  56 rust_analyzer_executable
  57 g:ale_rust_analyzer_executable
  58   Type: |String|
  59   Default: `'rust-analyzer'`
  60
  61   This variable can be modified to change the executable path for
  62   `rust-analyzer`.
  63
  64                                              *ale-options.rust_analyzer_config*
  65                                                    *g:ale_rust_analyzer_config*
  66                                                    *b:ale_rust_analyzer_config*
  67 rust_analyzer_config
  68 g:ale_rust_analyzer_config
  69   Type: |Dictionary|
  70   Default: `{}`
  71
  72   Dictionary with configuration settings for rust-analyzer. Keys of the
  73   dictionary are components of configuration keys. For example: >
  74
  75   let g:ale_rust_analyzer_config = {
  76   \  'server': {
  77   \    'extraEnv': { 'RUSTUP_TOOLCHAIN': 'stable' },
  78   \  }
  79   \}
  80 <
  81   corresponds to `rust-analyzer.server.extraEnv = { 'RUSTUP_TOOLCHAIN': 'stable' }`
  82
  83   For available configuration parameters, see the `rust-analyzer` manual:
  84
  85   https://rust-analyzer.github.io/manual.html#configuration
  86
  87
  88 ===============================================================================
  89 cargo                                                          *ale-rust-cargo*
  90
  91                                              *ale-options.rust_cargo_use_check*
  92                                                    *g:ale_rust_cargo_use_check*
  93                                                    *b:ale_rust_cargo_use_check*
  94 rust_cargo_use_check
  95 g:ale_rust_cargo_use_check
  96   Type: |Number|
  97   Default: `1`
  98
  99   When set to `1`, this option will cause ALE to use `cargo check` instead of
 100   `cargo build` . `cargo check` is supported since version 1.16.0 of Rust.
 101
 102   ALE will never use `cargo check` when the version of `cargo` is less than
 103   0.17.0.
 104
 105                                      *ale-options.rust_cargo_check_all_targets*
 106                                            *g:ale_rust_cargo_check_all_targets*
 107                                            *b:ale_rust_cargo_check_all_targets*
 108 rust_cargo_check_all_targets
 109 g:ale_rust_cargo_check_all_targets
 110   Type: |Number|
 111   Default: `0`
 112
 113   When set to `1`, ALE will set the `--all-targets` option when `cargo check`
 114   is used. See |g:ale_rust_cargo_use_check|,
 115
 116                                            *ale-options.rust_cargo_check_tests*
 117                                                  *g:ale_rust_cargo_check_tests*
 118                                                  *b:ale_rust_cargo_check_tests*
 119 rust_cargo_check_tests
 120 g:ale_rust_cargo_check_tests
 121   Type: |Number|
 122   Default: `0`
 123
 124   When set to `1`, ALE will set the `--tests` option when `cargo check`
 125   is used. This allows for linting of tests which are normally excluded.
 126   See |g:ale_rust_cargo_use_check|,
 127
 128                                         *ale-options.rust_cargo_check_examples*
 129                                               *g:ale_rust_cargo_check_examples*
 130                                               *b:ale_rust_cargo_check_examples*
 131 rust_cargo_check_examples
 132 g:ale_rust_cargo_check_examples
 133   Type: |Number|
 134   Default: `0`
 135
 136   When set to `1`, ALE will set the `--examples` option when `cargo check`
 137   is used. This allows for linting of examples which are normally excluded.
 138   See |g:ale_rust_cargo_use_check|,
 139
 140                               *ale-options.rust_cargo_default_feature_behavior*
 141                                     *g:ale_rust_cargo_default_feature_behavior*
 142                                     *b:ale_rust_cargo_default_feature_behavior*
 143 rust_cargo_default_feature_behavior
 144 g:ale_rust_cargo_default_feature_behavior
 145   Type: |String|
 146   Default: `default`
 147
 148   When set to `none`, ALE will set the `--no-default-features` option when
 149   invoking `cargo`. Only the features specified in
 150   |g:ale_rust_cargo_include_features| will be included when performing the
 151   lint check.
 152
 153   When set to `default`, ALE will instruct `cargo` to build all default
 154   features specified in the project's `Cargo.toml` file, in addition to
 155   including any additional features defined in
 156   |g:ale_rust_cargo_include_features|.
 157
 158   When set to `all`, ALE will set the `--all-features` option when
 159   invoking `cargo`, which will include all features defined in the project's
 160   `Cargo.toml` file when performing the lint check.
 161
 162                                       *ale-options.rust_cargo_include_features*
 163                                             *g:ale_rust_cargo_include_features*
 164                                             *b:ale_rust_cargo_include_features*
 165 rust_cargo_include_features
 166 g:ale_rust_cargo_include_features
 167   Type: |String|
 168   Default: `''`
 169
 170   When defined, ALE will set the `--features` option when invoking `cargo` to
 171   perform the lint check. See |g:ale_rust_cargo_default_feature_behavior|.
 172
 173                                  *ale-options.rust_cargo_avoid_whole_workspace*
 174                                        *g:ale_rust_cargo_avoid_whole_workspace*
 175                                        *b:ale_rust_cargo_avoid_whole_workspace*
 176 rust_cargo_avoid_whole_workspace
 177 g:ale_rust_cargo_avoid_whole_workspace
 178   Type: |Number|
 179   Default: `1`
 180
 181   When set to 1, and ALE is used to edit a crate that is part of a Cargo
 182   workspace, avoid building the entire workspace by invoking `cargo` directly
 183   in the crate's directory. Otherwise, behave as usual.
 184
 185                                             *ale-options.rust_cargo_use_clippy*
 186                                                   *g:ale_rust_cargo_use_clippy*
 187                                                   *b:ale_rust_cargo_use_clippy*
 188 rust_cargo_use_clippy
 189 g:ale_rust_cargo_use_clippy
 190   Type: |Number|
 191   Default: `0`
 192
 193   When set to 1, `cargo clippy` will be used instead of `cargo check` or
 194   `cargo build` as linter.
 195   For details of `cargo clippy`, please visit the following link:
 196
 197   https://github.com/rust-lang-nursery/rust-clippy
 198
 199   Since `cargo clippy` is optional toolchain, it's safer to check whether
 200   `cargo-clippy` is executable as follows:
 201 >
 202     let g:ale_rust_cargo_use_clippy = executable('cargo-clippy')
 203 <
 204                                         *ale-options.rust_cargo_clippy_options*
 205                                               *g:ale_rust_cargo_clippy_options*
 206                                               *b:ale_rust_cargo_clippy_options*
 207 rust_cargo_clippy_options
 208 g:ale_rust_cargo_clippy_options
 209   Type: |String|
 210   Default: `''`
 211
 212   When `cargo clippy` is used, this value will be added to a command line to run
 213   it. This variable is useful when you want to add some extra options which
 214   only `cargo clippy` supports (e.g. `--deny`).
 215
 216                                             *ale-options.rust_cargo_target_dir*
 217                                                   *g:ale_rust_cargo_target_dir*
 218                                                   *b:ale_rust_cargo_target_dir*
 219 rust_cargo_target_dir
 220 g:ale_rust_cargo_target_dir
 221   Type: |String|
 222   Default: `''`
 223
 224   Use a custom target directory when running the commands for ALE. This can
 225   help to avoid "waiting for file lock on build directory" messages when
 226   running `cargo` commands manually while ALE is performing its checks.
 227
 228
 229 ===============================================================================
 230 cspell                                                        *ale-rust-cspell*
 231
 232 See |ale-cspell-options|
 233
 234
 235 ===============================================================================
 236 rls                                                              *ale-rust-rls*
 237
 238                                               *ale-options.rust_rls_executable*
 239                                                     *g:ale_rust_rls_executable*
 240                                                     *b:ale_rust_rls_executable*
 241 rust_rls_executable
 242 g:ale_rust_rls_executable
 243   Type: |String|
 244   Default: `'rls'`
 245
 246   This variable can be modified to change the executable path for `rls`.
 247
 248                                                *ale-options.rust_rls_toolchain*
 249                                                      *g:ale_rust_rls_toolchain*
 250                                                      *b:ale_rust_rls_toolchain*
 251 rust_rls_toolchain
 252 g:ale_rust_rls_toolchain
 253   Type: |String|
 254   Default: `''`
 255
 256   This option can be set to change the toolchain used for `rls`. Possible
 257   values include `'nightly'`, `'beta'`, `'stable'`, and `''`. When using
 258   option `''`, rls will automatically find the default toolchain set by
 259   rustup. If you want to use `rls` from a specific toolchain version, you may
 260   also use values like `'channel-yyyy-mm-dd-arch-target'` as long as
 261   `'rls +{toolchain_name} -V'` runs correctly in your command line.
 262
 263   The `rls` server will only be started once per executable.
 264
 265                                                   *ale-options.rust_rls_config*
 266                                                         *g:ale_rust_rls_config*
 267                                                         *b:ale_rust_rls_config*
 268 rust_rls_config
 269 g:ale_rust_rls_config
 270   Type: |Dictionary|
 271   Default: `{}`
 272
 273   Dictionary with configuration settings for rls. For example, to force
 274   using clippy as linter in your ftplugin file: >
 275
 276   let b:ale_rust_rls_config = {
 277   \   'rust': {
 278   \       'clippy_preference': 'on'
 279   \   },
 280   \}
 281 <
 282   Or in Lua: >
 283
 284   require("ale").setup.buffer({
 285       rust_rls_config = {
 286           rust = {
 287               clippy_preference = "on",
 288           },
 289       },
 290   })
 291 <
 292
 293 ===============================================================================
 294 rustc                                                          *ale-rust-rustc*
 295
 296                                                *ale-options.rust_rustc_options*
 297                                                      *g:ale_rust_rustc_options*
 298                                                      *b:ale_rust_rustc_options*
 299 rust_rustc_options
 300 g:ale_rust_rustc_options
 301   Type: |String|
 302   Default: `'--emit=mir -o /dev/null'`
 303
 304   The variable can be used to change the options passed to `rustc`.
 305
 306   Users of nightly builds of Rust might want to use `-Z no-codegen` instead.
 307   Be careful when setting the options, as running `rustc` could execute code
 308   or generate binary files.
 309
 310                                           *ale-options.rust_ignore_error_codes*
 311                                                 *g:ale_rust_ignore_error_codes*
 312                                                 *b:ale_rust_ignore_error_codes*
 313 rust_ignore_error_codes
 314 g:ale_rust_ignore_error_codes
 315   Type: |List| of |String|s
 316   Default: `[]`
 317
 318   This variable can contain error codes which will be ignored. For example, to
 319   ignore most errors regarding failed imports, put this in your .vimrc >
 320
 321   let g:ale_rust_ignore_error_codes = ['E0432', 'E0433']
 322 <
 323                                       *ale-options.rust_ignore_secondary_spans*
 324                                             *g:ale_rust_ignore_secondary_spans*
 325                                             *b:ale_rust_ignore_secondary_spans*
 326 rust_ignore_secondary_spans
 327 g:ale_rust_ignore_secondary_spans
 328   Type: |Number|
 329   Default: `0`
 330
 331   When set to 1, instructs the Rust error reporting to ignore secondary spans.
 332   The problem with secondary spans is that they sometimes appear in error
 333   messages before the main cause of the error, for example: >
 334
 335   1 src/main.rs|98 col 5 error| this function takes 4 parameters but 5
 336     parameters were supplied: defined here
 337   2 src/main.rs|430 col 32 error| this function takes 4 parameters but 5
 338     parameters were supplied: expected 4 parameters
 339 <
 340   This is due to the sorting by line numbers. With this option set to 1,
 341   the 'defined here' span will not be presented.
 342
 343
 344 ===============================================================================
 345 rustfmt                                                      *ale-rust-rustfmt*
 346
 347                                              *ale-options.rust_rustfmt_options*
 348                                                    *g:ale_rust_rustfmt_options*
 349                                                    *b:ale_rust_rustfmt_options*
 350 rust_rustfmt_options
 351 g:ale_rust_rustfmt_options
 352   Type: |String|
 353   Default: `''`
 354
 355   This variable can be set to pass additional options to the rustfmt fixer.
 356
 357                                           *ale-options.rust_rustfmt_executable*
 358                                                 *g:ale_rust_rustfmt_executable*
 359                                                 *b:ale_rust_rustfmt_executable*
 360 rust_rustfmt_executable
 361 g:ale_rust_rustfmt_executable
 362   Type: |String|
 363   Default: `'rustfmt'`
 364
 365   This variable can be modified to change the executable path for `rustfmt`.
 366
 367
 368 ===============================================================================
 369   vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl: