Using Rust 1.88.0 Toolset

Red Hat Developer Tools 1

Installing and using Rust 1.88.0 Toolset

Red Hat Customer Content Services

Abstract

Rust Toolset is a Red Hat offering for developers on the Red Hat Enterprise Linux (RHEL) operating system. Use this guide for an overview of Rust Toolset, to learn how to invoke and use different versions of Rust tools, and to find resources with more in-depth information.

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. Let us know how we can improve it.

Submitting feedback through Jira (account required)

  1. Log in to the This content is not included.Jira website.
  2. Click Create in the top navigation bar.
  3. Enter a descriptive title in the Summary field.
  4. Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
  5. Click Create at the bottom of the dialogue.

Chapter 1. Rust Toolset

Rust Toolset is a Red Hat offering for developers on Red Hat Enterprise Linux (RHEL). It provides the rustc compiler for the Rust programming language, the Rust package manager Cargo, the rustfmt formatting tool, and required libraries.

Rust Toolset is available as a module for RHEL 8 and as packages for RHEL 9 and 10.

1.1. Rust Toolset components

Rust Toolset includes the Rust compiler, Cargo build system and dependency manager, and the rustfmt formatting tool, all at version 1.88.0. Each component is documented in the table with its name, version, and description.

NameVersionDescription

rust

1.88.0

The Rust compiler front-end for LLVM.

cargo

1.88.0

A build system and dependency manager for Rust.

rustfmt

1.88.0

A tool for automatic formatting of Rust code.

1.2. Rust Toolset compatibility

Rust Toolset is available for Red Hat Enterprise Linux on AMD and Intel 64-bit (x86_64), 64-bit ARM (aarch64), IBM Power Systems, Little Endian (ppc64le), and 64-bit IBM Z (s390x) architectures.

1.3. Installing Rust Toolset

Install Rust Toolset, including all development and debugging tools and dependent packages, by enabling the rust-toolset module on RHEL 8 or installing the rust-toolset package on RHEL 9 and 10. Rust Toolset depends on LLVM Toolset.

Prerequisites

  • All available Red Hat Enterprise Linux updates are installed.

Procedure

  • Install Rust Toolset:

    • On RHEL 8, enter: 

      # yum module install rust-toolset

    • On RHEL 9 and 10, enter: 

      # dnf install rust-toolset

1.4. Installing Rust documentation

Install the rust-doc package to have The Rust Programming Language book available locally on your system. The package provides the official Rust language documentation for offline use.

Procedure

  • Install the rust-doc package:

    • On RHEL 8, enter: 

      # yum install rust-doc

    • On RHEL 9 and 10, enter: 

      # dnf install rust-doc

Verification

  • Use a browser that is installed on the same host to display the documentation:

    • The Rust Programming Language book: /usr/share/doc/rust/html/index.html
    • The API documentation for all Rust code packages: /usr/share/doc/rust/html/std/index.html

1.5. Installing Cargo documentation

The Cargo, Rust’s Package Manager book is available as installable documentation for Cargo. Install the cargo-doc package to add this documentation to your system.

Procedure

  • Install the cargo-doc package:

    • On RHEL 8, enter: 

      # yum install cargo-doc

    • On RHEL 9 and 10, enter: 

      # dnf install cargo-doc

Verification

  • Open /usr/share/doc/cargo/html/index.html in a browser that is installed on the same host.

1.6. Additional resources

Chapter 2. The Cargo build tool

Cargo is a build tool and front end for the Rust compiler rustc and a package and dependency manager. It allows Rust projects to declare dependencies with specific version requirements, resolves the full dependency graph, downloads packages, and builds, and tests your entire project.

2.1. The Cargo directory structure and file placements

The Cargo build tool uses set conventions for defining the directory structure and file placement within a Cargo package. Running the cargo new command generates the package directory structure and templates for both a manifest and a project file. By default, it also initializes a new Git repository in the package root directory.

For a binary program, Cargo creates a directory <project_name> containing a text file named Cargo.toml and a subdirectory src containing a text file named main.rs.

Additional resources

2.2. Creating a Rust project

Create a new Rust project that is set up according to the Cargo conventions. The cargo new command generates the package directory structure, a manifest file, and initial source files.

Procedure

  1. Create a Rust project: 

    $ cargo new --bin <project_name>

    Replace <project_name> with your project name.

  2. To edit the project code, edit the main executable file main.rs and add new source files to the src subdirectory.

Additional resources

2.3. Creating a Rust library project

Create a Rust library project by using the Cargo build tool with the cargo new --lib command. The result is a package layout suitable for a library rather than a binary.

Procedure

  1. Create a Rust library project: 

    $ cargo new --lib <project_name>

    Replace <project_name> with the name of your Rust project.

  2. To edit the project code, edit the src/lib.rs source file.

Additional resources

2.4. Building a Rust project

Build your Rust project by using the Cargo build tool. Cargo resolves all dependencies of your project, downloads missing dependencies, and compiles it by using the rustc compiler.

By default, projects are built and compiled in debug mode. For information on compiling your project in release mode, see Building a Rust project in release mode.

Prerequisites

Procedure

  1. In the Rust project directory, build the project: 

    $ cargo build

  2. To verify that your Rust program can be built when you do not need to build an executable file, enter: 

    $ cargo check

2.5. Building a Rust project in release mode

Build your Rust project in release mode by using the Cargo build tool. Release mode is optimizing your source code and can therefore increase compilation time while ensuring that the compiled binary will run faster. Use this mode to produce optimized artifacts suitable for release and production.

Cargo resolves all dependencies of your project, downloads missing dependencies, and compiles it by using the rustc compiler.

For information on compiling your project in debug mode, see Building a Rust project.

Prerequisites

Procedure

  1. In the Rust project directory, build the project in release mode: 

    $ cargo build --release

  2. To verify that your Rust program can be built when you do not need to build an executable file, enter: 

    $ cargo check

2.6. Running a Rust program

Run your Rust project by using the Cargo build tool. Cargo first rebuilds your project and then runs the resulting executable file. If used during development, the cargo run command correctly resolves the output path independently of the build mode.

Prerequisites

Procedure

  • To run a Rust program managed as a project by Cargo, enter in the project directory: 

    $ cargo run

    If your program has not been built yet, Cargo builds your program before running it.

2.7. Testing a Rust project

Test your Rust program by using the Cargo build tool. Cargo first rebuilds your project and then runs the tests found in the project. Test functions must be free, monomorphic, and take no arguments. The function return type must be either () or Result<(), E> where E: Error.

By default, Rust projects are tested in debug mode. For information on testing your project in release mode, see Testing a Rust project in release mode.

Prerequisites

Procedure

  1. Add the #[test] attribute in front of your function.

  2. Enter in the project directory: 

    $ cargo test

Additional resources

2.8. Testing a Rust project in release mode

Test your Rust program in release mode by using the Cargo build tool. Release mode is optimizing your source code and can therefore increase compilation time while ensuring that the compiled binary will run faster. Use this mode to produce optimized artifacts suitable for release and production.

Cargo first rebuilds your project and then runs the tests found in the project. Test functions must be free, monomorphic, and take no arguments. The function return type must be either () or Result<(), E> where E: Error.

For information on testing your project in debug mode, see Testing a Rust project.

Prerequisites

Procedure

  1. Add the #[test] attribute in front of your function.

  2. Enter in the project directory: 

    $ cargo test --release

Additional resources

2.9. Configuring Rust project dependencies

Configure the dependencies of your Rust project by using the Cargo build tool. To specify dependencies for a project managed by Cargo, edit the file Cargo.toml in the project directory and rebuild your project. Cargo downloads the Rust code packages and their dependencies, stores them locally, builds all of the project source code including the dependency code packages, and runs the resulting executable.

Prerequisites

Procedure

  1. In your project directory, edit the Cargo.toml file, and list each dependency in the following format in the [dependencies] section: 

    <crate_name> = <version>

    Rust code packages are called crates.

  2. Rebuild your project: 

    $ cargo build

  3. Run your project: 

    $ cargo run

Additional resources

2.10. Building documentation for a Rust project

Use the Cargo tool to generate documentation from comments in your source code that are marked for extraction. Note that documentation comments are extracted only for public functions, variables, and members.

Prerequisites

Procedure

  1. In your code, use three slashes /// at the beginning of a line to mark the line for extracting the comment for documentation.

  2. Build the documentation: 

    $ cargo doc --no-deps

    The command stores the generated documentation in the .target/doc/ directory.

Additional resources

2.11. Compiling code into a WebAssembly binary with Rust

Install the WebAssembly standard library to compile Rust code into WebAssembly binaries. You can then build and run Rust projects that target the WebAssembly platform.

Prerequisites

Procedure

  1. Install the WebAssembly standard library:

    • On RHEL 8, enter: 

      # yum install rust-std-static-wasm32-unknown-unknown

    • On RHEL 9 and 10, enter: 

      # dnf install rust-std-static-wasm32-unknown-unknown

  2. Use WebAssembly with Cargo: 

    $ cargo <command> --target wasm32-unknown-unknown

    Replace <command> with the Cargo command you want to run.

Additional resources

2.12. Vendoring Rust project dependencies

Create a local copy of the dependencies of your Rust project for offline redistribution by using the Cargo build tool (vendoring). The vendored dependencies, including Rust code packages for building your project on a Windows operating system, are located in the vendor directory and can be used by Cargo without any connection to the internet.

