Repository files navigation

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
  • tree-sitter
  • LSP
    • eglot
    • lsp-mode
  • Auto-completion
  • Other recommended packages
    • flycheck
    • cargo.el
    • cargo-mode
    • rustic
  • Optional features
  • For package maintainers
    • Tests
  • Contributing

rust-mode makes editingRust code with Emacsenjoyable. It requires Emacs 25 or later, and is included in bothEmacs Prelude andSpacemacs by default.

This mode provides:

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

This mode doesnot provide auto completion, or jumping to function /trait definitions. SeeAuto-completion below for tips on howto enable this.

If you are missing features in rust-mode, please check outrustic before you open a featurerequest. It depends on rust-mode and provides additional features. Thisallows us to keep rust-mode light-weight for users that are happy withbasic functionality.

• rust-syntax-propertize andadaptive-wrap-prefix-mode can lead tosevere lag when editing larger files(brotzeit/rustic#107)

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 installrust-mode with:

M-x package-install rust-mode

And put this in your config to load rust-mode automatically:

(require 'rust-mode)

NonGNU ELPA can be used out of the box inemacs28.

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

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

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"nilt)(add-to-list'auto-mode-alist '("\\.rs\\'". rust-mode))

Commands likeTAB should indent correctly.

The Rust style guide recommends spaces rather than tabs forindentation; 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-modenil)))

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

Therust-format-buffer function will format your code withrustfmt if installed. Bydefault, this is bound toC-c C-f.

The variablerust-format-on-save enables automatic formatting onsave. For example, add the following in your init.el to enable formaton save:

(setq rust-format-on-savet)

You can toggle prettification of your code by runningM-x prettify-symbols-mode. If you'd like to automatically enable thisfor 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 torust-prettify-symbols-alist.For example, to displayx.add(y) asx∔(y), simply add to your initfile(push '(".add" . ?∔) rust-prettify-symbols-alist).

Therust-run,rust-test,rust-compile andrust-check functionsshell out to Cargo to run, test, build and check your code. Under thehood, these use the standard Emacscompile function.

By default these are bound to:

• C-c C-c C-urust-compile
• C-c C-c C-krust-check
• C-c C-c C-trust-test
• C-c C-c C-rrust-run

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

rust-run-clippy runsClippy, a linter. Bydefault, this is bound toC-c C-c C-l.

rust-dbg-wrap-or-unwrap either wraps or unwraps the current regionindbg!. This can be useful for easily adding debug lines to yourprogram.

This is bound toC-c C-d by default.

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

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

(use-package rust-mode:init  (setq rust-mode-treesitter-derivet))

In case you want to use treesitter but can't use Emacs 29.1, you cantake a look attree-sitter. Whenthe 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))

A lightweight lsp client.

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

Provides more features and you can enhance the functionalityby using additional packages. You can find more information in thelsp-mode wiki.

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

You can either use a lsp client orracerwithemacs-racer.

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

flycheck allows highlightingcompile errors and Clippy lints inline.

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

cargo-mode is an Emacs minormode which allows to dynamically select a Cargo command. The reasonsbehind this package can be found inthepost.

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

The features of the following files can be disabled withrust-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 implementationsfor those features.

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

Run elisp tests:

maketest

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