docs/development/languages/rust/editors.md

# Rust editor configuration

As there is no specific editor for Rust development on Fuchsia, `vim` and `VS Code` are the
most popular options. However, documentation for setting up any editor is welcome in this document.

## `rust-analyzer` setup {#rust-analyzer}

[rust-analyzer](https://rust-analyzer.github.io/) is a [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP)
implementation for Rust. This is the recommended workflow and will work with minimal editor setup.

`rust-analyzer` uses a file in the `out/` directory called `rust-project.json` that is
generated based on the build graph at `gn gen` time. A symlink to the `rust-project.json` is located
in the root directory of the Fuchsia tree.

The `rust-project.json` file format is currently unstable. Sometimes this can cause an
unexpected version mismatch where GN produces a `rust-project.json` that `rust-analyzer` is
not expecting, causing `rust-analyzer` to not work correctly.

### Currently supported version {#supported-rust-analyzer-version}

Currently, use [the **latest version** of `rust-analyzer`][rust-analyzer-latest].

## Visual Studio Code {#visual-studio-code}

To setup `rust-analyzer` on VS Code, see the VS Code guide
[Additional Vs Code extensions for Fuchsia][vscode-extension-guide].

## Vim

Install [`rust-lang/rust.vim`](https://github.com/rust-lang/rust.vim), which also integrates with:

*   [Tagbar](https://github.com/preservim/tagbar): universal-ctags is strongly recommended, but
    other ctags implementations are also supported.

*   [Syntastic](https://github.com/vim-syntastic/syntastic): `rust.vim` automatically registers
    `cargo` as a syntax checker for Rust. Yet it will fail unless you [set up cargo][cargo-setup].
    If you want to disable the integration (or use `rust-analyzer` to check the code, e.g. via
    YouCompleteMe), add the following to your `~/.vimrc`:

    ```
    let g:syntastic_rust_checkers = []
    ```

*   Auto formatting: to run `rustfmt` on save (disabled by default), add the following to `~./vimrc`:

    ```
    let g:rustfmt_command = '{{ "<var>" }}FUCHSIA_DIR{{ "</var>" }}/prebuilt/third_party/rust/{{ "<var>" }}HOST_OS{{ "</var>" }}/bin/rustfmt'
    let g:rustfmt_autosave = 1
    ```

For IDE support, see the vim section of the [rust-analyzer
manual](https://rust-analyzer.github.io/manual.html#vimneovim). For YouCompleteMe, add
`--rust-completer` (or `--all`) if you are installing from source, and it should work out of the
box. You can also specify the path to a standalone `rust-analyzer` in your `~/.vimrc` (this is not
guaranteed to work due to version compatibility); here is an example assuming it is installed to
`~/.local/bin/rust-analyzer` (note the intentional absence of `/bin` in the path):

```
let g:ycm_rust_toolchain_root = $HOME . '/.local'
```

## emacs

### Completion

See the [rust-analyzer manual](https://rust-analyzer.github.io/manual.html#emacs) for instructions.

### Check on save

You will be using [flycheck](https://www.flycheck.org/en/latest/) to compile
your Rust files when you save them.  flycheck will parse those outputs and
highlight errors.  You'll also use
[flycheck-rust](https://github.com/flycheck/flycheck-rust) so that it will
compile with cargo and not with rustc.  Both are available from
[melpa](https://melpa.org/#/).

Note that this workflow is based on cargo, which is more likely to break than
rust-analyzer based workflows.

If you don't yet have melpa, follow the instructions
[here](https://melpa.org/#/getting-started).

Install `flycheck` and `flycheck-rust` in `M-x list-packages`.  Type `i`
to queue for installation what you are missing and then `x` to execute.

Next, make sure that flycheck-rust is run at startup.  Put this in your `.emacs` files:

```elisp
(with-eval-after-load 'rust-mode
  (add-hook 'flycheck-mode-hook #'flycheck-rust-setup))
```

You'll want cargo to run "check" and not "test" so set
`flycheck-rust-check-tests` to `nil`.  You can do this by typing `C-h v
flycheck-rust-check-tests<RET>` and then customizing the variable in the normal
way.

Now, you'll want to make sure that the default `cargo` and `rustc` that you are
using are Fuchsia versions of those.  If you haven't already,
[install rustup](https://rustup.rs/). Then, from your Fuchsia root, type:

```posix-terminal
rustup toolchain link fuchsia {{ '<var>' }}FUCHSIA_DIR{{ '</var>' }}/prebuilt/third_party/rust/{{ '<var>' }}HOST_OS{{ '</var>' }}
rustup default fuchsia
```

Finally, follow the steps to [generate a `Cargo.toml`][cargo-toml-gen] for the GN target that you
want to work on.

You can [read about](http://www.flycheck.org/en/latest/user/error-reports.html)
adjusting flycheck to display your errors as you like.  Type `C-h v
flycheck-highlighting-mode<RET>` and customize it.  Also customize `C-h v
flycheck-indiation-mode<RET>`.

Now restart emacs and try it out.

### Test and debug

To test that it works, you can run `M-x flycheck-compile` and see the
command-line that flycheck is using to check syntax.  It ought to look like one
of these depending on whether you are in a lib or bin:

```sh
cargo check --lib --message-format\=json
cargo check --bin recovery_netstack --message-format\=json
```

If it runs `rustc` instead of `cargo`, that's because you didn't `fx gen-cargo`.

Note that it might report errors on the first line of the current file.  Those are
actually errors from a different file.  The error's comment will name the
problematic file.

## Sublime Text {#sublime-text}

### Using Rust-Enhanced for syntax checking

Follow the [instructions][cargo-setup] to generate `Cargo.toml` and `.cargo/config`, which will also
setup `cargo` to use the Fuchsia Rust toolchain.

Then, install the [Rust Enhanced](https://packagecontrol.io/packages/Rust%20Enhanced) plugin.
Now, you should have syntax checking on save and be able to run `cargo check` from the
context menu / command palette. Thanks to `fargo`, some tests also appear to run OK, but this
hasn't been thoroughly tested.

### Using a language server for intellisense / hover tooltips / go-to-definition

#### Setup

First, install the [LSP package](https://github.com/sublimelsp/LSP) for Sublime. Then,
follow  the [rust-analyzer setup instructions](https://rust-analyzer.github.io/manual.html#sublime-text-3)
for Sublime.

#### Usage

In order for the language server to work, you need to open a folder that contains a `Cargo.toml`
as the root of your Sublime project. There are two ways you can do this:

1. Open a new Sublime window for the folder that contains the `Cargo.toml` (e.g.
`garnet/foo/path/to/target`)
2. Or, go to the top menu bar -> Project -> Add Folder to Project. This will keep all your files
inside one Sublime window, and works even if you have the broader `fuchsia` folder also open.

You may need to restart Sublime after these steps.

## Intellij (Custom code completion)

See instructions on [the Intellij Rust site](https://intellij-rust.github.io/).
Finally, follow [these steps][cargo-toml-gen] to generate a `Cargo.toml` file for use by Intellij.
Note that cargo-based workflows are more likely to break than rust-analyzer based ones.

[rust-analyzer-latest]: https://github.com/rust-analyzer/rust-analyzer/releases
[vscode-extension-guide]: /docs/reference/tools/editors/vscode/extensions.md#rust-analyzer
[vscode-download]: https://code.visualstudio.com/Download
[vscode-update]:  https://vscode-docs.readthedocs.io/en/stable/supporting/howtoupdate/
[vscode-disable-telemetry]: https://code.visualstudio.com/docs/getstarted/telemetry#_disable-telemetry-reporting
[vscode-rust-analyzer]: https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer
[vscode-downgrade]: https://code.visualstudio.com/updates/v1_30#_install-previous-versions
[cargo-setup]: /docs/development/languages/rust/cargo.md
[cargo-toml-gen]: /docs/development/languages/rust/cargo.md#cargo-toml-gen