spacemacs/layers/+lang/rust/README.org

#+TITLE: Rust layer

#+TAGS: general|layer|multi-paradigm|programming

[[file:img/rust.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
  - [[#choosing-a-backend][Choosing a backend]]
    - [[#racer][Racer]]
    - [[#lsp][LSP]]
      - [[#autocompletion][Autocompletion]]
      - [[#debugger-dap-integration][Debugger (dap integration)]]
  - [[#cargo][Cargo]]
  - [[#rustfmt][Rustfmt]]
- [[#key-bindings][Key bindings]]
  - [[#debugger][debugger]]

* Description
This layer supports [[https://www.rust-lang.org][Rust]] development in Spacemacs.

** Features:
- Auto-completion and navigation support through [[https://github.com/emacs-lsp/lsp-mode][lsp-mode]] or [[https://github.com/phildawes/racer][Racer]]
- Interactive debugger using [[https://github.com/emacs-lsp/dap-mode][dap-mode]]
- support for the Rust package manager [[http://doc.crates.io/index.html][Cargo]]

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =rust= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Choosing a backend
To choose a default backend set the layer variable =rust-backend=:

#+BEGIN_SRC elisp
  (rust :variables rust-backend 'racer)
#+END_SRC

Alternatively the =lsp= backend will be automatically chosen if the layer =lsp=
is used and you did not specify any value for =rust-backend=.

Backend can be chosen on a per project basis using directory local variables
(files named =.dir-locals.el= at the root of a project), an example to use the
=lsp= backend:

#+BEGIN_SRC elisp
  ;;; Directory Local Variables
  ;;; For more information see (info "(emacs) Directory Variables")

  ((rust-mode (rust-backend . lsp)))
#+END_SRC

*Note:* you can easily add a directory local variable with ~SPC f v d~.

*** Racer
You must install [[https://github.com/phildawes/racer][Racer]] to use this backend. Make sure the =racer= binary is available in
your =PATH= and to set the environment variable =RUST_SRC_PATH=, as described in
the [[https://github.com/phildawes/racer#installation][installation instructions]].

To enable auto-completion, ensure that the =auto-completion= layer is enabled.

*** LSP
You must add =lsp= to the existing =dotspacemacs-configuration-layers= in your =~/.spacemacs=.

Consult the installation command for the desired language server found at [[https://github.com/emacs-lsp/lsp-mode][lsp-mode]] for instructions.

The default LSP server for Rust is [[https://github.com/rust-lang/rls][rls]], i.e. rust language server.
To choose the experimental [[https://github.com/rust-analyzer/rust-analyzer][rust-analyzer]], you need to set the layer variable =lsp-rust-server= of =lsp= layer:

#+BEGIN_SRC elisp
  (lsp :variables lsp-rust-server 'rust-analyzer)
#+END_SRC

**** Autocompletion
To enable auto-completion, ensure that the =auto-completion= layer is enabled.

By default, currently [[https://github.com/phildawes/racer][Racer]] is the only code completion backend of [[https://github.com/rust-lang/rls][rls]], so you also need to install it.

**** Debugger (dap integration)
To install the debug adapter you may run =M-x dap-gdb-lldb-setup= when you are on Linux or download it manually from [[https://marketplace.visualstudio.com/items?itemName=webfreak.debug][Native Debug]] and adjust =dap-gdb-lldb-path=.

** Cargo
[[http://doc.crates.io/index.html][Cargo]] is a project management command line tool for Rust. Installation
instructions can be found on the main page of [[http://doc.crates.io/index.html][Cargo]].

** Rustfmt
Format Rust code according to style guidelines using [[https://github.com/rust-lang-nursery/rustfmt][rustfmt]].

#+BEGIN_SRC sh
  cargo install rustfmt
#+END_SRC

To enable automatic buffer formatting on save, set the variable =rust-format-on-save= to =t=.

* Key bindings

| Key binding | Description                                 |
|-------------+---------------------------------------------|
| ~SPC m = =~ | reformat the buffer                         |
| ~SPC m c .~ | repeat the last Cargo command               |
| ~SPC m c C~ | remove build artifacts with Cargo           |
| ~SPC m c X~ | execute a project example with Cargo        |
| ~SPC m c c~ | compile project with Cargo                  |
| ~SPC m c d~ | generate documentation with Cargo           |
| ~SPC m c e~ | run benchmarks with Cargo                   |
| ~SPC m c f~ | format all project files with rustfmt       |
| ~SPC m c i~ | create a new project with Cargo (init)      |
| ~SPC m c l~ | run linter ([[https://github.com/arcnmx/cargo-clippy][cargo-clippy]]) with Cargo        |
| ~SPC m c n~ | create a new project with Cargo (new)       |
| ~SPC m c o~ | run all tests in current file with Cargo    |
| ~SPC m c s~ | search for packages on crates.io with Cargo |
| ~SPC m c t~ | run the current test with Cargo             |
| ~SPC m c u~ | update dependencies with Cargo              |
| ~SPC m c x~ | execute a project with Cargo                |
| ~SPC m c v~ | check (verify) a project with Cargo         |
| ~SPC m g g~ | jump to definition                          |
| ~SPC m h h~ | describe symbol at point                    |
| ~SPC m t~   | run tests with Cargo                        |

** debugger
Using the =dap= layer you'll get access to all the DAP key bindings, see the
complete list of key bindings on the [[https://github.com/syl20bnr/spacemacs/tree/develop/layers/%2Btools/dap#key-bindings][dap layer description]].