summaryrefslogtreecommitdiffstats
path: root/runtime/doc/ft_rust.txt
blob: 564f3e774a96319eb310fc5253e4213b3b85d35b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
*ft_rust.txt*      Filetype plugin for Rust

==============================================================================
CONTENTS                                                      *rust*

1. Introduction                                                   |rust-intro|
2. Settings                                                    |rust-settings|
3. Commands                                                    |rust-commands|
4. Mappings                                                    |rust-mappings|

==============================================================================
INTRODUCTION                                                      *rust-intro*

This plugin provides syntax and supporting functionality for the Rust
filetype. It requires Vim 8 or higher for full functionality. Some commands
will not work on earlier versions.

==============================================================================
SETTINGS                                                       *rust-settings*

This plugin has a few variables you can define in your vimrc that change the
behavior of the plugin.

Some variables can be set buffer local (`:b` prefix), and the buffer local
will take precedence over the global `g:` counterpart.

                                                                *g:rustc_path*
g:rustc_path~
	Set this option to the path to rustc for use in the |:RustRun| and
	|:RustExpand| commands. If unset, "rustc" will be located in $PATH: >
	    let g:rustc_path = $HOME."/bin/rustc"
<

                                                  *g:rustc_makeprg_no_percent*
g:rustc_makeprg_no_percent~
	Set this option to 1 to have 'makeprg' default to "rustc" instead of
	"rustc %": >
	    let g:rustc_makeprg_no_percent = 1
<

                                                              *g:rust_conceal*
g:rust_conceal~
	Set this option to turn on the basic |conceal| support: >
	    let g:rust_conceal = 1
<

                                                     *g:rust_conceal_mod_path*
g:rust_conceal_mod_path~
	Set this option to turn on |conceal| for the path connecting token
	"::": >
	    let g:rust_conceal_mod_path = 1
<

                                                          *g:rust_conceal_pub*
g:rust_conceal_pub~
	Set this option to turn on |conceal| for the "pub" token: >
	    let g:rust_conceal_pub = 1
<

                                                     *g:rust_recommended_style*
g:rust_recommended_style~
        Set this option to enable vim indentation and textwidth settings to
        conform to style conventions of the rust standard library (i.e. use 4
        spaces for indents and sets 'textwidth' to 99). This option is enabled
	by default. To disable it: >
	    let g:rust_recommended_style = 0
<

                                                                 *g:rust_fold*
g:rust_fold~
	Set this option to turn on |folding|: >
	    let g:rust_fold = 1
<
	Value		Effect ~
	0		No folding
	1		Braced blocks are folded. All folds are open by
			default.
	2		Braced blocks are folded. 'foldlevel' is left at the
			global value (all folds are closed by default).

                                                  *g:rust_bang_comment_leader*
g:rust_bang_comment_leader~
	Set this option to 1 to preserve the leader on multi-line doc comments
	using the /*! syntax: >
	    let g:rust_bang_comment_leader = 1
<

                                                *g:rust_use_custom_ctags_defs*
g:rust_use_custom_ctags_defs~
	Set this option to 1 if you have customized ctags definitions for Rust
	and do not wish for those included with rust.vim to be used: >
	    let g:rust_use_custom_ctags_defs = 1
<

	NOTE: rust.vim's built-in definitions are only used for the Tagbar Vim
	plugin, if you have it installed, AND if Universal Ctags is not
	detected. This is because Universal Ctags already has built-in
	support for Rust when used with Tagbar.

	Also, note that when using ctags other than Universal Ctags, it is not
	automatically used when generating |tags| files that Vim can use to
	navigate to definitions across different source files. Feel free to
	copy `rust.vim/ctags/rust.ctags` into your own `~/.ctags` if you wish
	to generate |tags| files.


                                                 *g:ftplugin_rust_source_path*
g:ftplugin_rust_source_path~
	Set this option to a path that should be prepended to 'path' for Rust
	source files: >
	    let g:ftplugin_rust_source_path = $HOME.'/dev/rust'
<

                                                       *g:rustfmt_command*
g:rustfmt_command~
	Set this option to the name of the 'rustfmt' executable in your $PATH. If
	not specified it defaults to 'rustfmt' : >
	    let g:rustfmt_command = 'rustfmt'
<
                                                       *g:rustfmt_autosave*
g:rustfmt_autosave~
	Set this option to 1 to run |:RustFmt| automatically when saving a
	buffer. If not specified it defaults to 0 : >
	    let g:rustfmt_autosave = 0
<
	There is also a buffer-local b:rustfmt_autosave that can be set for
	the same purpose, and can override the global setting.

                                        *g:rustfmt_autosave_if_config_present*
g:rustfmt_autosave_if_config_present~
	Set this option to 1 to have *b:rustfmt_autosave* be set automatically
	if a `rustfmt.toml` file is present in any parent directly leading to
	the file being edited. If not set, default to 0: >
	    let g:rustfmt_autosave_if_config_present = 0
<
	This is useful to have `rustfmt` only execute on save, on projects
	that have `rustfmt.toml` configuration.

	There is also a buffer-local b:rustfmt_autosave_if_config_present
	that can be set for the same purpose, which can overrides the global
	setting.
                                                       *g:rustfmt_fail_silently*
g:rustfmt_fail_silently~
	Set this option to 1 to prevent 'rustfmt' from populating the
	|location-list| with errors. If not specified it defaults to 0: >
	    let g:rustfmt_fail_silently = 0
<
                                                       *g:rustfmt_options*
g:rustfmt_options~
	Set this option to a string of options to pass to 'rustfmt'. The
	write-mode is already set to 'overwrite'. If not specified it
	defaults to '' : >
	    let g:rustfmt_options = ''
<
                                                       *g:rustfmt_emit_files*
g:rustfmt_emit_files~
	If not specified rust.vim tries to detect the right parameter to
	pass to rustfmt based on its reported version. Otherwise, it
	determines whether to run rustfmt with '--emit=files' (when 1 is
	provided) instead of '--write-mode=overwrite'. >
	    let g:rustfmt_emit_files = 0

<
                                                          *g:rust_playpen_url*
g:rust_playpen_url~
	Set this option to override the url for the playpen to use: >
	    let g:rust_playpen_url = 'https://play.rust-lang.org/'
<

                                                        *g:rust_shortener_url*
g:rust_shortener_url~
	Set this option to override the url for the url shortener: >
	    let g:rust_shortener_url = 'https://is.gd/'
<

                                                        *g:rust_clip_command*
g:rust_clip_command~
	Set this option to the command used in your OS to copy the Rust Play
	url to the clipboard: >
	    let g:rust_clip_command = 'xclip -selection clipboard'
<

                                                       *g:cargo_makeprg_params*
g:cargo_makeprg_params~
	Set this option to the string of parameters to pass to cargo. If not
	specified it defaults to '$*' : >
	    let g:cargo_makeprg_params = 'build'
<

                                                  *g:cargo_shell_command_runner*
g:cargo_shell_command_runner~
	Set this option to change how to run shell commands for cargo commands
	|:Cargo|, |:Cbuild|, |:Crun|, ...
	By default, |:terminal| is used to run shell command in terminal window
	asynchronously. But if you prefer |:!| for running the commands, it can
	be specified: >
	    let g:cargo_shell_command_runner = '!'
<


Integration with Syntastic                                    *rust-syntastic*
--------------------------

This plugin automatically integrates with the Syntastic checker. There are two
checkers provided: 'rustc', and 'cargo'. The latter invokes 'Cargo' in order to
build code, and the former delivers a single edited '.rs' file as a compilation
target directly to the Rust compiler, `rustc`.

Because Cargo is almost exclusively being used for building Rust code these
days, 'cargo' is the default checker. >

    let g:syntastic_rust_checkers = ['cargo']
<
If you would like to change it, you can set `g:syntastic_rust_checkers` to a
different value.
                                          *g:rust_cargo_avoid_whole_workspace*
                                          *b:rust_cargo_avoid_whole_workspace*
g:rust_cargo_avoid_whole_workspace~
	When editing a crate that is part of a Cargo workspace, and this
	option is set to 1 (the default), then 'cargo' will be executed
	directly in that crate directory instead of in the workspace
	directory. Setting 0 prevents this behavior - however be aware that if
	you are working in large workspace, Cargo commands may take more time,
	plus the Syntastic error list may include all the crates in the
	workspace. >
            let g:rust_cargo_avoid_whole_workspace = 0
<
                                              *g:rust_cargo_check_all_targets*
                                              *b:rust_cargo_check_all_targets*
g:rust_cargo_check_all_targets~
	When set to 1, the `--all-targets` option will be passed to cargo when
	Syntastic executes it, allowing the linting of all targets under the
	package.
	The default is 0.

                                              *g:rust_cargo_check_all_features*
                                              *b:rust_cargo_check_all_features*
g:rust_cargo_check_all_features~
	When set to 1, the `--all-features` option will be passed to cargo when
	Syntastic executes it, allowing the linting of all features of the
	package.
	The default is 0.

                                                 *g:rust_cargo_check_examples*
                                                 *b:rust_cargo_check_examples*
g:rust_cargo_check_examples~
	When set to 1, the `--examples` option will be passed to cargo when
	Syntastic executes it, to prevent the exclusion of examples from
	linting. The examples are normally under the `examples/` directory of
	the crate.
	The default is 0.

                                                    *g:rust_cargo_check_tests*
                                                    *b:rust_cargo_check_tests*
g:rust_cargo_check_tests~
	When set to 1, the `--tests` option will be passed to cargo when
	Syntastic executes it, to prevent the exclusion of tests from linting.
	The tests are normally under the `tests/` directory of the crate.
	The default is 0.

                                                  *g:rust_cargo_check_benches*
                                                  *b:rust_cargo_check_benches*
g:rust_cargo_check_benches~
	When set to 1, the `--benches` option will be passed to cargo when
	Syntastic executes it.  The benches are normally under the `benches/`
	directory of the crate.
	The default is 0.

Integration with auto-pairs                                    *rust-auto-pairs*
---------------------------

This plugin automatically configures the auto-pairs plugin not to duplicate
single quotes, which are used more often for lifetime annotations than for
single character literals.

                                                  *g:rust_keep_autopairs_default*
g:rust_keep_autopairs_default~

	Don't override auto-pairs default for the Rust filetype. The default
	is 0.

==============================================================================
COMMANDS                                                       *rust-commands*

Invoking Cargo
--------------

This plug defines very simple shortcuts for invoking Cargo from with Vim.

:Cargo <args>                                                       *:Cargo*
                Runs 'cargo' with the provided arguments.

:Cbuild <args>                                                     *:Cbuild*
                Shortcut for 'cargo build`.

:Cclean <args>                                                     *:Cclean*
                Shortcut for 'cargo clean`.

:Cdoc <args>                                                         *:Cdoc*
                Shortcut for 'cargo doc`.

:Cinit <args>                                                       *:Cinit*
                Shortcut for 'cargo init`.

:Crun <args>                                                         *:Crun*
                Shortcut for 'cargo run`.

:Ctest <args>                                                       *:Ctest*
                Shortcut for 'cargo test`.

:Cupdate <args>                                                   *:Cupdate*
                Shortcut for 'cargo update`.

:Cbench <args>                                                     *:Cbench*
                Shortcut for 'cargo bench`.

:Csearch <args>                                                   *:Csearch*
                Shortcut for 'cargo search`.

:Cpublish <args>                                                 *:Cpublish*
                Shortcut for 'cargo publish`.

:Cinstall <args>                                                 *:Cinstall*
                Shortcut for 'cargo install`.

:Cruntarget <args>                                                 *:Cruntarget*
                Shortcut for 'cargo run --bin' or 'cargo run --example',
                depending on the currently open buffer.

Formatting
----------

:RustFmt                                                       *:RustFmt*
		Runs |g:rustfmt_command| on the current buffer. If
		|g:rustfmt_options| is set then those will be passed to the
		executable.

		If |g:rustfmt_fail_silently| is 0 (the default) then it
		will populate the |location-list| with the errors from
		|g:rustfmt_command|. If |g:rustfmt_fail_silently| is set to 1
		then it will not populate the |location-list|.

:RustFmtRange                                                  *:RustFmtRange*
		Runs |g:rustfmt_command| with selected range. See
		|:RustFmt| for any other information.


Playpen integration
-------------------

:RustPlay                                                          *:RustPlay*
		This command will only work if you have web-api.vim installed
		(available at https://github.com/mattn/webapi-vim).  It sends the
		current selection, or if nothing is selected, the entirety of the
		current buffer to the Rust playpen, and emits a message with the
		shortened URL to the playpen.

		|g:rust_playpen_url| is the base URL to the playpen, by default
		"https://play.rust-lang.org/".

		|g:rust_shortener_url| is the base url for the shorterner, by
		default "https://is.gd/"

		|g:rust_clip_command| is the command to run to copy the
		playpen url to the clipboard of your system.


Evaluation of a single Rust file
--------------------------------

NOTE: These commands are useful only when working with standalone Rust files,
which is usually not the case for common Rust development. If you wish to
building Rust crates from with Vim can should use Vim's make, Syntastic, or
functionality from other plugins.


:RustRun  [args]                                                    *:RustRun*
:RustRun! [rustc-args] [--] [args]
		Compiles and runs the current file. If it has unsaved changes,
		it will be saved first using |:update|. If the current file is
		an unnamed buffer, it will be written to a temporary file
		first. The compiled binary is always placed in a temporary
		directory, but is run from the current directory.

		The arguments given to |:RustRun| will be passed to the
		compiled binary.

		If ! is specified, the arguments are passed to rustc instead.
		A "--" argument will separate the rustc arguments from the
		arguments passed to the binary.

		If |g:rustc_path| is defined, it is used as the path to rustc.
		Otherwise it is assumed rustc can be found in $PATH.

:RustExpand  [args]                                              *:RustExpand*
:RustExpand! [TYPE] [args]
		Expands the current file using --pretty and displays the
		results in a new split. If the current file has unsaved
		changes, it will be saved first using |:update|. If the
		current file is an unnamed buffer, it will be written to a
		temporary file first.

		The arguments given to |:RustExpand| will be passed to rustc.
		This is largely intended for specifying various --cfg
		configurations.

		If ! is specified, the first argument is the expansion type to
		pass to rustc --pretty. Otherwise it will default to
		"expanded".

		If |g:rustc_path| is defined, it is used as the path to rustc.
		Otherwise it is assumed rustc can be found in $PATH.

:RustEmitIr [args]                                               *:RustEmitIr*
		Compiles the current file to LLVM IR and displays the results
		in a new split. If the current file has unsaved changes, it
		will be saved first using |:update|. If the current file is an
		unnamed buffer, it will be written to a temporary file first.

		The arguments given to |:RustEmitIr| will be passed to rustc.

		If |g:rustc_path| is defined, it is used as the path to rustc.
		Otherwise it is assumed rustc can be found in $PATH.

:RustEmitAsm [args]                                             *:RustEmitAsm*
		Compiles the current file to assembly and displays the results
		in a new split. If the current file has unsaved changes, it
		will be saved first using |:update|. If the current file is an
		unnamed buffer, it will be written to a temporary file first.

		The arguments given to |:RustEmitAsm| will be passed to rustc.

		If |g:rustc_path| is defined, it is used as the path to rustc.
		Otherwise it is assumed rustc can be found in $PATH.


Running test(s)
---------------

:[N]RustTest[!] [options]                                       *:RustTest*
		Runs a test under the cursor when the current buffer is in a
		cargo project with "cargo test" command. If the command did
		not find any test function under the cursor, it stops with an
		error message.

		When N is given, adjust the size of the new window to N lines
		or columns.

		When ! is given, runs all tests regardless of current cursor
		position.

		When [options] is given, it is passed to "cargo" command
		arguments.

		When the current buffer is outside cargo project, the command
		runs "rustc --test" command instead of "cargo test" as
		fallback. All tests are run regardless of adding ! since there
		is no way to run specific test function with rustc. [options]
		is passed to "rustc" command arguments in the case.

		Takes optional modifiers (see |<mods>|):  >
		    :tab RustTest
		    :belowright 16RustTest
		    :leftabove vert 80RustTest
<
rust.vim Debugging
------------------

:RustInfo                                                          *:RustInfo*
		Emits debugging info of the Vim Rust plugin.

:RustInfoToClipboard                                      *:RustInfoClipboard*
		Saves debugging info of the Vim Rust plugin to the default
		register.

:RustInfoToFile [filename]                                   *:RustInfoToFile*
		Saves debugging info of the Vim Rust plugin to the given file,
		overwriting it.

==============================================================================
MAPPINGS                                                       *rust-mappings*

This plugin defines mappings for |[[| and |]]| to support hanging indents.

==============================================================================
 vim:tw=78:sw=4:noet:ts=8:ft=help:norl: