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
|
# 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)
- [Other recommended packages](#other-recommended-packages)
- [Auto-completion / code navigation](#auto-completion--code-navigation)
- [flycheck](#flycheck)
- [cargo.el](#cargoel)
- [cargo-mode](#cargo-mode)
- [Rustic](#rustic)
- [For package maintainers](#for-package-maintainers)
- [Tests](#tests)
<!-- 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 (#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.
## Other recommended packages
### Auto-completion / code navigation
This package does not provide integration with
[RLS](https://github.com/rust-lang/rls), which provides
auto-completion and code navigation. To use this you need an Emacs
package that supports LSP.
Two examples are:
- [LSP](https://github.com/emacs-lsp/lsp-mode)
- [eglot](https://github.com/joaotavora/eglot)
A lighter package that uses
[racer](https://github.com/racer-rust/racer) is
[emacs-racer](https://github.com/racer-rust/emacs-racer).
### 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
```
|
