doomemacs/modules/lang/rust/README.org

← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::lang rust][Issues]]  ↖ [[doom-module-source:lang/rust][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE:    :lang rust
#+SUBTITLE: Fe2O3.unwrap().unwrap().unwrap().unwrap()
#+CREATED:  September 30, 2015
#+SINCE:    0.7

* Description :unfold:
This module adds support for the Rust language and integration for its tools,
e.g. ~cargo~.

- Code completion ([[doom-package:][racer]] or an LSP server)
- Syntax checking ([[doom-package:][flycheck]])
- LSP support (for rust-analyzer and rls) ([[doom-package:][rustic]])
- Snippets

** Maintainers
- @hlissner

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +lsp ::
  Enable LSP support for ~rustic-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
  (supports rust-analyzer and rls).

** Packages
- [[doom-package:][rustic]]
- [[doom-package:][racer]] unless [[doom-module:][+lsp]]

** Hacks
- rustic has been modified /not/ to automatically install lsp-mode or eglot if
  they're missing. Doom expects you to have enabled the [[doom-module:][:tools lsp]] module
  yourself.

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires ~rust~, which can be acquired through =rustup=:
#+begin_src sh
curl https://sh.rustup.rs -sSf | sh
#+end_src

Note that when the Rust /language/ has updates, you are to run =rustup= such
that it doesn't upgrade itself:
#+begin_src sh
rustup update --no-self-update
#+end_src

** Other Requirements
- If [[doom-module:][:editor format]] is enabled, you'll need =rustfmt=: ~$ rustup component add
  rustfmt-preview~.
- Users without [[doom-module:][+lsp]] enabled will need [[doom-package:][racer]]: ~$ cargo +nightly install racer~
  (with requires rust nightly edition).
- Users with [[doom-module:][+lsp]] enabled will need:
  - =rust-analyzer= or =rls=
- Using the following commands requires:
  - ~cargo-process-check~: ~$ cargo install cargo-check~
  - ~cargo-process-clippy~: ~$ rustup component add clippy-preview~

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** LSP support (rls or rust-analyzer)
This module supports LSP integration. For it to work you'll need:

1. Either [[https://github.com/rust-analyzer/rust-analyzer][rust-analyzer]] or [[https://github.com/rust-lang/rls][the Rust Language Server]] installed (e.g. through your
   OS package manager).
2. The [[doom-module:][:tools lsp]] module enabled.
3. The [[doom-module:][+lsp]] flag on this module enabled.

** Format on save
Enable [[doom-module:][:editor format +onsave]] to get formatting on save with =rustfmt=. No
additional configuration is necessary.

** Keybinds
| Binding             | Description                 |
|---------------------+-----------------------------|
| =<localleader> b a= | ~cargo audit~               |
| =<localleader> b b= | ~cargo build~               |
| =<localleader> b B= | ~cargo bench~               |
| =<localleader> b c= | ~cargo check~               |
| =<localleader> b C= | ~cargo clippy~              |
| =<localleader> b d= | ~cargo doc~                 |
| =<localleader> b n= | ~cargo update~              |
| =<localleader> b o= | ~cargo outdated~            |
| =<localleader> b r= | ~cargo run~                 |
| =<localleader> t a= | ~cargo test~                |
| =<localleader> t t= | ~run current test~          |

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Enable RLS by default
If both =rls= and =rust-analyzer= are present on your system, =rust-analyzer= is
used by default. Modify ~rustic-lsp-server~ to change the default:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! rustic
  (setq rustic-lsp-server 'rls))
#+end_src

** Enabling eglot support for Rust
Doom's [[doom-module:][:tools lsp]] module has an [[doom-module:][+eglot]] flag. Enable it and this module will use
eglot instead.

* Troubleshooting
[[doom-report:][Report an issue?]]

** error[E0670]: `async fn` is not permitted in the 2015 edition
You may be seeing this error, despite having ~edition = "2018"~ in your
=Cargo.toml=. This error actually originates from ~rustfmt~, which the LSP
server tries to invoke on save (if you have ~rustic-format-on-save~ or
[[doom-module:][:editor format]] enabled).

To fix this your project needs a =rustfmt.toml= with ~edition = "2018"~ in it.

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote