branch: elpa/rust-mode
commit 405ac98629af1a232c1000328b6becce4bcaeeb8
Author: brotzeit <brotzeitmac...@gmail.com>
Commit: brotzeit <brotzeitmac...@gmail.com>
update readme
close #377
---
README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++------------------
1 file changed, 57 insertions(+), 23 deletions(-)
diff --git a/README.md b/README.md
index ab4decd..6bddd7b 100644
--- a/README.md
+++ b/README.md
@@ -18,18 +18,23 @@
- [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)
- - [Auto-completion / code
navigation](#auto-completion--code-navigation)
- [flycheck](#flycheck)
- [cargo.el](#cargoel)
- [cargo-mode](#cargo-mode)
- - [Rustic](#rustic)
+ - [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
@@ -41,17 +46,20 @@ This mode provides:
- 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.
+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)
+ 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
@@ -71,6 +79,7 @@ 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
@@ -79,7 +88,9 @@ Clone this repository locally, and add this to your init.el:
```
## Feature guide
+
### Indentation
+
Commands like <kbd>TAB</kbd> should indent correctly.
The Rust style guide recommends spaces rather than tabs for
@@ -107,9 +118,9 @@ on save:
### 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.
+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:
@@ -119,48 +130,67 @@ you can use the following in your init.el:
```
### 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
-## Other recommended packages
+### eglot
+
+eglot is a lightweight lsp client.
-### 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.
+```elisp
+(add-hook 'rust-mode-hook 'eglot-ensure)
+```
-Two examples are:
-- [LSP](https://github.com/emacs-lsp/lsp-mode)
-- [eglot](https://github.com/joaotavora/eglot)
+### lsp-mode
-A lighter package that uses
-[racer](https://github.com/racer-rust/racer) is
-[emacs-racer](https://github.com/racer-rust/emacs-racer).
+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/).
+[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
[rustic](https://github.com/brotzeit/rustic) is based on rust-mode,
-extending it with other features such as integration with LSP and with
flycheck.
+extending it with other features such as integration with LSP and with
+flycheck.
## For package maintainers
@@ -172,3 +202,7 @@ Run elisp tests:
``` bash
make test
```
+
+## Contributing
+
+Contributions are very welcome. We are also looking for additional maintainers.
