diff options
Diffstat (limited to 'doc/rust.txt')
| -rw-r--r-- | doc/rust.txt | 490 |
1 files changed, 0 insertions, 490 deletions
diff --git a/doc/rust.txt b/doc/rust.txt deleted file mode 100644 index 6dbb1a2c..00000000 --- a/doc/rust.txt +++ /dev/null @@ -1,490 +0,0 @@ -if !exists('g:polyglot_disabled') || index(g:polyglot_disabled, 'rust') == -1 - -*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 the given - file, overwritting 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: - -endif |