1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
# rust-mode
[](https://melpa.org/#/rust-mode)
[](https://github.com/rust-lang/rust-mode/actions?query=workflow%3ACI)
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [rust-mode](#rust-mode)
- [Introduction](#introduction)
- [Known issues](#known-issues)
- [Installation](#installation)
- [Melpa](#melpa)
- [Manual installation](#manual-installation)
- [Feature guide](#feature-guide)
- [Indentation](#indentation)
- [Code formatting](#code-formatting)
- [Running / testing / compiling code](#running--testing--compiling-code)
- [Clippy](#clippy)
- [Easy insertion of dbg!](#easy-insertion-of-dbg)
- [More commands](#more-commands)
- [LSP](#lsp)
- [eglot](#eglot)
- [lsp-mode](#lsp-mode)
- [Auto-completion](#auto-completion)
- [Other recommended packages](#other-recommended-packages)
- [flycheck](#flycheck)
- [cargo.el](#cargoel)
- [cargo-mode](#cargo-mode)
- [rustic](#rustic)
- [For package maintainers](#for-package-maintainers)
- [Tests](#tests)
- [Contributing](#contributing)
<!-- markdown-toc end -->
## Introduction
`rust-mode` makes editing [Rust](http://rust-lang.org) code with Emacs
enjoyable. It requires Emacs 25 or later, and is included in both
[Emacs Prelude](https://github.com/bbatsov/prelude) and
[Spacemacs](https://github.com/syl20bnr/spacemacs) by default.
This mode provides:
- Syntax highlighting (for Font Lock Mode)
- Indentation
- Integration with Cargo, clippy and rustfmt
This mode does _not_ provide autocompletion, or jumping to function /
trait definitions. See [Auto-completion / code
navigation](#auto-completion--code-navigation) below for tips on how
to enable this.
## Known issues
- `rust-syntax-propertize` and `adaptive-wrap-prefix-mode` can lead to
severe lag when editing larger files
(https://github.com/brotzeit/rustic/issues/107)
## Installation
### Melpa
The package is available on MELPA. Add this to your init.el.
``` elisp
(require 'package)
(add-to-list 'package-archives
'("melpa" . "https://melpa.org/packages/") t)
(package-initialize)
(package-refresh-contents)
```
Now you can install `rust-mode` with:
`M-x package-install rust-mode`
And put this in your config to load rust-mode automatically:
`(require 'rust-mode)`
### NonGNU ELPA
[NonGNU ELPA](https://elpa.nongnu.org/) can be used out of the box in
emacs28.
For older versions you need to add something like the following to
your init file:
``` elisp
(with-eval-after-load 'package (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))
```
### Manual installation
Clone this repository locally, and add this to your init.el:
``` elisp
(add-to-list 'load-path "/path/to/rust-mode/")
(autoload 'rust-mode "rust-mode" nil t)
```
## Feature guide
### Indentation
Commands like <kbd>TAB</kbd> should indent correctly.
The Rust style guide recommends spaces rather than tabs for
indentation; to follow the recommendation add this to your init.el,
which forces indentation to always use spaces.
```elisp
(add-hook 'rust-mode-hook
(lambda () (setq indent-tabs-mode nil)))
```
### Code formatting
The `rust-format-buffer` function will format your code with
[rustfmt](https://github.com/rust-lang/rustfmt) if installed. By
default, this is bound to <kbd>C-c C-f</kbd>.
The variable `rust-format-on-save` enables automatic formatting on
save. For example, add the following in your init.el to enable format
on save:
``` elisp
(setq rust-format-on-save t)
```
### Prettifying
You can toggle prettification of your code by running `M-x
prettify-symbols-mode`. If you'd like to automatically enable this
for all rust files, add the following to your init.el.
```elisp
(add-hook 'rust-mode-hook
(lambda () (prettify-symbols-mode)))
```
You can add your own prettifications to `rust-prettify-symbols-alist`.
For example, to display `x.add(y)` as `x∔(y)`, simply add to your init
file `(push '(".add" . ?∔) rust-prettify-symbols-alist)`.
### Running / testing / compiling code
The `rust-run`, `rust-test`, `rust-compile` and `rust-check` functions
shell out to Cargo to run, test, build and check your code. Under the
hood, these use the standard Emacs `compile` function.
These are not bound by default. To bind these to keyboard shortcuts,
you can use the following in your init.el:
``` elisp
(define-key rust-mode-map (kbd "C-c C-c") 'rust-run)
```
### Clippy
`rust-run-clippy` runs
[Clippy](https://github.com/rust-lang/rust-clippy), a linter.
### Easy insertion of dbg!
`rust-dbg-wrap-or-unwrap` either wraps or unwraps the current region
in `dbg!`. This can be useful for easily adding debug lines to your
program.
This is bound to <kbd>C-c C-d</kbd> by default.
### More commands
- `rustic-toggle-mutability` toggle mut for var defined at current line
## LSP
### eglot
A lightweight lsp client.
```elisp
(add-hook 'rust-mode-hook 'eglot-ensure)
```
### lsp-mode
Provides more features and you can enhance the functionality
by using additional packages. You can find more information in the
[lsp-mode wiki](https://emacs-lsp.github.io/lsp-mode/page/installation/#vanilla-emacs).
```elisp
(add-hook 'rust-mode-hook #'lsp)
```
## Auto-completion
You can either use a lsp client or [racer](https://github.com/racer-rust/racer)
with [emacs-racer](https://github.com/racer-rust/emacs-racer#installation).
## Other recommended packages
### flycheck
[flycheck](https://github.com/flycheck/flycheck) allows highlighting
compile errors and Clippy lints inline.
### cargo.el
[cargo.el](https://github.com/kwrooijen/cargo.el) provides a minor
mode for integration with Cargo, Rust's package manager.
### cargo-mode
[cargo-mode](https://github.com/ayrat555/cargo-mode) is an Emacs minor
mode which allows to dynamically select a Cargo command. The reasons
behind this package can be found in [the
post](https://www.badykov.com/emacs/2021/05/29/emacs-cargo-mode/).
### rustic
[rustic](https://github.com/brotzeit/rustic) is based on rust-mode,
extending it with other features such as integration with LSP and with
flycheck.
## For package maintainers
### Tests
Run elisp tests:
``` bash
make test
```
## Contributing
Contributions are very welcome. We are also looking for additional maintainers.
|
