Rust

From ArchWiki

Related articles

From Wikipedia:

Rust is a multi-paradigm, general-purpose programming language that emphasizes performance, type safety, and concurrency. It enforces memory safety—meaning that all references point to valid memory—without a garbage collector. To simultaneously enforce memory safety and prevent data races, its "borrow checker" tracks the object lifetime of all references in a program during compilation. Rust was influenced by ideas from functional programming, including immutability, higher-order functions, and algebraic data types. It is popular for systems programming.

Core language

Rust Core Library

The Rust Core Library is the dependency-free foundation of the Rust Standard Library. It interfaces directly with LLVM primitives, which allows Rust to be platform and hardware-agnostic. It is this integration with LLVM that allows Rust to obtain greater performance than equivalent C applications compiled with Clang, making Rust software designed with libcore lower level than C. It contains only basic platform-independent types such as Option, Result, and Iterator. Developers looking to target software for embedded platforms may forego the standard library with #![no_std] to exclusively use the no-batteries-included core library for smaller binary sizes and improved performance. However, using #![no_std] limits the amount of software support that you can get from the larger Rust community as a majority of libraries require the standard library.

Rust Standard Library

The Rust Standard Library provides the convenient high level abstractions by which a majority of portable Rust software is created with. It features convenient features such as the Vec and String types; a vast amount of methods for language primitives; a large number of standard macros; I/O and multithreading support; heap allocations with Box; and many more high level features not available in the core library.

Release cycle

Rust follows a regular six-week release cycle, similar to the release cycle of Firefox. With each new release, the core and standard libraries are improved to support more platforms, improve performance, and stabilize new features for use with stable Rust.

Installation

The two main ways to install Rust are:

  • The Native installation, recommended if you only use Rust for running or installing software made with Rust
  • The Rustup installation, recommended if you intend to program anything in Rust

Native installation

To install the latest stable version of Rust from the official Arch Linux software repository, install the rust package. This will install the rustc compiler and Cargo.

There is also a development version of the Rust compiler available: rust-nightly-binAUR for prebuilt generic binaries or rust-gitAUR to build the compiler with system libraries.

Rustup

The official and recommended method of installing Rust for the purpose of developing software is to use the Rustup toolchain manager, written in Rust.

The benefit of using the Rustup toolchain manager instead of the standalone prepackaged Rust in the software repository is the ability to install multiple toolchains (stable, beta, nightly) for multiple targets (windows, mac, android) and architectures (x86, x86_64, arm). It should be noted that installing rustup does not automatically install a rust toolchain with it, nor does updating rustup through any method automatically provide the latest toolchain release of rust. See #Usage or rustup toolchain documentation for more on toolchains.

There are two choices for a Rustup installation, one is supported by Arch Linux via pacman, while the other is officially supported by Rust via their installation script.

Arch Linux package

rustup is available on the Arch Linux software repository. Note that rustup self update will not work when installed this way, the package needs to be updated by pacman. However, this change does not extend to other rustup functionality, such as rustup update for updating rust toolchains.

This package has the advantage that the various Rust executables live in /usr/bin, instead of ~/.cargo/bin, removing the need to add another directory to your PATH.

Note: The rustup package does not install a toolchain by default. It provides instead symlinks between /usr/bin/rustup to the common binaries such as /usr/bin/rustc and /usr/bin/cargo. As stated above, the user still needs to install a toolchain manually for these Rust commands to do anything.

In order to install the toolchain, you need to tell rustup which version to use, between stable and nightly: 

$ rustup default stable

Upstream installation script

Rustup is also available to download and install manually via rustup's official web page.

Download the file with curl --proto '=https' --tlsv1.3 -sSf https://sh.rustup.rs -o rust.sh, view it: less ./rust.sh, and run the script ./rust.sh to start rustup installation. The script makes PATH changes only to login shell configuration files. You need to source ~/.cargo/env until you logout and login back into the system. To update rustup afterwards, run rustup self update.

The script installs and activates the default toolchain by default (the one used by the rust package), so there is no need to manually install it to start using Rust.

Warning: Running curl some-url | sh, as the Rust documentation suggests, is considered a security risk, because it executes unknown code, that might even be corrupted during the download. Therefore it is recommended to manually download the script and check it, before executing it.
Note: Please make sure that ~/.cargo/bin is in your PATH when you run rustup.

Usage

You might need to manually install a toolchain, e.g. stable, beta, nightly or 1.58.0. You also need to do this if you want to use/test another toolchain. 

$ rustup toolchain install toolchain

You can now run the Rust commands by running, rustup run toolchain command. However, to use these commands directly, you need to activate the toolchain: 

$ rustup default toolchain

Check the installed Rust version using rustc -V: 

$ rustc -V 
rustc 1.58.0 (02072b482 2022-01-11)
Note:

Rust does not do its own linking, and so you’ll need to have a linker installed. You can use gcc, otherwise Rust will generate the following error: linker `cc` not found.

Note:

Rustup does not automatically update provided toolchains. If users are wishing to use the latest releases of Rust, crates, and other relevant packages, they may occasionally wish to update their toolchains with rustup update. See Official rustup documentation for more.

Test your installation

Check that Rust is installed correctly by building a simple program, as follows: 

~/hello.rs
fn main() {
    println!("Hello, World!");
}

You can compile it with rustc, then run it: 

$ rustc hello.rs && ./hello
Hello, World!

Cross compiling

Using rustup

You can easily cross-compile using Rustup. Rustup supports many cross-compile targets. A full list can be found running rustup target list.

For instance, if you want to install Rust using the stable channel for Windows, using the GNU Compiler, you will need to do: 

$ rustup toolchain install stable-x86_64-pc-windows-gnu

This will only install Rust and its tools for your target architecture, but some additional tools might be needed for cross-compiling.

Windows

In this section, $ARCH is the target architecture (either x86_64 or i686). It will explain how to cross compile using rustup.

  1. Install mingw-w64-gcc
  2. Run rustup target add $ARCH-pc-windows-gnu to install Rust standard library for your architecture.
  3. Finally, tell cargo where to find the MinGW-w64 gcc/ar by adding the following to your ~/.cargo/config:
~/.cargo/config
[target.$ARCH-pc-windows-gnu]
linker = "/usr/bin/$ARCH-w64-mingw32-gcc"
ar = "/usr/bin/$ARCH-w64-mingw32-ar"

Finally, you can cross compile for windows by passing the --target $ARCH-pc-windows-gnu to cargo: 

$ # Build
$ cargo build --release --target "$ARCH-pc-windows-gnu"
$ # Run unit tests under wine
$ cargo test --target "$ARCH-pc-windows-gnu"

Currently building executables using MinGW 6 and the toolchains installed by rustup is broken. To fix it, execute 

for lib in crt2.o dllcrt2.o libmsvcrt.a; do cp -v /usr/x86_64-w64-mingw32/lib/$lib $HOME/.rustup/toolchains/$CHANNEL-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-pc-windows-gnu/lib/; done

where CHANNEL is the update channel (stable, beta or nightly)

Unofficial packages

The unofficial repository archlinuxcn has rust-nightly and Rust std library for i686, ARM, ARMv7, Windows 32 and 64 so you can just install the one you want then enjoy cross-compiling. However, you have to find an ARM toolchain by yourself. For Windows 32bit targets, you will need to get a libgcc_s_dw2-1.dll (provided by mingw-w64-gcc) to build and run.

Cargo

Cargo, Rust's package manager, is part of the rust package. The nightly version is available in the AUR as part of rust-nightly-binAUR. If you use rustup, it already includes cargo.

Cargo is a tool that allows Rust projects to declare their various dependencies, and ensure that you will always get a repeatable build. You are encouraged to read the official guide.

Usage

To create a new project using Cargo: 

$ cargo new hello_world

