191 lines
8.6 KiB
Org Mode
191 lines
8.6 KiB
Org Mode
#+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]]
|
|
- [[#switch-to-another-lsp-server][Switch to another LSP server]]
|
|
- [[#autocompletion][Autocompletion]]
|
|
- [[#debugger-dap-integration][Debugger (dap integration)]]
|
|
- [[#automatically-reload-workspace][Automatically Reload Workspace]]
|
|
- [[#cargo][Cargo]]
|
|
- [[#cargo-edit][cargo-edit]]
|
|
- [[#cargo-audit][cargo-audit]]
|
|
- [[#cargo-outdated][cargo-outdated]]
|
|
- [[#rustfmt][Rustfmt]]
|
|
- [[#clippy][Clippy]]
|
|
- [[#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]]
|
|
- Support for [[https://github.com/nabero/ron-mode][Rusty Object Notation (RON)]]
|
|
|
|
* 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
|
|
(setq-default dotspacemacs-configuration-layers
|
|
'(lsp :variables lsp-rust-server 'rust-analyzer))
|
|
#+END_SRC
|
|
|
|
**** Switch to another LSP server
|
|
If both =rls= and =rust-analyzer= server are installed, you can press ~SPC m s s~ to switch to another LSP server backend.
|
|
|
|
**** 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=.
|
|
|
|
**** Automatically Reload Workspace
|
|
When the LSP server is =rust-analyzer=, it may needs to reload the workspace to pickup changes made in =Cargo.toml=.
|
|
You can call =spacemacs/lsp-rust-analyzer-reload-workspace=, which would be faster than restarting the LSP backend.
|
|
|
|
You can also set =cargo-process-reload-on-modify= to =t=, then it will automatically reload the workspace after
|
|
one of the following is run:
|
|
- =cargo-process-add=
|
|
- =cargo-process-rm=
|
|
- =cargo-process-upgrade=
|
|
|
|
#+BEGIN_SRC elisp
|
|
(setq-default dotspacemacs-configuration-layers
|
|
'(lsp :variables lsp-rust-server 'rust-analyzer
|
|
cargo-process-reload-on-modify t))
|
|
#+END_SRC
|
|
|
|
** 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]].
|
|
|
|
*** cargo-edit
|
|
[[https://github.com/killercup/cargo-edit][cargo-edit]] allows you to add, remove, and upgrade dependencies by modifying your =Cargo.toml= file.
|
|
|
|
#+BEGIN_SRC sh
|
|
cargo install cargo-edit
|
|
#+END_SRC
|
|
|
|
*** cargo-audit
|
|
[[https://github.com/RustSec/cargo-audit][cargo-audit]] audits =Cargo.lock= files for crates with security vulnerabilities.
|
|
|
|
#+BEGIN_SRC sh
|
|
cargo install cargo-audit
|
|
#+END_SRC
|
|
|
|
*** cargo-outdated
|
|
[[https://github.com/kbknapp/cargo-outdated][cargo-outdated]] displays dependencies that have new version available.
|
|
|
|
#+BEGIN_SRC sh
|
|
cargo install cargo-outdated
|
|
#+END_SRC
|
|
|
|
** Rustfmt
|
|
Format Rust code according to style guidelines using [[https://github.com/rust-lang-nursery/rustfmt][rustfmt]].
|
|
|
|
#+BEGIN_SRC sh
|
|
rustup component add rustfmt
|
|
#+END_SRC
|
|
|
|
To enable automatic buffer formatting on save, set the variable =rust-format-on-save= to =t=.
|
|
|
|
** Clippy
|
|
[[https://github.com/rust-lang/rust-clippy][Clippy]] provides a collection of lints to to catch common mistakes and improve your code.
|
|
|
|
#+BEGIN_SRC sh
|
|
rustup component add clippy
|
|
#+END_SRC
|
|
|
|
* Key bindings
|
|
|
|
| Key binding | Description |
|
|
|-------------+-------------------------------------------------------------|
|
|
| ~SPC m = =~ | reformat the buffer |
|
|
| ~SPC m b R~ | reload Rust-Analyzer workspace |
|
|
| ~SPC m c .~ | repeat the last Cargo command |
|
|
| ~SPC m c /~ | search for packages on crates.io with Cargo |
|
|
| ~SPC m c =~ | format all project files with rustfmt |
|
|
| ~SPC m c a~ | add a new dependency with cargo-edit |
|
|
| ~SPC m c A~ | audit dependencies for known vulnerability with cargo-audit |
|
|
| ~SPC m c c~ | compile project |
|
|
| ~SPC m c C~ | remove build artifacts |
|
|
| ~SPC m c d~ | generate documentation |
|
|
| ~SPC m c D~ | generate documentation and open it in default browser |
|
|
| ~SPC m c e~ | run benchmarks |
|
|
| ~SPC m c E~ | run a project example |
|
|
| ~SPC m c i~ | initialise a new project with Cargo (init) |
|
|
| ~SPC m c l~ | run linter ([[https://github.com/arcnmx/cargo-clippy][cargo-clippy]]) |
|
|
| ~SPC m c n~ | create a new project with Cargo (new) |
|
|
| ~SPC m c o~ | display outdated dependencies ([[https://github.com/kbknapp/cargo-outdated][cargo-outdated]]) |
|
|
| ~SPC m c r~ | remove a dependency with cargo-edit |
|
|
| ~SPC m c u~ | update dependencies with Cargo |
|
|
| ~SPC m c U~ | upgrade dependencies to LATEST version with cargo-edit |
|
|
| ~SPC m c v~ | check (verify) a project with Cargo |
|
|
| ~SPC m c x~ | execute the default binary |
|
|
| ~SPC m c X~ | execute a specific binary |
|
|
| ~SPC m g g~ | jump to definition |
|
|
| ~SPC m h h~ | describe symbol at point |
|
|
| ~SPC m s s~ | switch to other LSP server backend |
|
|
| ~SPC m t a~ | test current project |
|
|
| ~SPC m t t~ | run the current test |
|
|
| ~SPC m t b~ | run all tests in current buffe |
|
|
|
|
** 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]].
|