vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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: