Skip to content

Commit 6f1abc3

Browse files
holocircuitholocircuit
authored
Expand README to include more information about features (#358)
1 parent eb5270b commit 6f1abc3

File tree

1 file changed

+101
-44
lines changed

1 file changed

+101
-44
lines changed

‎README.md

+101-44
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,47 @@
11
[![MELPA](https://melpa.org/packages/rust-mode-badge.svg)](https://melpa.org/#/rust-mode)
22

3-
# Emacs mode for editing Rust source code
4-
53
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
64
**Table of Contents**
75

6+
- [Introduction](#introduction)
87
- [Installation](#installation)
98
- [Melpa](#melpa)
10-
- [straight](#straight)
11-
- [Manual Installation](#manual-installation)
12-
- [Indentation](#indentation)
13-
- [rustfmt](#rustfmt)
14-
- [Tests](#tests)
15-
- [LSP](#lsp)
16-
- [eglot](#eglot)
17-
- [lsp-mode](#lsp-mode)
18-
- [Other useful packages](#other-useful-packages)
9+
- [Manual installation](#manual-installation)
10+
- [Feature guide](#feature-guide)
11+
- [Indentation](#indentation)
12+
- [Code formatting](#code-formatting)
13+
- [Running / testing / compiling code](#running--testing--compiling-code)
14+
- [Clippy](#clippy)
15+
- [Easy insertion of !dbg](#easy-insertion-of-dbg)
16+
- [Other recommended packages](#other-recommended-packages)
17+
- [Auto-completion / code navigation](#auto-completion--code-navigation)
18+
- [flycheck](#flycheck)
19+
- [cargo.el](#cargoel)
20+
- [Rustic](#rustic)
21+
- [For package maintainers](#for-package-maintainers)
22+
- [Tests](#tests)
1923

2024
<!-- markdown-toc end -->
2125

26+
# Introduction
27+
`rust-mode` makes editing [Rust](http://rust-lang.org) code with Emacs
28+
enjoyable. It requires Emacs 24 or later, and is include in both
29+
[Emacs Prelude](https://github.com/bbatsov/prelude) and
30+
[Spacemacs](https://github.com/syl20bnr/spacemacs) by default.
31+
32+
This mode provides:
33+
- Syntax highlighting (for Font Lock Mode)
34+
- Indentation
35+
- Integration with Cargo, clippy and rustfmt
36+
37+
This mode does _not_ provide autocompletion, or jumping to function /
38+
trait definitions. See [Integration with Rust Language Server](#rust-language-server)
39+
below for tips on how to enable this.
40+
41+
2242
# Installation
2343

2444
## Melpa
25-
26-
`rust-mode` makes editing [Rust](http://rust-lang.org) code with Emacs
27-
enjoyable. It requires Emacs 24 or later.
2845
The package is available on MELPA. Add this to your init.el.
2946

3047
``` elisp
@@ -43,60 +60,100 @@ And put this in your config to load rust-mode automatically:
4360

4461
`(require 'rust-mode)`
4562

46-
## straight
47-
48-
[straight.el](https://github.com/raxod502/straight.el#install-packages) clones each of your packages directly from its source. There are good additional [installation instructions](https://github.crookster.org/switching-to-straight.el-from-emacs-26-builtin-package.el/) for moving your package management from package.el to straight.
49-
50-
## Manual Installation
51-
52-
Add this to your init.el:
63+
## Manual installation
64+
Clone this repository locally, and add this to your init.el:
5365

5466
``` elisp
5567
(add-to-list 'load-path "/path/to/rust-mode/")
5668
(autoload 'rust-mode "rust-mode" nil t)
5769
```
5870

59-
# Indentation
71+
# Feature guide
72+
## Indentation
73+
Commands like <TAB> should indent correctly.
6074

61-
The Rust style guide recommends spaces for indentation; to follow the
62-
recommendation add this to your init.el:
75+
The Rust style guide recommends spaces rather than tabs for
76+
indentation; to follow the recommendation add this to your init.el,
77+
which forces indentation to always use spaces.
6378

6479
```elisp
6580
(add-hook 'rust-mode-hook
6681
(lambda () (setq indent-tabs-mode nil)))
6782
```
6883

69-
# rustfmt
84+
## Code formatting
7085

7186
The `rust-format-buffer` function will format your code with
72-
[rustfmt](https://github.com/rust-lang/rustfmt) if installed. By default,
73-
this is bound to `C-c C-f`.
87+
[rustfmt](https://github.com/rust-lang/rustfmt) if installed. By
88+
default, this is bound to `C-c C-f`.
7489

75-
Placing `(setq rust-format-on-save t)` in your init.el will enable automatic
76-
running of `rust-format-buffer` when you save a buffer.
90+
The variable `rust-format-on-save` enables automatic formatting on
91+
save. For example, add the following in your init.el to enable format
92+
on save:
7793

78-
# Tests
94+
``` elisp
95+
(setq rust-format-on-save t)
96+
```
7997

80-
The file `rust-mode-tests.el` contains tests that can be run via
81-
[ERT](http://www.gnu.org/software/emacs/manual/html_node/ert/index.html).
82-
You can use `run_rust_emacs_tests.sh` to run them in batch mode, if
83-
you set the environment variable EMACS to a program that runs emacs.
98+
## Running / testing / compiling code
99+
100+
The `rust-run`, `rust-test` and `rust-build` functions shell out to
101+
Cargo to run, test or build your code. Under the hood, these use the
102+
standard Emacs `compile` function.
103+
104+
These are not bound by default. To bind these to keyboard shortcuts,
105+
you can use the following in your init.el:
106+
107+
``` elisp
108+
(define-key rust-mode-map (kbd "C-c C-c") 'rust-run)
109+
```
110+
111+
## Clippy
112+
`rust-run-clippy` runs
113+
[Clippy](https://github.com/rust-lang/rust-clippy), a linter.
114+
115+
## Easy insertion of !dbg
116+
`rust-dbg-wrap-or-unwrap` either wraps or unwraps the current region
117+
in `dbg!`. This can be useful for easily adding debug lines to your
118+
program.
84119

85-
# LSP
120+
This is bound to `C-c C-d` by default.
86121

87-
## eglot
88122

89-
[Installation instructions](https://github.com/joaotavora/eglot#connecting-automatically)
123+
# Other recommended packages
90124

91-
## lsp-mode
125+
## Auto-completion / code navigation
126+
This package does not provide integration with
127+
[RLS](https://github.com/rust-lang/rls), which provides
128+
auto-completion and code navigation. To use this you need an Emacs
129+
package that supports LSP.
92130

93-
[Installation instructions](https://github.com/emacs-lsp/lsp-mode#installation)
131+
Two examples are:
132+
- [LSP](https://github.com/emacs-lsp/lsp-mode)
133+
- [eglot](https://github.com/joaotavora/eglot)
94134

135+
A lighter package that uses
136+
[racer](https://github.com/racer-rust/racer) is
137+
[emacs-racer](https://github.com/racer-rust/emacs-racer).
95138

96-
You can find more information in the [lsp-mode wiki](https://github.com/emacs-lsp/lsp-mode/wiki/Rust).
139+
## flycheck
140+
[flycheck](https://github.com/flycheck/flycheck) allows highlighting
141+
compile errors and Clippy lints inline.
97142

98-
# Other useful packages
143+
## cargo.el
144+
[cargo.el](https://github.com/kwrooijen/cargo.el) provides a minor
145+
mode for integration with Cargo, Rust's package manager.
99146

100-
* [cargo.el](https://github.com/kwrooijen/cargo.el) Emacs Minor Mode for Cargo, Rust's Package Manager
101-
* [emacs-racer](https://github.com/racer-rust/emacs-racer) Racer support for Emacs
102-
* [rustic](https://github.com/brotzeit/rustic) Rust development environment for Emacs
147+
## Rustic
148+
[rustic](https://github.com/brotzeit/rustic) is a fork of rust-mode,
149+
extending it with other features such as integration with LSP and with flycheck.
150+
151+
152+
# For package maintainers
153+
154+
## Tests
155+
156+
The file `rust-mode-tests.el` contains tests that can be run via
157+
[ERT](http://www.gnu.org/software/emacs/manual/html_node/ert/index.html).
158+
You can use `run_rust_emacs_tests.sh` to run them in batch mode, if
159+
you set the environment variable EMACS to a program that runs emacs.

0 commit comments

Comments
 (0)