Prerequisites

Procedure

  • To vendor your Rust project with dependencies by using Cargo, enter in the project directory: 

    $ cargo vendor

2.13. Additional resources

Chapter 3. The rustfmt formatting tool

With the rustfmt formatting tool, you can automatically format the source code of your Rust programs. You can use rustfmt either as a standalone tool or with Cargo.

For further details, see the rustfmt help pages displayed by the rustfmt --help command.

3.1. Installing rustfmt

Install the rustfmt formatting tool by installing the rustfmt package. On RHEL 8 enable the rust-toolset module; on RHEL 9 and 10 install the rust-toolset package.

Prerequisites

Procedure

  • Install the rustfmt package:

    • On RHEL 8, enter: 

      # yum install rustfmt

    • On RHEL 9 and 10, enter: 

      # dnf install rustfmt

3.2. Using rustfmt as a standalone tool

Use rustfmt as a standalone tool to format a Rust source file and all its dependencies. As an alternative, use rustfmt with the Cargo build tool. For more information, see Using rustfmt with the Cargo build tool.

Prerequisites

Procedure

  • Format the Rust source code: 

    $ rustfmt <source-file>

    Replace <source_file> with the name of your source file. Alternatively, you can replace <source_file> with standard input. The rustfmt utility then provides its output in standard output.

    Important

    By default, rustfmt modifies the affected files without displaying details or creating backups. To display details and create backups, run rustfmt with the --write-mode option.

3.3. Using rustfmt with the Cargo build tool

Use the rustfmt tool with Cargo to format a Rust source file and all its dependencies. As an alternative, use rustfmt as a standalone tool. For more information, see Using rustfmt as a standalone tool.

Prerequisites

Procedure

  1. Optional: To change the rustfmt formatting options, create rustfmt.toml configuration file in the project directory and add your configurations to the file.

  2. Format the Rust source code: 

    $ cargo fmt

Chapter 4. Container images with Rust Toolset

You can build your own Rust Toolset containers from Red Hat Universal Base Images. Use these images as a base and add Rust Toolset packages to create custom development or build environments.

4.1. Creating a custom UBI-based container with Rust Toolset

Rust Toolset packages are part of the Red Hat Universal Base Images (UBIs) repositories. To keep the container size small, install only individual packages instead of the entire Rust Toolset.

Prerequisites

Procedure

  • To create a container image containing Rust Toolset, add the following to your container file:

    • For an image based on RHEL 8, enter: 

      FROM registry.access.redhat.com/ubi8/ubi:latest

RUN yum module install -y rust-toolset

    • For an image based on RHEL 9, enter: 

      FROM registry.access.redhat.com/ubi9/ubi:latest

RUN yum install -y rust-toolset

    • For an image based on RHEL 10, enter: 

      FROM registry.access.redhat.com/ubi10/ubi:latest

RUN yum install -y rust-toolset

4.2. Additional resources

Chapter 5. Changes in Rust 1.88.0 Toolset

RHEL provides Rust Toolset in version 1.88.0. Notable enhancements since the previously available version 1.84.1 are the Rust 2024 Edition, async closures, let chains, naked functions, high-performance computing improvements, trait upcasting, and standard library improvements.

  • Rust 2024 Edition: The Rust 2024 Edition is now stable. It introduces changes such as refined capture rules for impl Trait, and safer extern blocks which now require the unsafe keyword.
  • Async Closures: The async closures are now stable.
  • Let Chains: This feature allows using && to chain multiple let statements within if and while conditions, enabling more concise complex conditional checks. This feature is available only in the Rust 2024 Edition.
  • Naked Functions: Developers can now define "naked functions" using the #[unsafe(naked)] attribute. These functions do not have a compiler-generated prologue or epilogue, providing full control over the assembly code.
  • High-performance computing: When you enable target features, you can call multiple std::arch intrinsics directly in safe Rust, which gives you direct access to specific CPU features.
  • Trait Upcasting: It is now possible to upcast trait objects to their supertraits, improving flexibility when working with trait objects.

  • Standard Library Improvements:

    • Anonymous Pipes: Access to anonymous pipes is now available in the standard library.

    • Mutable Multiple Element Indexing: `HashMap`s and slices now support safely retrieving mutable references to multiple elements simultaneously.

      Compatibility notes
  • The #[bench] attribute has been fully de-stabilized and its usage will result in a hard error.
  • The wasm_c_abi future compatibility warning is now a hard error.
  • The missing_abi lint is now warn-by-default, and explicitly specify the ABI in extern blocks.

Rust Toolset is a rolling Application Stream, and Red Hat only supports the latest version. For more information, see the Red Hat Enterprise Linux Application Streams Life Cycle document.

Legal Notice

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.