Using Rust 1.66.1 Toolset

Red Hat Developer Tools 1

Installing and using Rust 1.66.1 Toolset

Jacob Valdez

Red Hat Developer Group Documentation Team

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.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

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 distributed as a part of Red Hat Developer Tools for Red Hat Enterprise Linux 7. For Red Hat Enterprise Linux 8, Rust Toolset is available as a module. Rust Toolset is available as packages for Red Hat Enterprise Linux 9.

1.1. Rust Toolset components

The following components are available as part of Rust Toolset:

NameVersionDescription

rust

1.66.1

The Rust compiler front-end for LLVM.

cargo

1.66.1

A build system and dependency manager for Rust.

rustfmt

1.66.1

A tool for automatic formatting of Rust code.

1.2. Rust Toolset compatibility

Rust Toolset is available for Red Hat Enterprise Linux 7 and Red Hat Enterprise Linux 8 and Red Hat Enterprise Linux 9 on the following architectures:

  • AMD and Intel 64-bit
  • 64-bit ARM (RHEL 8 and RHEL 9)
  • IBM Power Systems, Little Endian
  • IBM Power Systems, Big Endian (Only RHEL 7)
  • 64-bit IBM Z

1.3. Getting access to Rust Toolset on Red Hat Enterprise Linux 7

To be able to install Rust Toolset on Red Hat Enterprise Linux 7, you must access and enable Red Hat Developer Tools and Red Hat Software Collections repositories.
If these repositories are already attached to your system, see Installing Rust Toolset.

Procedure

  1. Install Wget by running:

    # yum install wget
  2. Download the latest subscription data by running:

    # subscription-manager refresh
  3. Register your system by running:

    # subscription-manager register

    To register your system using a graphical user interface (GUI), follow the Registering and Unregistering a System guide.

  4. Display a list of all available subscriptions and identify the pool ID by running:

    # subscription-manager list --available
  5. Find the pool ID on the line beginning with Pool ID.
  6. Attach the subscription that provides access to the Red Hat Developer Tools repository to your system by running:

    # subscription-manager attach --pool=<pool ID from the subscription>
    • Replace <pool ID from the subscription> with the pool ID you identified in the previous step.
  7. Verify which subscriptions are attached to your system by running:

    # sudo subscription-manager list --consumed
  8. Enable the rhel-7-variant-devtools-rpms repository by running:

    # subscription-manager repos --enable rhel-7-<variant>-devtools-rpms
    • Replace <variant> with your Red Hat Enterprise Linux system variant: server or workstation.

      Use server to access the widest range of development tools.

  9. Enable the rhel-variant-rhscl-7-rpms repository by running:

    # subscription-manager repos --enable rhel-<variant>-rhscl-7-rpms
    • Replace <variant> with your Red Hat Enterprise Linux system variant: server or workstation.
  10. Add the Red Hat Developer Tools GPG key to your system by running:

    # cd /etc/pki/rpm-gpg
    # wget -O RPM-GPG-KEY-redhat-devel https://www.redhat.com/security/data/a5787476.txt
    # rpm --import RPM-GPG-KEY-redhat-devel

Additional resources

1.4. Installing Rust Toolset

Complete the following steps to install Rust Toolset including all development and debugging tools as well as dependent packages. Note that Rust Toolset has a dependency on LLVM Toolset.

Prerequisites

Procedure

On Red Hat Enterprise Linux 7, install the rust-toolset-1.66 collection by running:

# yum install rust-toolset-1.66

On Red Hat Enterprise Linux 8, install the rust-toolset module by running:

# yum module install rust-toolset

On Red Hat Enterprise Linux 9, install the rust-toolset package by running:

# dnf install rust-toolset

1.5. Installing Rust documentation

The The Rust Programming Language book is available as installable documentation.

Prerequisites

Procedure

