[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/rust-mode 6f1abc3 438/486: Expand README to include more i
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/rust-mode 6f1abc3 438/486: Expand README to include more information about features (#358) |
Date: |
Sat, 7 Aug 2021 09:26:10 -0400 (EDT) |
branch: elpa/rust-mode
commit 6f1abc33d6d03661d6edd165a440c6df874e5912
Author: holocircuit <holocircuit@gmail.com>
Commit: GitHub <noreply@github.com>
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 @@
[![MELPA](https://melpa.org/packages/rust-mode-badge.svg)](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.
- [nongnu] elpa/rust-mode beda16d 466/486: rearrange IV: Misc, (continued)
- [nongnu] elpa/rust-mode beda16d 466/486: rearrange IV: Misc, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode f9e3618 468/486: Divide library into sections, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode e9e9e32 472/486: Add release build/run functions, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode e006788 474/486: Add .dir-locals.el, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 7fdb9c2 450/486: Use <kbd> to indicate keyboard input in README (#375), ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode d211e68 453/486: Fix various byte compilation warnings in rust-mode-tests.el., ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode bded667 457/486: Add missing ‘require’ form., ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 139a658 482/486: Create rust-rustfmt.el from existing code, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 494d59f 486/486: Make most additional libraries optional, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 9f3d8cf 432/486: rust format buffer now saves position across multiple frames (#348), ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 6f1abc3 438/486: Expand README to include more information about features (#358),
ELPA Syncer <=
- [nongnu] elpa/rust-mode e04e485 441/486: rustc-compilation-regexps: handle `note` case as compilation-info., ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 39f32cc 447/486: In emacs >= 26.2, use replace-buffer-contents after formatting, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode eca55c0 451/486: Check for -> and => early in rust-ordinary-lt-gt-p, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode ca7d99c 469/486: Set default directory when compiling., ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode c5c7ed3 471/486: Update README.md, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 4e394ac 475/486: Add Makefile, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 09b4320 476/486: test: Suppress some noisy messages, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode afeddec 325/486: Merge pull request #224 from tromey/beginning-of-defun, ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 7fd78f0 444/486: rust-goto-format-problem: make sure to always just to a buffer that exists., ELPA Syncer, 2021/08/07
- [nongnu] elpa/rust-mode 9e03890 478/486: Create rust-compile.el from existing code, ELPA Syncer, 2021/08/07