branch: elpa/rust-mode
commit 6f1abc33d6d03661d6edd165a440c6df874e5912
Author: holocircuit <[email protected]>
Commit: GitHub <[email protected]>
Expand README to include more information about features (#358)
---
README.md | 145 +++++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 101 insertions(+), 44 deletions(-)
diff --git a/README.md b/README.md
index d78ac28..54702d3 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,47 @@
[](https://melpa.org/#/rust-mode)
-# Emacs mode for editing Rust source code
-
<!-- markdown-toc start - Don't edit this section. Run M-x
markdown-toc-refresh-toc -->
**Table of Contents**
+- [Introduction](#introduction)
- [Installation](#installation)
- [Melpa](#melpa)
- - [straight](#straight)
- - [Manual Installation](#manual-installation)
-- [Indentation](#indentation)
-- [rustfmt](#rustfmt)
-- [Tests](#tests)
-- [LSP](#lsp)
- - [eglot](#eglot)
- - [lsp-mode](#lsp-mode)
-- [Other useful packages](#other-useful-packages)
+ - [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 24 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
-
-`rust-mode` makes editing [Rust](http://rust-lang.org) code with Emacs
-enjoyable. It requires Emacs 24 or later.
The package is available on MELPA. Add this to your init.el.
``` elisp
@@ -43,60 +60,100 @@ And put this in your config to load rust-mode
automatically:
`(require 'rust-mode)`
-## straight
-
-[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.
-
-## Manual Installation
-
-Add this to your init.el:
+## 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)
```
-# Indentation
+# Feature guide
+## Indentation
+Commands like <TAB> should indent correctly.
-The Rust style guide recommends spaces for indentation; to follow the
-recommendation add this to your init.el:
+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)))
```
-# rustfmt
+## 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`.
+[rustfmt](https://github.com/rust-lang/rustfmt) if installed. By
+default, this is bound to `C-c C-f`.
-Placing `(setq rust-format-on-save t)` in your init.el will enable automatic
-running of `rust-format-buffer` when you save a buffer.
+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:
-# Tests
+``` elisp
+(setq rust-format-on-save t)
+```
-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.
+## 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.
-# LSP
+This is bound to `C-c C-d` by default.
-## eglot
-[Installation
instructions](https://github.com/joaotavora/eglot#connecting-automatically)
+# Other recommended packages
-## lsp-mode
+## 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.
-[Installation instructions](https://github.com/emacs-lsp/lsp-mode#installation)
+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).
-You can find more information in the [lsp-mode
wiki](https://github.com/emacs-lsp/lsp-mode/wiki/Rust).
+## flycheck
+[flycheck](https://github.com/flycheck/flycheck) allows highlighting
+compile errors and Clippy lints inline.
-# Other useful packages
+## cargo.el
+[cargo.el](https://github.com/kwrooijen/cargo.el) provides a minor
+mode for integration with Cargo, Rust's package manager.
-* [cargo.el](https://github.com/kwrooijen/cargo.el) Emacs Minor Mode for
Cargo, Rust's Package Manager
-* [emacs-racer](https://github.com/racer-rust/emacs-racer) Racer support for
Emacs
-* [rustic](https://github.com/brotzeit/rustic) Rust development environment
for Emacs
+## 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.