This creates a directory with a default Cargo.toml file, set to build an executable.

Note: Cargo uses this Cargo.toml as a manifest containing all of the metadata required to compile your project. 
Cargo.toml
[package]
name = "hello_world"
version = "0.1.0"
edition = "2021"

[dependencies]

Optimizing for native CPU platform

In order to instruct Cargo to always compile optimal code for your CPU platform, you can achieve this by adding a flag to ~/.cargo/config. Please be aware that the resulting binaries can not be distributed for use on other computers, and might even fail on your own system if you decide to change your CPU in the future.

Find out which target platform is used by default on your installation: 

$ rustup toolchain list
stable-x86_64-unknown-linux-gnu (default)

In this example, we are using stable Rust on the x86_64-unknown-linux-gnu platform.

Instruct Cargo to always compile code optimized for the native CPU platform: 

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

sccache

Compilation times can be greatly reducing by using sccache (sccache package). This will maintain a local cache of compiler artifacts, eliminating the need to recompile code that has not changed since the last time it was compiled.

To enable sccache, you can use RUSTC_WRAPPER environment variable: 

$ export RUSTC_WRAPPER=sccache
$ cargo build

or 

$ RUSTC_WRAPPER=sccache cargo build

Alternatively, add the following configuration to ~/.cargo/config: 

~/.cargo/config
[build]
rustc-wrapper = "sccache"

IDE support

Tools

See https://www.rust-lang.org/tools for the recommended tools of the Rust project.

rust-analyzer

rust-analyzer is the official Language Server Protocol implementation for Rust which has replaced RLS.

It is available as the rust-analyzer package, and the latest Git version is available as rust-analyzer-gitAUR. Alternatively, if you have rustup installed, you can install rust-analyzer with: 

$ rustup component add rust-analyzer

rust-analyzer needs the source code of the standard library. If it is not present, rust-analyzer will attempt to install it automatically using rustup. To install the source code manually using rustup, run the following command: 

$ rustup component add rust-src

Clippy

Clippy takes advantage of compiler plugin support to provide a large number of additional lints for detecting and warning about a larger variety of errors and non-idiomatic Rust.

Clippy is included in the rust package. To install it with rustup use: 

$ rustup component add clippy

Rustfmt

Rustfmt is a tool to format Rust code according to the official style guidelines.

Rustfmt is included in the rust package. To install it with rustup use: 

$ rustup component add rustfmt

Editors

Emacs

Emacs support for Rust can be obtained via the official rust-mode plugin.

GNOME Builder

GNOME Builder support for Rust is achieved using Language Server Protocol. It uses rust-analyzer by default; all you need to do is install it along with the Rust source.

Helix

Helix editor is written in Rust and has the Rust language server protocol included. Helix is inspired by Neovim and Kakoune.

Kate

Kate support for Rust is achieved using Language Server Protocol. It uses rust-analyzer by default; all you need to do is install it along with the Rust source.

IntelliJ IDEA

IntelliJ IDEA has a Rust plugin. The same plugin also works with CLion.

If using rustup, use rustup to download the source (rustup component add rust-src), and then select ~/.rustup/toolchains/<your toolchain>/bin as the toolchain location.

If using Rust from the official Arch Linux software repository, select /usr/bin as the toolchain location and /usr/lib/rustlib/src/rust/library/ as the stdlib sources location.

Jetbrains RustRover

Jetbrains is also working on a special Editor just for Rust, which is currently only in Early Access. It can be found and downloaded under their official Website or in the AUR under rustroverAUR and rustrover-eapAUR.

Visual Studio Code

Visual Studio Code support for Rust can be obtained via rust-analyzer with the matklad.rust-analyzer extension.

Vim

Vim support for Rust can be obtained via the official rust.vim plugin, which provides file detection, syntax highlighting, formatting and support for the Syntastic syntax checking plugin. Many completion engines have Rust support, like coc (via the coc.rls plugin) and YouCompleteMe.

See also