rust-mode

Emacs configuration for Rust

Programming language: Emacs Lisp

License: Apache License 2.0

Tags: Development Tools     IDEs     Emacs    

Latest version: v0.5.0

README

rust-mode

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --> Table of Contents

• rust-mode
  • Introduction
  • Known issues
  • Installation
    • Melpa
    • Manual installation
  • Feature guide
    • Indentation
    • Code formatting
    • Prettifying
    • Running / testing / compiling code
    • Clippy
    • Easy insertion of dbg!
    • More commands
  • highlighting with tree-sitter
  • LSP
    • eglot
    • lsp-mode
  • Auto-completion
  • Other recommended packages
    • flycheck
    • cargo.el
    • cargo-mode
    • rustic
  • Optional features
  • For package maintainers
    • Tests
  • Contributing

<!-- markdown-toc end -->

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 autocompletion, 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 (https://github.com/brotzeit/rustic/issues/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.

These are not bound by default. To bind these to keyboard shortcuts, you can use the following in your init.el:

(define-key rust-mode-map (kbd "C-c C-c") 'rust-run)

Clippy

rust-run-clippy runs 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 C-c C-d by default.

More commands

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

highlighting with tree-sitter

You should 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 try 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.