To install the rust-doc package, run the following command:

  • On Red Hat Enterprise Linux 7:

    # yum install rust-toolset-1.66-rust-doc

    You can find the The Rust Programming Language book under the following path: /opt/rh/rust-toolset-1.66/root/usr/share/doc/rust/html/index.html.
    You can find the API documentation for all Rust code packages under the following path: /opt/rh/rust-toolset-1.66/root/usr/share/doc/rust/html/std/index.html.

  • On Red Hat Enterprise Linux 8:

    # yum install rust-doc

    You can find the The Rust Programming Language book under the following path: /usr/share/doc/rust/html/index.html.
    You can find the API documentation for all Rust code packages under the following path: /usr/share/doc/rust/html/std/index.html.

  • On Red Hat Enterprise Linux 9:

    # dnf install rust-doc

    You can find the The Rust Programming Language book under the following path: /usr/share/doc/rust/html/index.html.
    You can find the API documentation for all Rust code packages under the following path: /usr/share/doc/rust/html/std/index.html.

1.6. Installing Cargo documentation

The Cargo, Rust’s Package Manager book is available as installable documentation for Cargo.

Note

From Rust Toolset 1.66, the cargo-doc package is included in the rust-doc package.

Prerequisites

Procedure

  • To install the cargo-doc package, run:

    • On Red Hat Enterprise Linux 7:

      # yum install rust-toolset-1.66-cargo-doc

      You can find the Cargo book under the following path: /opt/rh/rust-toolset-1.66/root/usr/share/doc/cargo/html/index.html.

    • On Red Hat Enterprise Linux 8:

      # yum install cargo-doc

      You can find the Cargo, Rust’s Package Manager book under the following path: /usr/share/doc/cargo/html/index.html.

    • On Red Hat Enterprise Linux 9:

      # dnf install cargo-doc

      You can find the Cargo, Rust’s Package Manager book under the following path: /usr/share/doc/cargo/html/index.html.

1.7. Additional resources

Chapter 2. The Cargo build tool

Cargo is a build tool and front end for the Rust compiler rustc as well as 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 as well as tests your entire project.

Rust Toolset is distributed with Cargo 1.66.1.

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 Cargo directory structure and file placements.

Procedure

Create a Rust project by running the following command:

  • On Red Hat Enterprise Linux 7:

    $ scl enable rust-toolset-1.66 'cargo new --bin <project_name>'
    • Replace <project_name> with your project name.
  • On Red Hat Enterprise Linux 8:

    $ cargo new --bin <project_name>
    • Replace <project_name> with your project name.
  • On Red Hat Enterprise Linux 9:

    $ cargo new --bin <project_name>
    • Replace <project_name> with your project name.
Note

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

Complete the following steps to create a Rust library project using the Cargo build tool.

Procedure

To create a Rust library project, run the following command:

  • On Red Hat Enterprise Linux 7:

    $ scl enable rust-toolset-1.66 'cargo new --lib <project_name>'
    • Replace <project_name> with the name of your Rust project.
  • On Red Hat Enterprise Linux 8:

    $ cargo new --lib <project_name>
    • Replace <project_name> with the name of your Rust project.
  • On Red Hat Enterprise Linux 9:

    $ cargo new --lib <project_name>
    • Replace <project_name> with the name of your Rust project.
Note

To edit the project code, edit the source file, lib.rs, in the src subdirectory.

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

  • To build a Rust project managed by Cargo, run in the project directory:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'cargo build'
    • On Red Hat Enterprise Linux 8:

      $ cargo build
    • On Red Hat Enterprise Linux 9:

      $ cargo build
  • To verify that your Rust program can be built when you do not need to build an executable file, run:
$ cargo check

2.5. Building a Rust project in release mode

Build your Rust project in release mode 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 using the rustc compiler.

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

Prerequisites

Procedure

  • To build the project in release mode, run:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'cargo build --release'
    • On Red Hat Enterprise Linux 8:

      $ cargo build --release
    • On Red Hat Enterprise Linux 9:

      $ cargo build --release
  • To verify that your Rust program can be build when you do not need to build an executable file, run:
$ cargo check

2.6. Running a Rust program

Run your Rust project 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, run in the project directory:

  • On Red Hat Enterprise Linux 7:

    $ scl enable rust-toolset-1.66 'cargo run'
  • On Red Hat Enterprise Linux 8:

    $ cargo run
  • On Red Hat Enterprise Linux 9:

    $ cargo run
