Organisation:	Copyright (C) 2024-2024 Olivier Boudeville
Contact:	about (dash) howtos (at) esperide (dot) com
Creation date:	Tuesday, March 12, 2024
Lastly updated:	Saturday, April 13, 2024

Overview

Rust is a multi-paradigm, general-purpose, efficient, safe language available as free software; see its official website for more details.

Documentation

One should read the official Rust book (The Rust Programming Language), which is clear and well written.

Installation

Even if done here in the context of Arch Linux, for the procedure that we recommend the actual distribution does not matter.

As we intend to develop (rather than just running or installing Rust software), we prefer relying on the Rustup toolchain manager, so that multiple toolchains, for multiple platforms and architectures, can be used.

Rather than using pacman to install its rustup package, we prefer going the more standard Rust way. One should follow the official Rust guidelines for that; here is our corresponding procedure:

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs > install-rustup.sh
# Inspect install-rustup.sh before running it.
$ sh install-rustup.sh

From now the rustc compiler and the Cargo package manager are available on the system, from one's account (in the ~/.rustup and ~/.cargo trees respectively). All Rust-related commands are then be available from ~/.cargo/bin.

One may prefer customising the installation and avoiding that one's shell configuration is automatically modified; then it is just a matter of editing typically one's ~/.bashrc or related by oneself and adding there export PATH="${HOME}/.cargo/bin:${PATH}" (another option is to add . ${HOME}/.cargo/env instead).

Then updating the current shell accordingly (e.g. . ~/.bashrc) allows to check that for example rustc can now be executed as intended.

As Rust does not perform the linking by itself, a linker (typically provided by gcc) must be available.

Afterwards Rust may be updated thanks to rustup update.

Should some day Rust and rustup have to be uninstalled, run rustup self uninstall.

Examples

Most Basic One

In ~/hello.rs:

fn main() {
   println!("Hello from Ceylan-HOWTOs!");
}

One may notice the use of a macro (! suffix), and that most lines of Rust code end with a semicolon (;).

To be compiled and linked with rustc hello.rs and run with ./hello; yields as expected: Hello from Ceylan-HOWTOs!.

This executable occupies 3.7MB (!); more information:

$ file hello
hello: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2,
BuildID[sha1]=c77ef3f032c2f1961866e0889d54d6342a9e3554, for GNU/Linux 4.4.0, with debug_info, not stripped

No need to devise one's GNU make automatic rules - cargo will do best.

Related Tools

Included with rustup

Cargo

Cargo is the Rust integrated dependency manager and build tool.

In Rust, a package of code is referred to as a crate. So Cargo is the build system and package manager of choice to access Rust community’s crate registry.

More precisely, Cargo allows installing crates and publishing ones, so that Rust projects can declare their various dependencies and so that their build is repeatable. See also the Cargo guide.

For its configuration, Cargo relies on a Cargo.toml manifest file, placed at the root of the tree of the package it applies to.

Its format is named TOML (Tom's Obvious, Minimal Language), and the various keys that it introduces are listed here.

Rustfmt

Rustfmt is the source-formatting tool of choice: it formats Rust code according to the official style guidelines [1].

[1]	e.g. indent with four spaces - not tabs; place the curly braces according to this convention, etc.

We found very useful that a stable, conventional formatting exists, and decided from the start to systematically use it. This allows a great standardization of sources, for easier readings and simplified merges.

Rustfmt should be readily available with rustup; otherwise execute rustup component add rustfmt.

External Ecosystem

rust-analyzer

This is a Language Server Protocol implementation for Rust, typically used by IDEs.

There are multiple options to install it; rather than installing as an (OS) package, we prefer once again using rustup, with: rustup component add rust-analyzer.

Once installed, running rust-analyzer --version should switch from:

error: Unknown binary 'rust-analyzer' in official toolchain 'stable-x86_64-unknown-linux-gnu'.

to something like:

rust-analyzer 1.76.0 (07dca48 2024-02-04)

As rust-analyzer will need the Rust source code, the latter can be directly installed with: rustup component add rust-src.

Using Emacs with Rust

The Emacs light-weight rust-mode can be used, yet rustic (which is based on rust-mode) provides additional features that we like.

A prerequisite thereof is rust-analyzer (and of course a recent Emacs).

Base Approach

One may rely on straight.el to manage one's Emacs packages (as a replacement for the Emacs now built-in package.el), so, provided that the straight.el bases are respected, having rustic is just a matter of adding, typically in one's ~/.emacs.d/init.el, a (straight-use-package 'rustic) line.

More Involved Approach

We prefer installing and configuring rustic with use-package rustic, as done in Robert Krahn's page; see our complete init.el for that.

Then opening a Rust source file (e.g. hello.rs) should automatically exhibit syntax highlighting and the Rustic mode.

Notably, saving a Rust source file will automatically format it with Rustfmt, which is neat.

Mode of Operation

Rust relies on LLVM to generate its code, in order to be platform and hardware-agnostic, and to achieve best performance.

Quick Facts

Rust is well suited for embedded development, because it can target many platforms (thanks to LLVM) and can be as low-level as wanted; notably using #![no_std] allows to benefit from the Rust Core Library without relying on the Rust Standard Library, for smaller binary sizes and possibly improved performance
thanks to the use of rustup and its support of toolchains, cross-compiling is rather easy; for instance, to install Rust using the stable channel for Windows, using the GNU Compiler, just execute rustup toolchain install stable-x86_64-pc-windows-gnu

Language Bindings

Short Hints

Optimizing for native CPU platform

The current target platform is given by rustup toolchain list; in our case it is stable-x86_64-unknown-linux-gnu.

Then, to request Cargo to always compile code optimized for the native CPU platform, one may add in ~/.cargo/config:

[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "target-cpu=native"]

Note that the resulting binary is expected to depend on the precise local CPU and thus should not be distributed - lest it cannot be run on other computers.

Accelerating Builds

A shared compilation cache - specifically sccache may be used to speed up builds.

See this section for more details.

Micro-Cheat Sheet

to get Rust (compiler) version: rustc -V; for cargo: cargo --version
to create a binary (application) my_project package: cargo new my_project; Git files will be generated iff not already in a clone

Rust Resources

the reference is the Rust official website