Using Rust 1.79.0 Toolset

Red Hat Developer Tools 1

Installing and using Rust 1.79.0 Toolset

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.

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

Rust Toolset provides the Rust programming language compiler rustc, the cargo build tool and dependency manager, the cargo-vendor plugin, and required libraries. The components and their versions are listed below.

Name	Version	Description
`rust`	1.79.0	The Rust compiler front-end for LLVM.
`cargo`	1.79.0	A build system and dependency manager for Rust.
`rustfmt`	1.79.0	A tool for automatic formatting of Rust code.

1.2. Rust Toolset compatibility

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

AMD and Intel 64-bit
64-bit ARM
IBM Power Systems, Little Endian
64-bit IBM Z

1.3. Installing Rust Toolset

To install Rust Toolset including all development and debugging tools as well as dependent packages, complete the steps below. Note that Rust Toolset has a dependency on LLVM Toolset.

Prerequisites

All available Red Hat Enterprise Linux updates are installed.

Procedure

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.4. Installing Rust documentation

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

Prerequisites

Rust Toolset is installed.
For more information, see Installing Rust Toolset.

Procedure

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

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.5. Installing Cargo documentation

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

Note

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

Prerequisites

Rust Toolset is installed.
For more information, see Installing Rust Toolset.

Procedure

To install the cargo-doc package, run:
- 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.6. Additional resources

For more information on the Rust programming language, see the Content from doc.rust-lang.org is not included.official Rust documentation.

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

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

For more information on the Cargo directory structure, see Content from doc.rust-lang.org is not included.The Cargo Book — Package Layout.
For in-depth information about Rust code organization, see Content from doc.rust-lang.org is not included.The Rust Programming Language — Managing Growing Projects with Packages, Crates, and Modules.

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

For information on configuring your project and adding dependencies, see Configuring Rust project dependencies.

2.3. Creating a Rust library project

To create a Rust library project using the Cargo build tool, complete the steps below.

Procedure

To create a Rust library project, run:
- 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.

Additional resources

Content from doc.rust-lang.org is not included.Managing Growing Projects with Packages, Crates, and Modules

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

An existing Rust project.
For information on how to create a Rust project, see Creating a Rust project.

Procedure

To build a Rust project managed by Cargo, run in the project directory:
- 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

An existing Rust project.
For information on how to create a Rust project, see Creating a Rust project.

Procedure

To build the project in release mode, run:
- 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

A built Rust project.
For information on how to build a Rust project, see Building a Rust project.

Procedure

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

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

A built Rust project.
For information on how to build a Rust project, see Building a Rust project.

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 8:
```
$ cargo test
```
- On Red Hat Enterprise Linux 9:
```
$ cargo test
```

Additional resources

For more information on performing tests in your Rust project, see Content from doc.rust-lang.org is not included.The Rust Reference — Testing attributes.

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

A built Rust project.
For information on how to build a Rust project, see Building a Rust project.

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 8:
```
$ cargo test --release
```
- On Red Hat Enterprise Linux 9:
```
$ cargo test --release
```

Additional resources

For more information on performing tests in your Rust project, see Content from doc.rust-lang.org is not included.The Rust Reference — Testing attributes.

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

A built Rust project.
For information on how to build a Rust project, see Building a Rust project.

Procedure

In your project directory, open the file Cargo.toml.
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.
Edit your dependencies.
Rebuild your project by running:
- On Red Hat Enterprise Linux 8:
```
$ cargo build
```
- On Red Hat Enterprise Linux 9:
```
$ cargo build
```
Run your project by using the following command:
- On Red Hat Enterprise Linux 8:
```
$ cargo run
```
- On Red Hat Enterprise Linux 9:
```
$ cargo run
```

Additional resources

For more information on configuring Rust dependencies, see Content from doc.crates.io is not included.The Cargo Book — Specifying Dependencies.

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

A built Rust project.
For information on how to build a Rust project, see Building a Rust project.
Configured dependencies.
For more information on configuring dependencies, see Configuring Rust project dependencies.

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

For more information on building documentation using Cargo, see Content from doc.rust-lang.org is not included.The Rust Programming Language — Making Useful Documentation Comments.

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

To compile code into a WebAssembly binary with Rust on Red Hat Enterprise Linux 8 and Red Hat Enterprise Linux 9, complete the steps below.

Prerequisites

Rust Toolset is installed.
For more information, see Installing Rust Toolset.

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

For more information on WebAssembly, see the official Content from rustwasm.github.io is not included.Rust and WebAssembly documentation or the Content from rustwasm.github.io is not included.Rust and WebAssembly book.

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

A built Rust project.
For information on how to build a Rust project, see Building a Rust project.
Configured dependencies.
For more information on configuring dependencies, see Configuring Rust project dependencies.

Procedure

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

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 Content from doc.crates.io is not included.Official Cargo Guide.
To display the manual page included in Rust Toolset, run:
- 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

To install the rustfmt formatting tool for Rust on Red Hat Enterprise Linux 8 and Red Hat Enterprise Linux 9, complete the steps below.

Prerequisites

Rust Toolset is installed. For more information, see Installing Rust Toolset.

Procedure

To install rustfmt, run:

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

An existing Rust project.
For information on how to create a Rust project, see Creating a Rust project.

Procedure

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

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

An existing Rust project.
For information on how to create a Rust project, see Creating a Rust project.

Procedure

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

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 8:
```
$ rustfmt --help
```
- On Red Hat Enterprise Linux 9:
```
$ rustfmt --help
```
To configure the rustfmt tool, create the rustfmt.toml configuration file in the project directory and add your configurations to the file. You can find the configuration options in the Configurations.md file.
- 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 Content from docs.docker.com is not included.Dockerfile reference page.

Procedure

Visit the This content is not included.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

For more information on Red Hat UBI images, see Working with Container Images.
For more information on Red Hat UBI repositories, see Universal Base Images (UBI): Images, repositories, packages, and source code.

Chapter 5. Changes in Rust 1.79.0 Toolset

5.1. Changes in Rust 1.79.0 Toolset

Rust Toolset has been updated from version 1.75.0 to 1.79.0 on Red Hat Enterprise Linux 8 and Red Hat Enterprise Linux 9.

Rust Toolset has been updated from version 1.75.0 to 1.79.0 on RHEL 8 and RHEL 9.

Notable changes are listed below.

A new offset_of! macro
Support for C-string literals
Support for inline const expressions
Support for bounds in associated type position
Improved automatic temporary lifetime extension
Debug assertions for unsafe preconditions

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

Legal Notice

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.