ft_rust.txt 19 KB

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