Skip to content

Latest commit

 

History

History
301 lines (212 loc) · 8.4 KB

README.md

File metadata and controls

301 lines (212 loc) · 8.4 KB
Raw

rust-mode

NonGNU ELPA MELPA

Table of Contents

Introduction

rust-mode makes editing Rust code with Emacs enjoyable. It requires Emacs 25 or later, and is included in both Emacs Prelude and Spacemacs by default.

This mode provides:

  • Syntax highlighting (for Font Lock Mode)
  • Indentation
  • Integration with Cargo, clippy and rustfmt

This mode does not provide auto completion, or jumping to function / trait definitions. See Auto-completion below for tips on how to enable this.

If you are missing features in rust-mode, please check out rustic before you open a feature request. It depends on rust-mode and provides additional features. This allows us to keep rust-mode light-weight for users that are happy with basic functionality.

Known issues

  • rust-syntax-propertize and adaptive-wrap-prefix-mode can lead to severe lag when editing larger files (brotzeit/rustic#107)

Installation

Melpa

The package is available on MELPA. Add this to your init.el.

(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)

NonGNU ELPA

NonGNU ELPA can be used out of the box in emacs28.

For older versions you need to add something like the following to your init file:

(with-eval-after-load 'package (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))

Manual installation

Clone this repository locally, and add this to your init.el:

(add-to-list 'load-path "/path/to/rust-mode/")
(autoload 'rust-mode "rust-mode" nil t)
(add-to-list 'auto-mode-alist '("\\.rs\\'" . rust-mode))

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.

(add-hook 'rust-mode-hook
          (lambda () (setq indent-tabs-mode nil)))

Since Emacs ≥ 24.4, electric-indent-mode is turned on by default. If you do not like it, call (electric-indent-mode 0) in rust-mode-hook.

Code formatting

The rust-format-buffer function will format your code with 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:

(setq rust-format-on-save t)

Prettifying

You can toggle prettification of your code by running M-x prettify-symbols-mode. If you'd like to automatically enable this for all rust files, add the following to your init.el.

(add-hook 'rust-mode-hook
          (lambda () (prettify-symbols-mode)))

You can add your own prettifications to rust-prettify-symbols-alist. For example, to display x.add(y) as x∔(y), simply add to your init file (push '(".add" . ?∔) rust-prettify-symbols-alist).

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.

By default these are bound to:

  • C-c C-c C-u rust-compile
  • C-c C-c C-k rust-check
  • C-c C-c C-t rust-test
  • C-c C-c C-r rust-run

To run programs requiring user input use universal argument when invoking rust-run (C-u C-c C-c C-r).

Clippy

rust-run-clippy runs Clippy, a linter. By default, this is bound to C-c C-c C-l.

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.

More commands

  • rust-toggle-mutability toggle mut for var defined at current line

tree-sitter

You can try the new native treesitter mode rust-ts-mode with:

(use-package rust-mode
  :init
  (setq rust-mode-treesitter-derive t))

In case you want to use treesitter but can't use Emacs 29.1, you can take a look at tree-sitter. When the dependencies are installed you can activate the feature with:

(use-package tree-sitter
  :config
  (require 'tree-sitter-langs)
  (global-tree-sitter-mode)
  (add-hook 'tree-sitter-after-on-hook #'tree-sitter-hl-mode))

LSP

eglot

A lightweight lsp client.

(add-hook 'rust-mode-hook 'eglot-ensure)

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.

(add-hook 'rust-mode-hook #'lsp)

Auto-completion

You can either use a lsp client or racer with emacs-racer.

Note that racer and rls are considered deprecated. You should use rust-analyzer instead.

Other recommended packages

flycheck

flycheck allows highlighting compile errors and Clippy lints inline.

cargo.el

cargo.el provides a minor mode for integration with Cargo, Rust's package manager.

cargo-mode

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.

rustic

rustic is based on rust-mode, extending it with other features such as integration with LSP and with flycheck.

Optional features

The features of the following files can be disabled with rust-load-optional-libraries.

  • rust-cargo.el
  • rust-compile.el
  • rust-playpen.el
  • rust-rustfmt.el

They are disabled by default when you use rustic as it has its own implementations for those features.

Customization

rust-cargo-default-arguments set additional cargo args used for check,compile,run,test

For package maintainers

Tests

Run elisp tests:

make test

Contributing

Contributions are very welcome. We are also looking for additional maintainers.