doomemacs/modules/lang/rust/README.org
Henrik Lissner 63b0ebeda7
refactor!(rust): remove racer and default to +lsp
BREAKING CHANGE: Racer is no longer developed and its project page
recommends using rust-analyzer instead. Moreover, users have reported
issues trying to build/install it on recent versions of rust, so I've
removed support for Racer from Doom, and now default solely to LSP for
IDE features.

Users that want these features will need to activate the module's +lsp
flag (along with the :tools lsp module) and install rust-analyzer. See
the module's README for instructions.

Close: #6705
Co-authored-by: c1ttim <c1ttim@users.noreply.github.com>
2022-09-07 01:25:18 +02:00

127 lines
4.5 KiB
Org Mode

#+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]]
** 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 with [[doom-module:][+lsp]] enabled will need [[https://rust-analyzer.github.io/][rust-analyzer]] (rls is supported, but
[[https://blog.rust-lang.org/2022/07/01/RLS-deprecation.html][deprecated]]).
- 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-trigger~ 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