Using Rust 1.92.0 Toolset

Red Hat Developer Tools 1

Installing and using Rust 1.92.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 are committed to providing high-quality documentation and value your feedback. To help us improve, you can submit suggestions or report errors through the Red Hat Jira tracking system.

Procedure

  1. Log in to the Content from redhat.atlassian.net is not included.Jira website.

    If you do not have an account, select the option to create one.

  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 window.

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

The following table lists the main Rust Toolset packages, their versions, and a short description of each.

Table 1.1. Packages included in Rust Toolset

NameVersionDescription

rust

1.92.0

The Rust compiler front-end for LLVM.

cargo

1.92.0

A build system and dependency manager for Rust.

rustfmt

1.92.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

On Red Hat Enterprise Linux 8, enable the rust-toolset module to install Rust Toolset with its development and debugging tools and dependent packages. On Red Hat Enterprise Linux 9 and 10, install the rust-toolset package instead. Rust Toolset depends on LLVM Toolset. On Red Hat Enterprise Linux 10, Rust 1.92 is built against LLVM 21.

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.

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.

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 Rust’s build tool, package manager, and front end for the rustc compiler. After you declare dependency versions in your manifest, you can use Cargo to fetch crates, build the project, and run tests.

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. For more information on Cargo conventions, see The Cargo directory structure and file placements.

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 (cargo new --lib).

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 using the Cargo build tool. Cargo resolves all dependencies of your project, downloads missing dependencies, and compiles it 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

In a Cargo project directory, run cargo run command to compile when needed and start your binary. The executable you launch matches your active debug or release profile.

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 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 Cargo.toml file in the project directory and rebuild your project. Cargo downloads the Rust code packages and their dependencies and stores them locally. Use cargo build or cargo run commands to compile your code with those packages and produce a runnable 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.

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). Vendored sources live in the vendor directory, including any Windows-target crates you captured. Point Cargo at that tree to build offline without network access.

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 (RHEL 8 module or RHEL 9 and 10 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. If you use standard input instead, formatted output is printed to 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 (UBI).

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.92.0 Toolset

Red Hat Enterprise Linux provides Rust Toolset at version 1.92.0. The previous version was 1.88.0.

  • Language:

    • The never_type_fallback_flowing_into_unsafe and dependency_on_unit_never_type_fallback lints are deny-by-default. They report code that is likely to break when the never type is stabilized. You can allow these lints, but you should fix affected code when they are reported.
    • The unused_must_use lint no longer warns when you ignore Result<(), UninhabitedType> (for example, Result with the never type as the error type) or ControlFlow values whose error variant cannot be constructed.
    • You can use &raw [mut | const] on union fields in safe code.
    • You can combine #[track_caller] and #[no_mangle] when every declaration of the function specifies #[track_caller].

  • Compiler:

    • On Linux, unwind tables are emitted by default even when you build with -C panic=abort, so backtraces work again. Use -C force-unwind-tables=no if you must omit unwind tables.
    • On Red Hat Enterprise Linux 10, Rust 1.92 is built against LLVM 21 through LLVM Toolset. When you install Rust Toolset, ensure that LLVM Toolset provides LLVM 21.

  • Standard library:

    • iter::Repeat::last and iter::Repeat::count now panic instead of looping indefinitely.
    • Stabilized APIs include NonZero::div_ceil, Location::file_as_c_str, RwLockWriteGuard::downgrade, Box::new_zeroed, Box::new_zeroed_slice, and corresponding Rc and Arc methods, and btree_map::Entry::insert_entry.

  • Cargo and Rustdoc:

  • Compatibility notes:

    • The invalid_macro_export_arguments lint is deny-by-default and is reported in dependencies. Invalid arguments to #[macro_export] now fail to compile.
    • Downstream impl DerefMut for Pin is no longer permitted.
    • Temporary lifetime extension no longer applies to arguments of non-extended pin! and formatting macros in some cases.

For more information, see the Content from blog.rust-lang.org is not included.Rust 1.92.0 release announcement and the Content from doc.rust-lang.org is not included.upstream Rust 1.92.0 release notes.

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.