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