Note

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. Note that you can only test functions that are 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

  • Add the test attribute #[test] in front of your function.
  • To run tests for a Rust project managed by Cargo, run in the project directory:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'cargo test'
    • On Red Hat Enterprise Linux 8:

      $ cargo test
    • On Red Hat Enterprise Linux 9:

      $ cargo test

Additional resources

2.8. Testing a Rust project in release mode

Test your Rust program in release mode 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. Note that you can only test functions that are 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

  • Add the test attribute #[test] in front of your function.
  • To run tests for a Rust project managed by Cargo in release mode, run in the project directory:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'cargo test --release'
    • On Red Hat Enterprise Linux 8:

      $ cargo test --release
    • On Red Hat Enterprise Linux 9:

      $ cargo test --release

Additional resources

2.9. Configuring Rust project dependencies

Configure the dependencies of your Rust project 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, open the file Cargo.toml.
  2. Move to the section labelled [dependencies].
    Each dependency is listed on a new line in the following format:

    crate_name = version

    Rust code packages are called crates.

  3. Edit your dependencies.
  4. Rebuild your project by running:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'cargo build'
    • On Red Hat Enterprise Linux 8:

      $ cargo build
    • On Red Hat Enterprise Linux 9:

      $ cargo build
  5. Run your project by using the following command:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'cargo run'
    • On Red Hat Enterprise Linux 8:

      $ cargo run
    • On Red Hat Enterprise Linux 9:

      $ 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

  • To mark comments for extraction, use three slashes /// and place your comment in the beginning of the line it is documenting.
    Cargo supports the Markdown language for your comments.
  • To build project documentation using Cargo, run in the project directory:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'cargo doc --no-deps'
    • On Red Hat Enterprise Linux 8:

      $ cargo doc --no-deps
    • On Red Hat Enterprise Linux 9:

      $ cargo doc --no-deps

The generated documentation is located in the .target/doc directory.

Additional resources

2.11. Compiling code into a WebAssembly binary with Rust on Red Hat Enterprise Linux 8 and Red Hat Enterprise Linux 9 Beta

Complete the following steps to install the WebAssembly standard library.

Prerequisites

Procedure

  • To install the WebAssembly standard library, run:

    • On Red Hat Enterprise Linux 8:

      # yum install rust-std-static-wasm32-unknown-unknown
    • On Red Hat Enterprise Linux 9:

      # dnf install rust-std-static-wasm32-unknown-unknown
  • To use WebAssembly with Cargo, run:

    • On Red Hat Enterprise Linux 8:

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

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

    • On Red Hat Enterprise Linux 9:

      # 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 and reuse using the Cargo build tool. This procedure is called vendoring project dependencies. The vendored dependencies including Rust code packages for building your project on a Windows operating system are located in the vendor directory. Vendored dependencies can be used by Cargo without any connection to the internet.

Prerequisites

Procedure

To vendor your Rust project with dependencies using Cargo, run in the project directory:

  • On Red Hat Enterprise Linux 7:

    $ scl enable rust-toolset-1.66 'cargo vendor'
  • On Red Hat Enterprise Linux 8:

    $ cargo vendor
  • On Red Hat Enterprise Linux 9:

    $ cargo vendor

2.13. Additional resources

  • For more information on Cargo, see the Official Cargo Guide.
  • To display the manual page included in Rust Toolset, run:

    • For Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'man cargo'
    • For Red Hat Enterprise Linux 8:

      $ man cargo
    • For Red Hat Enterprise Linux 9:

      $ man cargo

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 rusftmt either as a standalone tool or with Cargo.

3.1. Installing rustfmt

Complete the following steps to install the rustfmt formatting tool.

Prerequisites

Procedure

Run the following command to install rustfmt:

  • On Red Hat Enterprise Linux 7:

    # yum install rust-toolset-1.66-rustfmt
  • On Red Hat Enterprise Linux 8:

    # yum install rustfmt
  • On Red Hat Enterprise Linux 9:

    # 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 Cargo.

Prerequisites

Procedure

To format a Rust source file using rustfmt as a standalone tool, run the following command:

  • On Red Hat Enterprise Linux 7:

    $ scl enable rust-toolset-1.66 'rustfmt <source-file>'
    • Replace <source_file> with the name of your source file.
      Alternatively, you can replace <source_file> with standard input. rustfmt then provides its output in standard output.
  • On Red Hat Enterprise Linux 8:

    $ rustfmt <source-file>
    • Replace <source_file> with the name of your source file.
      Alternatively, you can replace <source_file> with standard input. rustfmt then provides its output in standard output.
  • On Red Hat Enterprise Linux 9:

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

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

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

To format all source files in a Cargo code package, run the following command:

  • On Red Hat Enterprise Linux 7:

    $ scl enable rust-toolset-1.66 'cargo fmt'
  • On Red Hat Enterprise Linux 8:

    $ cargo fmt
  • On Red Hat Enterprise Linux 9:

    $ cargo fmt
Note

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

3.4. Additional resources

  • To display the help pages of rustfmt, run:

    • On Red Hat Enterprise Linux 7:

      $ scl enable rust-toolset-1.66 'rustfmt --help'
    • On Red Hat Enterprise Linux 8:

      $ rustfmt --help
    • On Red Hat Enterprise Linux 9:

      $ rustfmt --help
  • To configure the rustfmt tool, edit the file Configurations.md.

    • On Red Hat Enterprise Linux 7, you can find it under the following path:

      /opt/rh/rust-toolset-1.66/root/usr/share/doc/rust-toolset-1.66-rustfmt-1.66.1/Configurations.md

    • On Red Hat Enterprise Linux 8, you can find it under the following path:

      /usr/share/doc/rustfmt/Configurations.md

    • On Red Hat Enterprise Linux 9, you can find it under the following path:

      /usr/share/doc/rustfmt/Configurations.md

Chapter 4. Container images with Rust Toolset on RHEL 8

On RHEL 8, you can build your own Rust Toolset container images on top of Red Hat Universal Base Images (UBI) containers using Containerfiles.

4.1. Creating a container image of Rust Toolset on RHEL 8

On RHEL 8, 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

  • An existing Containerfile.
    For more information on creating Containerfiles, see the Dockerfile reference page.

Procedure

  • Visit the Red Hat Container Catalog.
  • Select a UBI.
  • Click Get this image and follow the instructions.
  • To create a container containing Rust Toolset, add the following lines to your Containerfile:
FROM registry.access.redhat.com/ubi8/ubi:latest

RUN yum install -y rust-toolset
  • To create a container image containing an individual package only, add the following lines to your Containerfile:
RUN yum install <package-name>
  • Replace <package_name> with the name of the package you want to install.

4.2. Additional resources

Chapter 5. Changes in Rust 1.66.1 Toolset

Rust Toolset has been updated from version 1.62.1 to 1.66.1 on RHEL 7, RHEL 8, and RHEL 9.

Notable changes include:

  • The thread::scope API creates a lexical scope in which local variables can be safely borrowed by newly spawned threads, and those threads are all guaranteed to exit before the scope ends.
  • The hint::black_box API adds a barrier to compiler optimization, which is useful for preserving behavior in benchmarks that might otherwise be optimized away.
  • The .await keyword now makes conversions with the IntoFuture trait, similar to the relationship between for and IntoIterator.
  • Generic associated types (GATs) allow traits to include type aliases with generic parameters, enabling new abstractions over both types and lifetimes.
  • A new let-else statement allows binding local variables with conditional pattern matching, executing a divergent else block when the pattern does not match.
  • Labeled blocks allow break statements to jump to the end of the block, optionally including an expression value.
  • rust-analyzer is a new implementation of the Language Server Protocol, enabling Rust support in many editors. This replaces the former rls package, but you might need to adjust your editor configuration to migrate to rust-analyzer .
  • Cargo has a new cargo remove subcommand for removing dependencies from Cargo.toml.

For detailed information regarding the updates, see the series of upstream release announcements:

Legal Notice

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, 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, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.