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
|
# 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)
- [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)`
### 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)
```
### 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.
## LSP
### eglot
eglot is a lightweight lsp client.
```elisp
(add-hook 'rust-mode-hook 'eglot-ensure)
```
### lsp-mode
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.
|
