merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,139 +1,131 @@
|
|||
#+TITLE: lang/rust
|
||||
#+DATE: June 5, 2019
|
||||
#+SINCE: v3.0.0
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :lang rust
|
||||
#+subtitle: Fe2O3.unwrap().unwrap().unwrap().unwrap()
|
||||
#+created: September 30, 2015
|
||||
#+since: 0.7
|
||||
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#hacks][Hacks]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#install][Install]]
|
||||
- [[#arch-linux][Arch Linux]]
|
||||
- [[#general][General]]
|
||||
- [[#other-requirements][Other Requirements]]
|
||||
- [[#features][Features]]
|
||||
- [[#lsp-support-rls-or-rust-analyzer][LSP support (rls or rust-analyzer)]]
|
||||
- [[#format-on-save][Format on save]]
|
||||
- [[#keybinds][Keybinds]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#enable-rls-by-default][Enable RLS by default]]
|
||||
- [[#enabling-eglot-support-for-rust][Enabling eglot support for Rust]]
|
||||
- [[#troubleshooting][Troubleshooting]]
|
||||
- [[#errore0670-async-fn-is-not-permitted-in-the-2015-edition][error[E0670]: `async fn` is not permitted in the 2015 edition]]
|
||||
|
||||
* Description
|
||||
* Description :unfold:
|
||||
This module adds support for the Rust language and integration for its tools,
|
||||
e.g. ~cargo~.
|
||||
|
||||
+ Code completion (=racer= or an LSP server)
|
||||
+ Syntax checking (=flycheck=)
|
||||
+ LSP support (for rust-analyzer and rls) (=rustic=)
|
||||
+ Snippets
|
||||
- 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
|
||||
|
||||
** Module Flags
|
||||
+ ~+lsp~ to add support Language server protocol. Will use the first of
|
||||
=rust-analyzer= or =rls= (in that order).
|
||||
** Maintainers
|
||||
- @hlissner
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/brotzeit/rustic][rustic]]
|
||||
+ [[https://github.com/racer-rust/emacs-racer][racer]]* (unless =+lsp=)
|
||||
[[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 =:tools lsp= module
|
||||
- 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.
|
||||
|
||||
* Prerequisites
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
** Install
|
||||
|
||||
This module requires ~rust~, which can be acquired through =rustup=.
|
||||
|
||||
*** Arch Linux
|
||||
|
||||
#+begin_src sh
|
||||
sudo pacman -S rustup
|
||||
#+end_src
|
||||
|
||||
See also the Rust article [[https://wiki.archlinux.org/title/Rust#Rustup][on the Arch Wiki]].
|
||||
|
||||
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
|
||||
|
||||
*** General
|
||||
* 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
|
||||
|
||||
Additional requirements depend on the module's configuration:
|
||||
|
||||
+ If =:editor format= is enabled, you'll need =rustfmt=: ~rustup component add
|
||||
- If [[doom-module:][:editor format]] is enabled, you'll need =rustfmt=: ~$ rustup component add
|
||||
rustfmt-preview~.
|
||||
+ Users without =+lsp= enabled will need =racer=: ~cargo +nightly install racer~
|
||||
- Users without [[doom-module:][+lsp]] enabled will need [[doom-package:][racer]]: ~$ cargo +nightly install racer~
|
||||
(with requires rust nightly edition).
|
||||
+ Users with =+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~
|
||||
- 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
|
||||
|
||||
* Features
|
||||
** 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 =:tools lsp= module enabled.
|
||||
3. The ~+lsp~ flag on this module enabled.
|
||||
2. The [[doom-module:][:tools lsp]] module enabled.
|
||||
3. The [[doom-module:][+lsp]] flag on this module enabled.
|
||||
|
||||
** Format on save
|
||||
Enable the [[file:../../../modules/editor/format/README.org][:editor format]] module's =+onsave= flag to get formatting on save with
|
||||
rustfmt. No additional configuration is necessary.
|
||||
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~ |
|
||||
| =<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
|
||||
selected by default. Modify ~rustic-lsp-server~ to change the default:
|
||||
|
||||
#+BEGIN_SRC elisp
|
||||
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
|
||||
#+end_src
|
||||
|
||||
** Enabling eglot support for Rust
|
||||
Doom's =:tools lsp= module has an =+eglot= flag. Enable it and this module will
|
||||
use eglot instead.
|
||||
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 =:editor
|
||||
format= enabled).
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue