ft_rust.txt (20073B)
1 *ft_rust.txt* Filetype plugin for Rust 2 3 ============================================================================== 4 CONTENTS *rust* 5 6 1. Introduction |rust-intro| 7 2. Settings |rust-settings| 8 3. Commands |rust-commands| 9 4. Mappings |rust-mappings| 10 11 ============================================================================== 12 INTRODUCTION *rust-intro* 13 14 This plugin provides syntax and supporting functionality for the Rust 15 filetype. It requires Vim 8 or higher for full functionality. Some commands 16 will not work on earlier versions. 17 18 ============================================================================== 19 SETTINGS *rust-settings* 20 21 This plugin has a few variables you can define in your vimrc that change the 22 behavior of the plugin. 23 24 Some variables can be set buffer local (`:b` prefix), and the buffer local 25 will take precedence over the global `g:` counterpart. 26 27 *g:rustc_path* 28 g:rustc_path ~ 29 Set this option to the path to rustc for use in the |:RustRun| and 30 |:RustExpand| commands. If unset, `rustc` will be located in $PATH: >vim 31 let g:rustc_path = $HOME."/bin/rustc" 32 < 33 34 *g:rustc_makeprg_no_percent* 35 g:rustc_makeprg_no_percent ~ 36 Set this option to 1 to have 'makeprg' default to `rustc` instead of 37 `rustc %`: >vim 38 let g:rustc_makeprg_no_percent = 1 39 < 40 41 *g:rust_conceal* 42 g:rust_conceal ~ 43 Set this option to turn on the basic |conceal| support: >vim 44 let g:rust_conceal = 1 45 < 46 47 *g:rust_conceal_mod_path* 48 g:rust_conceal_mod_path ~ 49 Set this option to turn on |conceal| for the path connecting token 50 "::": >vim 51 let g:rust_conceal_mod_path = 1 52 < 53 54 *g:rust_conceal_pub* 55 g:rust_conceal_pub ~ 56 Set this option to turn on |conceal| for the "pub" token: >vim 57 let g:rust_conceal_pub = 1 58 < 59 60 *g:rust_recommended_style* 61 g:rust_recommended_style ~ 62 Set this option to enable vim indentation and textwidth settings to 63 conform to style conventions of the Rust style guide (i.e. use 4 64 spaces for indents and set 'textwidth' to 100). This option is enabled 65 by default. To disable it: >vim 66 let g:rust_recommended_style = 0 67 < 68 69 *g:rust_fold* 70 g:rust_fold ~ 71 Set this option to turn on |folding|: >vim 72 let g:rust_fold = 1 73 < 74 Value Effect ~ 75 0 No folding 76 1 Braced blocks are folded. All folds are open by 77 default. 78 2 Braced blocks are folded. 'foldlevel' is left at the 79 global value (all folds are closed by default). 80 81 *g:rust_bang_comment_leader* 82 g:rust_bang_comment_leader ~ 83 Set this option to 1 to preserve the leader on multi-line doc comments 84 using the `/*!` syntax: >vim 85 let g:rust_bang_comment_leader = 1 86 < 87 88 *g:rust_use_custom_ctags_defs* 89 g:rust_use_custom_ctags_defs ~ 90 Set this option to 1 if you have customized ctags definitions for Rust 91 and do not wish for those included with rust.vim to be used: >vim 92 let g:rust_use_custom_ctags_defs = 1 93 < 94 95 NOTE: rust.vim's built-in definitions are only used for the Tagbar Vim 96 plugin, if you have it installed, AND if Universal Ctags is not 97 detected. This is because Universal Ctags already has built-in 98 support for Rust when used with Tagbar. 99 100 Also, note that when using ctags other than Universal Ctags, it is not 101 automatically used when generating |tags| files that Vim can use to 102 navigate to definitions across different source files. Feel free to 103 copy `rust.vim/ctags/rust.ctags` into your own `~/.ctags` if you wish 104 to generate |tags| files. 105 106 *g:ftplugin_rust_source_path* 107 g:ftplugin_rust_source_path ~ 108 Set this option to a path that should be prepended to 'path' for Rust 109 source files: >vim 110 let g:ftplugin_rust_source_path = $HOME . '/dev/rust' 111 < 112 113 *g:rustfmt_command* 114 g:rustfmt_command ~ 115 Set this option to the name of the "rustfmt" executable in your $PATH. If 116 not specified it defaults to "rustfmt" : >vim 117 let g:rustfmt_command = 'rustfmt' 118 < 119 *g:rustfmt_autosave* 120 g:rustfmt_autosave ~ 121 Set this option to 1 to run |:RustFmt| automatically when saving a 122 buffer. If not specified it defaults to 0 : >vim 123 let g:rustfmt_autosave = 0 124 < 125 There is also a buffer-local b:rustfmt_autosave that can be set for 126 the same purpose, and can override the global setting. 127 128 *g:rustfmt_autosave_if_config_present* 129 g:rustfmt_autosave_if_config_present ~ 130 Set this option to 1 to have *b:rustfmt_autosave* be set automatically 131 if a `rustfmt.toml` file is present in any parent directly leading to 132 the file being edited. If not set, default to 0: >vim 133 let g:rustfmt_autosave_if_config_present = 0 134 < 135 This is useful to have `rustfmt` only execute on save, on projects 136 that have `rustfmt.toml` configuration. 137 138 There is also a buffer-local b:rustfmt_autosave_if_config_present 139 that can be set for the same purpose, which can overrides the global 140 setting. 141 142 *g:rustfmt_fail_silently* 143 g:rustfmt_fail_silently ~ 144 Set this option to 1 to prevent "rustfmt" from populating the 145 |location-list| with errors. If not specified it defaults to 0: >vim 146 let g:rustfmt_fail_silently = 0 147 < 148 *g:rustfmt_options* 149 g:rustfmt_options ~ 150 Set this option to a string of options to pass to "rustfmt". The 151 write-mode is already set to "overwrite". If not specified it 152 defaults to '' : >vim 153 let g:rustfmt_options = '' 154 < 155 *g:rustfmt_emit_files* 156 g:rustfmt_emit_files ~ 157 If not specified rust.vim tries to detect the right parameter to 158 pass to rustfmt based on its reported version. Otherwise, it 159 determines whether to run rustfmt with '--emit=files' (when 1 is 160 provided) instead of '--write-mode=overwrite'. >vim 161 let g:rustfmt_emit_files = 0 162 < 163 *g:rustfmt_detect_version* 164 g:rustfmt_detect_version ~ 165 When set to 1, will try to parse the version output from "rustfmt". 166 Disabled by default for performance reasons >vim 167 let g:rustfmt_detect_version = 1 168 < 169 *g:rustfmt_find_toml* 170 g:rustfmt_find_toml ~ 171 When set to 1, will try to find `rustfmt.toml` file by searching from 172 current path upwards. Disabled by default for performance reasons >vim 173 let g:rustfmt_find_toml = 1 174 < 175 *g:rust_playpen_url* 176 g:rust_playpen_url ~ 177 Set this option to override the url for the playpen to use: >vim 178 let g:rust_playpen_url = 'https://play.rust-lang.org/' 179 < 180 181 *g:rust_shortener_url* 182 g:rust_shortener_url ~ 183 Set this option to override the url for the url shortener: >vim 184 let g:rust_shortener_url = 'https://is.gd/' 185 < 186 *g:rust_clip_command* 187 g:rust_clip_command ~ 188 Set this option to the command used in your OS to copy the Rust Play 189 url to the clipboard: >vim 190 let g:rust_clip_command = 'xclip -selection clipboard' 191 < 192 193 *g:cargo_makeprg_params* 194 g:cargo_makeprg_params ~ 195 Set this option to the string of parameters to pass to cargo. If not 196 specified it defaults to `$*` : >vim 197 let g:cargo_makeprg_params = 'build' 198 < 199 200 *g:cargo_shell_command_runner* 201 g:cargo_shell_command_runner ~ 202 Set this option to change how to run shell commands for cargo commands 203 |:Cargo|, |:Cbuild|, |:Crun|, ... 204 By default, |:terminal| is used to run shell command in terminal window 205 asynchronously. But if you prefer |:!| for running the commands, it can 206 be specified: >vim 207 let g:cargo_shell_command_runner = '!' 208 < 209 210 ------------------------------------------------------------------------------ 211 Integration with Syntastic *rust-syntastic* 212 213 This plugin automatically integrates with the Syntastic checker. There are two 214 checkers provided: `rustc`, and `cargo`. The latter invokes `cargo` in order to 215 build code, and the former delivers a single edited '.rs' file as a compilation 216 target directly to the Rust compiler, `rustc`. 217 218 Because Cargo is almost exclusively being used for building Rust code these 219 days, `cargo` is the default checker. >vim 220 221 let g:syntastic_rust_checkers = ['cargo'] 222 < 223 If you would like to change it, you can set `g:syntastic_rust_checkers` to a 224 different value. 225 *g:rust_cargo_avoid_whole_workspace* 226 *b:rust_cargo_avoid_whole_workspace* 227 g:rust_cargo_avoid_whole_workspace ~ 228 When editing a crate that is part of a Cargo workspace, and this 229 option is set to 1 (the default), then `cargo` will be executed 230 directly in that crate directory instead of in the workspace 231 directory. Setting 0 prevents this behavior - however be aware that if 232 you are working in large workspace, Cargo commands may take more time, 233 plus the Syntastic error list may include all the crates in the 234 workspace. >vim 235 let g:rust_cargo_avoid_whole_workspace = 0 236 < 237 *g:rust_cargo_check_all_targets* 238 *b:rust_cargo_check_all_targets* 239 g:rust_cargo_check_all_targets ~ 240 When set to 1, the `--all-targets` option will be passed to cargo when 241 Syntastic executes it, allowing the linting of all targets under the 242 package. 243 The default is 0. 244 245 *g:rust_cargo_check_all_features* 246 *b:rust_cargo_check_all_features* 247 g:rust_cargo_check_all_features ~ 248 When set to 1, the `--all-features` option will be passed to cargo when 249 Syntastic executes it, allowing the linting of all features of the 250 package. 251 The default is 0. 252 253 *g:rust_cargo_check_examples* 254 *b:rust_cargo_check_examples* 255 g:rust_cargo_check_examples ~ 256 When set to 1, the `--examples` option will be passed to cargo when 257 Syntastic executes it, to prevent the exclusion of examples from 258 linting. The examples are normally under the `examples/` directory of 259 the crate. 260 The default is 0. 261 262 *g:rust_cargo_check_tests* 263 *b:rust_cargo_check_tests* 264 g:rust_cargo_check_tests ~ 265 When set to 1, the `--tests` option will be passed to cargo when 266 Syntastic executes it, to prevent the exclusion of tests from linting. 267 The tests are normally under the `tests/` directory of the crate. 268 The default is 0. 269 270 *g:rust_cargo_check_benches* 271 *b:rust_cargo_check_benches* 272 g:rust_cargo_check_benches ~ 273 When set to 1, the `--benches` option will be passed to cargo when 274 Syntastic executes it. The benches are normally under the `benches/` 275 directory of the crate. 276 The default is 0. 277 278 ------------------------------------------------------------------------------ 279 Integration with auto-pairs *rust-auto-pairs* 280 281 This plugin automatically configures the auto-pairs plugin not to duplicate 282 single quotes, which are used more often for lifetime annotations than for 283 single character literals. 284 285 *g:rust_keep_autopairs_default* 286 g:rust_keep_autopairs_default ~ 287 288 Don't override auto-pairs default for the Rust filetype. The default 289 is 0. 290 291 ============================================================================== 292 COMMANDS *rust-commands* 293 294 Invoking Cargo ~ 295 296 This plug defines very simple shortcuts for invoking Cargo from with Vim. 297 298 :Cargo <args> *:Cargo* 299 Runs `cargo` with the provided arguments. 300 301 :Cbuild <args> *:Cbuild* 302 Shortcut for `cargo build` . 303 304 :Cclean <args> *:Cclean* 305 Shortcut for `cargo clean` . 306 307 :Cdoc <args> *:Cdoc* 308 Shortcut for `cargo doc` . 309 310 :Cinit <args> *:Cinit* 311 Shortcut for `cargo init` . 312 313 :Crun <args> *:Crun* 314 Shortcut for `cargo run` . 315 316 :Ctest <args> *:Ctest* 317 Shortcut for `cargo test` . 318 319 :Cupdate <args> *:Cupdate* 320 Shortcut for `cargo update` . 321 322 :Cbench <args> *:Cbench* 323 Shortcut for `cargo bench` . 324 325 :Csearch <args> *:Csearch* 326 Shortcut for `cargo search` . 327 328 :Cpublish <args> *:Cpublish* 329 Shortcut for `cargo publish` . 330 331 :Cinstall <args> *:Cinstall* 332 Shortcut for `cargo install` . 333 334 :Cruntarget <args> *:Cruntarget* 335 Shortcut for `cargo run --bin` or `cargo run --example`, 336 depending on the currently open buffer. 337 338 Formatting ~ 339 340 :RustFmt *:RustFmt* 341 Runs |g:rustfmt_command| on the current buffer. If 342 |g:rustfmt_options| is set then those will be passed to the 343 executable. 344 345 If |g:rustfmt_fail_silently| is 0 (the default) then it 346 will populate the |location-list| with the errors from 347 |g:rustfmt_command|. If |g:rustfmt_fail_silently| is set to 1 348 then it will not populate the |location-list|. 349 350 :RustFmtRange *:RustFmtRange* 351 Runs |g:rustfmt_command| with selected range. See 352 |:RustFmt| for any other information. 353 354 355 Playpen integration ~ 356 357 :RustPlay *:RustPlay* 358 This command will only work if you have web-api.vim installed 359 (available at https://github.com/mattn/webapi-vim). It sends the 360 current selection, or if nothing is selected, the entirety of the 361 current buffer to the Rust playpen, and emits a message with the 362 shortened URL to the playpen. 363 364 |g:rust_playpen_url| is the base URL to the playpen, by default 365 "https://play.rust-lang.org/". 366 367 |g:rust_shortener_url| is the base url for the shorterner, by 368 default "https://is.gd/" 369 370 |g:rust_clip_command| is the command to run to copy the 371 playpen url to the clipboard of your system. 372 373 374 Evaluation of a single Rust file ~ 375 376 NOTE: These commands are useful only when working with standalone Rust files, 377 which is usually not the case for common Rust development. If you wish to 378 building Rust crates from with Vim can should use Vim's make, Syntastic, or 379 functionality from other plugins. 380 381 382 :RustRun [args] *:RustRun* 383 :RustRun! [rustc-args] [--] [args] 384 Compiles and runs the current file. If it has unsaved changes, 385 it will be saved first using |:update|. If the current file is 386 an unnamed buffer, it will be written to a temporary file 387 first. The compiled binary is always placed in a temporary 388 directory, but is run from the current directory. 389 390 The arguments given to |:RustRun| will be passed to the 391 compiled binary. 392 393 If ! is specified, the arguments are passed to rustc instead. 394 A "--" argument will separate the rustc arguments from the 395 arguments passed to the binary. 396 397 If |g:rustc_path| is defined, it is used as the path to rustc. 398 Otherwise it is assumed rustc can be found in $PATH. 399 400 :RustExpand [args] *:RustExpand* 401 :RustExpand! [TYPE] [args] 402 Expands the current file using `--pretty` and displays the 403 results in a new split. If the current file has unsaved 404 changes, it will be saved first using |:update|. If the 405 current file is an unnamed buffer, it will be written to a 406 temporary file first. 407 408 The arguments given to |:RustExpand| will be passed to rustc. 409 This is largely intended for specifying various `--cfg` 410 configurations. 411 412 If ! is specified, the first argument is the expansion type to 413 pass to `rustc --pretty` . Otherwise it will default to 414 "expanded". 415 416 If |g:rustc_path| is defined, it is used as the path to rustc. 417 Otherwise it is assumed rustc can be found in $PATH. 418 419 :RustEmitIr [args] *:RustEmitIr* 420 Compiles the current file to LLVM IR and displays the results 421 in a new split. If the current file has unsaved changes, it 422 will be saved first using |:update|. If the current file is an 423 unnamed buffer, it will be written to a temporary file first. 424 425 The arguments given to |:RustEmitIr| will be passed to rustc. 426 427 If |g:rustc_path| is defined, it is used as the path to rustc. 428 Otherwise it is assumed rustc can be found in $PATH. 429 430 :RustEmitAsm [args] *:RustEmitAsm* 431 Compiles the current file to assembly and displays the results 432 in a new split. If the current file has unsaved changes, it 433 will be saved first using |:update|. If the current file is an 434 unnamed buffer, it will be written to a temporary file first. 435 436 The arguments given to |:RustEmitAsm| will be passed to rustc. 437 438 If |g:rustc_path| is defined, it is used as the path to rustc. 439 Otherwise it is assumed rustc can be found in $PATH. 440 441 442 Running test(s) ~ 443 444 :[N]RustTest[!] [options] *:RustTest* 445 Runs a test under the cursor when the current buffer is in a 446 cargo project with "cargo test" command. If the command did 447 not find any test function under the cursor, it stops with an 448 error message. 449 450 When N is given, adjust the size of the new window to N lines 451 or columns. 452 453 When ! is given, runs all tests regardless of current cursor 454 position. 455 456 When [options] is given, it is passed to "cargo" command 457 arguments. 458 459 When the current buffer is outside cargo project, the command 460 runs `rustc --test` command instead of "cargo test" as 461 fallback. All tests are run regardless of adding ! since there 462 is no way to run specific test function with rustc. [options] 463 is passed to `rustc` command arguments in the case. 464 465 Takes optional modifiers (see |<mods>|): >vim 466 :tab RustTest 467 :belowright 16RustTest 468 :leftabove vert 80RustTest 469 < 470 rust.vim Debugging ~ 471 472 :RustInfo *:RustInfo* 473 Emits debugging info of the Vim Rust plugin. 474 475 :RustInfoToClipboard *:RustInfoClipboard* 476 Saves debugging info of the Vim Rust plugin to the default 477 register. 478 479 :RustInfoToFile [filename] *:RustInfoToFile* 480 Saves debugging info of the Vim Rust plugin to the given file, 481 overwriting it. 482 483 ============================================================================== 484 MAPPINGS *rust-mappings* 485 486 This plugin defines mappings for |[[| and |]]| to support hanging indents. 487 488 489 vim:tw=78:sw=4:noet:ts=8:ft=help:norl: