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
|
[](https://melpa.org/#/rust-mode)
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [Introduction](#introduction)
- [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)
- [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 include 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 [Integration with Rust Language Server](#rust-language-server)
below for tips on how to enable this.
# 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 <TAB> 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 `C-c C-f`.
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` and `rust-build` functions shell out to
Cargo to run, test or build 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 `C-c C-d` 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.
## Rustic
[rustic](https://github.com/brotzeit/rustic) is a fork of rust-mode,
extending it with other features such as integration with LSP and with flycheck.
# For package maintainers
## Tests
The file `rust-mode-tests.el` contains tests that can be run via
[ERT](http://www.gnu.org/software/emacs/manual/html_node/ert/index.html).
You can use `run_rust_emacs_tests.sh` to run them in batch mode, if
you set the environment variable EMACS to a program that runs emacs.
|
