Red Hat Developer Tools 1

Using Rust 1.39 Toolset

Installing and using the Rust 1.39 toolset

Last Updated: 2020-03-25

Red Hat Developer Tools 1 Using Rust 1.39 Toolset
Installing and using the Rust 1.39 toolset

Olga Tikhomirova
[email protected]

Supriya Takkhi

Peter Macko

Kevin Owen

Vladimir Slavik
Legal Notice
Copyright © 2020 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.

Abstract
Rust is a Red Hat offering for developers on the Red Hat Enterprise Linux platform. The Rust User
Guide provides an overview of this product, explains how to invoke and use the Rust versions of the
tools, and links to resources with more in-depth information.
 Table of Contents

Table of Contents
.CHAPTER
. . . . . . . . . . 1.. .RUST
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3. . . . . . . . . . . . .
1.1. ABOUT THE RUST TOOLSET 3
1.2. COMPATIBILITY 3
1.3. GETTING ACCESS TO THE RUST TOOLSET ON RED HAT ENTERPRISE LINUX 7 3
Additional Resources 4
1.4. INSTALLING THE RUST TOOLSET 4
Installable documentation 5
Online Documentation 5

.CHAPTER
. . . . . . . . . . 2.
. . CARGO
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6. . . . . . . . . . . . .
2.1. INSTALLING CARGO 6
2.2. CREATING A NEW PROJECT 6
2.3. BUILDING A PROJECT 8
2.4. CHECKING A PROGRAM 9
2.5. RUNNING A PROGRAM 10
2.6. RUNNING PROJECT TESTS 11
2.7. CONFIGURING PROJECT DEPENDENCIES 13
Additional Resources 14
2.8. BUILDING PROJECT DOCUMENTATION 14
Additional Resources 17
2.9. VENDORING PROJECT DEPENDENCIES 17
2.10. ADDITIONAL RESOURCES 18
Cargo documentation 18
Online Cargo Documentation 19
See also 19

. . . . . . . . . . . 3.
CHAPTER . . RUSTFMT
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
..............
3.1. INSTALLING RUSTFMT 20
3.2. USING RUSTFMT AS A STANDALONE TOOL 20
3.3. USING RUSTFMT WITH CARGO 20
3.4. ADDITIONAL RESOURCES 21

. . . . . . . . . . . 4.
CHAPTER . . .CONTAINER
. . . . . . . . . . . . .IMAGES
. . . . . . . . .WITH
. . . . . .RUST
. . . . . .TOOLSET
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
..............
4.1. IMAGE CONTENTS 22
4.2. ACCESSING THE IMAGES 22
4.3. ADDITIONAL RESOURCES 22

. . . . . . . . . . . 5.
CHAPTER . . CHANGES
. . . . . . . . . . . .IN
. . RUST
. . . . . . 1.39
. . . . .TOOLSET
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
..............

1
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

2
 CHAPTER 1. RUST

CHAPTER 1. RUST

1.1. ABOUT THE RUST TOOLSET

The Rust toolset is a Red Hat offering for developers on the Red Hat Enterprise Linux platform. It
provides the Rust programming language compiler rustc, the cargo build tool and dependency
manager, the rustfmt tool, and required libraries. The cargo-vendor package is now built into the cargo
command, but its usage remains the same.

The Rust toolset is distributed as a part of Red Hat Developer Tools for Red Hat Enterprise Linux 7 and
is available as a module in Red Hat Enterprise Linux 8.

The following components are available as a part of the Rust toolset:

Table 1.1. Rust Components

Name Version Description

rust 1.39 A Rust compiler front-end for

LLVM.

cargo 1.39 A build system and dependency

manager for Rust.

rustfmt 1.39 A tool for automatic formatting of

Rust code.

1.2. COMPATIBILITY
The Rust toolset is available for Red Hat Enterprise Linux 7 and Red Hat Enterprise Linux 8 on the
following architectures:

The 64-bit Intel and AMD architectures

The 64-bit ARM architecture

The IBM Power Systems architecture

The little-endian variant of IBM Power Systems architecture

The IBM Z Systems architecture

1.3. GETTING ACCESS TO THE RUST TOOLSET ON RED HAT

ENTERPRISE LINUX 7
The Rust toolset is an offering that is distributed as a part of the Red Hat Developer Tools content set,
which is available to customers with deployments of Red Hat Enterprise Linux 7. To install the Rust
toolset, enable the Red Hat Developer Tools and Red Hat Software Collections repositories by using
the Red Hat Subscription Management and add the Red Hat Developer Tools GPG key to your system.

1. Enable the rhel-7-variant-devtools-rpms repository:

3
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

# subscription-manager repos --enable rhel-7-variant-devtools-rpms

Replace variant with the Red Hat Enterprise Linux system variant ( server or workstation).

NOTE

Consider using Red Hat Enterprise Linux Server to access the widest range of
the development tools.

2. Enable the rhel-variant-rhscl-7-rpms repository:

# subscription-manager repos --enable rhel-variant-rhscl-7-rpms

Replace variant with the Red Hat Enterprise Linux system variant ( server or workstation).

3. Add the Red Hat Developer Tools key to your system:

# 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

Once the subscription is attached to the system and the repositories are enabled, install the Rust
toolset as described in Section 1.4, “Installing the Rust toolset” .

Additional Resources

For more information on how to register your system using Red Hat Subscription Management
and associate it with subscriptions, see the Red Hat Subscription Management collection of
guides.

For detailed instructions on subscription to Red Hat Software Collections, see the Red Hat
Developer Toolset User Guide, Section 1.4. Getting Access to Red Hat Developer Toolset .

1.4. INSTALLING THE RUST TOOLSET

The Rust toolset is distributed as a collection of RPM packages that can be installed, updated,
uninstalled, and inspected by using the standard package management tools that are included in
Red Hat Enterprise Linux. Note that a valid subscription that provides access to the Red Hat Developer
Tools content set is required to install the Rust toolset on a Red Hat Enterprise Linux 7 system. For
detailed instructions on how to associate your Red Hat Enterprise Linux 7 system with an appropriate
subscription and get access to the Rust toolset, see Section 1.3, “Getting access to the Rust toolset on
Red Hat Enterprise Linux 7”.

IMPORTANT

Before installing the Rust toolset, install all available Red Hat Enterprise Linux updates.

1. Install all of the components included in the Rust toolset for your operating system:

On Red Hat Enterprise Linux 7, install the rust-toolset-1.39 package:

# yum install rust-toolset-1.39

4
 CHAPTER 1. RUST

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

# yum module install rust-toolset

This installs all development and debugging tools, and other dependent packages to the
system. Notably, the Rust toolset has a dependency on Clang and LLVM Toolset.

Installable documentation

Install The Rust Programming Language book and API documentation in HTML format:

On Red Hat Enterprise Linux 7, install the rust-toolset-1.39-rust-doc package:

# yum install rust-toolset-1.39-rust-doc

The book is available in /opt/rh/rust-toolset-1.39/usr/share/doc/rust/html/index.html

The API documentation for all crates is available in HTML format in /opt/rh/rust-toolset-
1.39/usr/share/doc/rust/html/std/index.html.

On Red Hat Enterprise Linux 8, install the rust-doc package:

# yum install rust-doc

The book is available in /usr/share/doc/rust/html/index.html

The API documentation for all crates is available in HTML format in

/usr/share/doc/rust/html/std/index.html.

Online Documentation

Rust documentation — The upstream Rust documentation.

5
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

CHAPTER 2. CARGO
cargo is a tool for development using the Rust programming language. cargo fulfills the following roles:

Build tool and frontend for the Rust compiler rustc.

NOTE

Consider using cargo over rustc.

Package and dependency manager.

cargo allows Rust projects to declare dependencies with specific version requirement. cargo will
resolve the full dependency graph, download packages as needed, and build and test the entire
project.

The Rust toolset is distributed with cargo 1.39.

2.1. INSTALLING CARGO

Install the Rust toolset. For details, see Section 1.4, “Installing the Rust toolset” .

NOTE

cargo is installed as a part of the Rust toolset.

On Red Hat Enterprise Linux 7, cargo is provided by the rust-toolset-1.39-

cargo package.

On Red Hat Enterprise Linux 8, cargo is provided by the rust-toolset module.

2.2. CREATING A NEW PROJECT

To create a Rust program on the command line, run the cargo tool as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo new --bin project_name'

For Red Hat Enterprise Linux 8:

$ cargo new --bin project_name

This creates a directory project_name containing a text file named Cargo.toml and a subdirectory src
containing a text file named main.rs.

To configure the project and add dependencies, edit the file Cargo.toml. See Section 2.7, “Configuring
project dependencies”.

To edit the project code, edit the file main.rs and add new source files in the src subdirectory as
needed.

To create a project for a cargo package instead of a program, run the cargo tool on the command line
as follows:

6
 CHAPTER 2. CARGO

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo new --lib project_name'

For Red Hat Enterprise Linux 8:

$ cargo new --lib project_name

Note that you can execute any command using the scl utility on Red Hat Enterprise Linux 7, causing it
to be run with the Rust binaries available. This allows you to run a shell session with the Rust cargo
command directly available:

$ scl enable rust-toolset-1.39 'bash'

Example 2.1. Creating a project using cargo

Create a new Rust project called helloworld:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo new --bin helloworld'

Created binary (application) helloworld project

For Red Hat Enterprise Linux 8:

$ cargo new --bin helloworld

Created binary (application) helloworld project

Examine the result:

$ cd helloworld
$ tree
.
├── Cargo.toml
└── src
└── main.rs

1 directory, 2 files
$ cat src/main.rs
fn main() {
println!("Hello, world!");
}

A directory helloworld is created for the project, with a file Cargo.toml for tracking project
metadata, and a subdirectory src containing the main source code file main.rs.

The source code file main.rs has been initialized by cargo to a sample hello world program.

NOTE
7
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

NOTE

The tree tool is available from the default Red Hat Enterprise Linux repositories. To
install it:

# yum install tree

2.3. BUILDING A PROJECT

To build a Rust project on the command line, change to the project directory and run the cargo tool as
follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo build'

For Red Hat Enterprise Linux 8:

$ cargo build

This resolves all dependencies of the project, downloads the missing dependencies, and compiles the
project using the rustc compiler.

By default, the project is built and compiled in debug mode. To build the project in release mode, run
the cargo tool with the --release option as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo build --release'

For Red Hat Enterprise Linux 8:

$ cargo build --release

Example 2.2. Building a project using cargo

This example assumes that you have successfully created the Rust project helloworld according to
Example 2.1, “Creating a project using cargo” .

Change to the directory helloworld and build the project:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo build'

Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.51 secs

For Red Hat Enterprise Linux 8:

$ cargo build
Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.51 secs

8
 CHAPTER 2. CARGO

Examine the result:

$ tree
.
├── Cargo.lock
├── Cargo.toml
├── src
│ └── main.rs
└── target
└── debug
├── build
├── deps
│ └── helloworld-b7c6fab39c2d17a7
├── examples
├── helloworld
├── helloworld.d
├── incremental
└── native

8 directories, 6 files

A subdirectory structure has been created, starting with the directory target. Since the project was
built in debug mode, the actual build output is contained in a further subdirectory debug. The actual
resulting executable file is target/debug/helloworld.

NOTE

The tree tool is available from the default Red Hat Enterprise Linux repositories. To
install it:

# yum install tree

2.4. CHECKING A PROGRAM

To verify that a Rust program managed by cargo can be built, on the command line change to the
project directory and run the cargo tool as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo check'

For Red Hat Enterprise Linux 8:

$ cargo check

NOTE

Consider using the cargo check command over the cargo build command for
verification of a Rust program validity when you do not need the executable code. The
cargo check command is faster than a full project build using the cargo build command,
because it does not generate the executable code.

9
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

By default, the project is checked in debug mode. To check the project in release mode, run the cargo
tool with the --release option as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo check --release'

For Red Hat Enterprise Linux 8:

$ cargo check --release

Example 2.3. Checking a program with cargo

This example assumes that you have successfully built the Rust project helloworld according to
Example 2.2, “Building a project using cargo” .

Change to the directory helloworld and check the project:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo check'

Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.5 secs

For Red Hat Enterprise Linux 8:

$ cargo check
Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.5 secs

The project is checked, with output similar to that of the cargo build command. However, the
executable file is not generated. You can verify this by comparing the current time with the time
stamp of the executable file:

$ date
Fri Oct 13 08:53:21 CEST 2017
$ ls -l target/debug/helloworld
-rwxrwxr-x. 2 vslavik vslavik 252624 Oct 13 08:48 target/debug/helloworld

2.5. RUNNING A PROGRAM

To run a Rust program managed as a project by cargo on the command line, change to the project
directory and run the cargo tool as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo run'

For Red Hat Enterprise Linux 8:

$ cargo run

10
 CHAPTER 2. CARGO

If the program has not been built yet, cargo will run a build before running the program.

NOTE

Consider using cargo to run a Rust program during development. It will correctly resolve
the output path independently of the build mode.

By default, the project is built in debug mode. To build the project in release mode before running, run
the cargo tool with the --release option as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo run --release'

For Red Hat Enterprise Linux 8:

$ cargo run --release

Example 2.4. Running a program with cargo

This example assumes that you have successfully built the Rust project helloworld according to
Example 2.2, “Building a project using cargo” .

Change to the directory helloworld and run the project:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo run'

Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
Running target/debug/helloworld
Hello, world!

For Red Hat Enterprise Linux 8:

$ cargo run
Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
Running target/debug/helloworld
Hello, world!

cargo first rebuilds the project, and then runs the resulting executable file.

In this example, there were no changes to the source code since last build. As a result, cargo did not
have to rebuild the executable file, but merely accepted it as current.

2.6. RUNNING PROJECT TESTS

To run tests for a cargo project on the command line, change to the project directory and run the cargo
tool as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo test'

11
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

For Red Hat Enterprise Linux 8:

$ cargo test

By default, the project is tested in debug mode. To test the project in release mode, run the cargo tool
with the --release option as follows:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo test --release'

For Red Hat Enterprise Linux 8:

$ cargo test --release

Example 2.5. Testing a project with cargo

This example assumes that you have successfully built the Rust project helloworld according to
Example 2.2, “Building a project using cargo” .

Change to the directory helloworld, and edit the file src/main.rs so that it contains the following
source code:

fn main() {
println!("Hello, world!");
}

#[test]
fn my_test() {
assert_eq!(21+21, 42);
}

The function my_test marked as a test has been added.

Save the file, and run the test:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo test'

Compiling helloworld v0.1.0 (file:///home/vslavik/Documentation/rusttest/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.26 secs
Running target/debug/deps/helloworld-9dd6b83647b49aec

running 1 test
test my_test ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

For Red Hat Enterprise Linux 8:

$ cargo test
Compiling helloworld v0.1.0 (file:///home/vslavik/Documentation/rusttest/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.26 secs
Running target/debug/deps/helloworld-9dd6b83647b49aec

12
 CHAPTER 2. CARGO

running 1 test
test my_test ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

cargo first rebuilds the project, and then runs the tests found in the project. The test my_test has
been succesfully passed.

2.7. CONFIGURING PROJECT DEPENDENCIES

To specify dependencies for a cargo project, edit the file Cargo.toml in the project directory. The
section [dependencies] contains a list of the project dependencies. Each dependency is listed on a new
line in the following format:

crate_name = version

Rust code packages are called crates.

Example 2.6. Adding Dependency to a Project and Building it with cargo

This example assumes that you have successfully built the Rust project helloworld according to
Example 2.2, “Building a project using cargo” .

Change to the directory helloworld and edit the file src/main.rs so that it contains the following
source code:

extern crate time;

fn main() {
println!("Hello, world!");
println!("Time is: {}", time::now().rfc822());
}

The code now requires an external crate time. Add this dependency to project configuration by
editing the file Cargo.toml so that it contains the following code:

[package]
name = "helloworld"
version = "0.1.0"
authors = ["Your Name <[email protected]>"]

[dependencies]
time = "0.1"

Run the cargo run command to build the project and run the resulting executable file:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo run'

Updating registry `https://github.com/rust-lang/crates.io-index`
Downloading time v0.1.38
Downloading libc v0.2.32

13
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs

Running `target/debug/helloworld`
Hello, world!
Time is: Fri, 13 Oct 2017 11:08:57

For Red Hat Enterprise Linux 8:

$ cargo run
Updating registry `https://github.com/rust-lang/crates.io-index`
Downloading time v0.1.38
Downloading libc v0.2.32
Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
Running `target/debug/helloworld`
Hello, world!
Time is: Fri, 13 Oct 2017 11:08:57

cargo downloads the time crate and its dependencies (crate libc), stores them locally, builds all of
the project source code including the dependency crates, and finally runs the resulting executable.

Additional Resources

Specifying Dependencies — official cargo documentation.

2.8. BUILDING PROJECT DOCUMENTATION

NOTE

Consider using the cargo doc command over rustdoc. The command cargo doc utilizes
the rustdoc utility.

NOTE

cargo doc extracts documentation comments only for public functions, variables, and
members.

Rust code can contain comments marked for extraction into documentation. The comments support the
Markdown language.

To build project documentation using the cargo tool, change to the project directory and run cargo
tool:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo doc --no-deps'

For Red Hat Enterprise Linux 8:

$ cargo doc --no-deps

This extracts documentation stored from the special comments in the source code of your project and
writes the documentation in the HTML format.

14
 CHAPTER 2. CARGO

Omit the --no-deps option to include dependencies in the generated documentation, including
third-party libraries.

Add the --open option to open the generated documentation in your browser.

Example 2.7. Building project documentation

This example assumes that you have successfully built the Rust project helloworld with
dependencies, according to Example 2.6, “Adding Dependency to a Project and Building it with
cargo”.

Change to the directory helloworld and edit the file src/main.rs so that it contains the following
source code:

//! This is a hello-world program.

extern crate time;

/// Prints a greeting to `stdout`.

pub fn print_output() {
println!("Hello, world!");
println!("Time is: {}", time::now().rfc822());
}

/// The program entry point.

fn main() {
print_output();
}

The code now contains a public function print_output(). The whole helloworld program, the
print_output() function, and the main() function have documentation comments.

Run the cargo doc command to build the project documentation:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo doc --no-deps'

Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.31 secs

For Red Hat Enterprise Linux 8:

$ cargo doc --no-deps

Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 0.31 secs

Install the tree tool that is available in the default Red Hat Enterprise Linux repositories, if not
already installed:

# yum install tree

Examine the result:

$ tree
.

15
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

├── Cargo.lock
├── Cargo.toml
├── src
│ └── main.rs
└── target
...
└── doc
...
├── helloworld
│ ├── fn.print_output.html
│ ├── index.html
│ ├── print_output.v.html
│ └── sidebar-items.js
...
└── src
└── helloworld
└── main.rs.html

12 directories, 32 files

cargo builds the project documentation. To view the documentation, open the file
target/doc/helloworld/index.html in your browser. The generated documentation does not contain
any mention of the main() function, because it is not public.

Run the cargo doc command without the --no-deps option to build the project documentation,
including the dependency libraries time and libc:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo doc'

Documenting libc v0.2.32
Documenting time v0.1.38
Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 3.41 secs

For Red Hat Enterprise Linux 8:

$ cargo doc
Documenting libc v0.2.32
Documenting time v0.1.38
Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld)
Finished dev [unoptimized + debuginfo] target(s) in 3.41 secs

Examine the resulting directory structure with tree command:

$ tree
...
92 directories, 11804 files
$ ls -d target/doc/*/
target/doc/helloworld/ target/doc/implementors/ target/doc/libc/ target/doc/src/ target/doc/time/

The resulting documentation now covers the dependency libraries time and libc, with each present
as another subdirectory in the target/doc/ directory.

16
 CHAPTER 2. CARGO

Additional Resources
A detailed description of the cargo doc tool and its features is beyond the scope of this document. For
more information, see the resources listed below.

Making Useful Documentation Comments from the official Rust Programming Language
documentation.

2.9. VENDORING PROJECT DEPENDENCIES

Vendoring project dependencies means creating a local copy of the dependencies for offline
redistribution and reuse. Vendored dependencies can be used by the cargo build tool without any
connection to the internet.

Note that starting with this release the cargo-vendor package is included in cargo, but there has been
no change in the way it works.

Example 2.8. Vendoring project dependencies

This example assumes that you have successfully built the Rust project helloworld with
dependencies, according to Example 2.6, “Adding Dependency to a Project and Building it with
cargo”.

Change to the directory helloworld and run the cargo vendor command to vendor the project with
dependencies:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo vendor'

Downloading kernel32-sys v0.2.2
Downloading redox_syscall v0.1.31
Downloading winapi-build v0.1.1
Downloading winapi v0.2.8
Vendoring kernel32-sys v0.2.2 (/home/vslavik/.cargo/registry/src/github.com-
1ecc6299db9ec823/kernel32-sys-0.2.2) to vendor/kernel32-sys
Vendoring libc v0.2.32 (/home/vslavik/.cargo/registry/src/github.com-
1ecc6299db9ec823/libc-0.2.32) to vendor/libc
Vendoring redox_syscall v0.1.31 (/home/vslavik/.cargo/registry/src/github.com-
1ecc6299db9ec823/redox_syscall-0.1.31) to vendor/redox_syscall
Vendoring time v0.1.38 (/home/vslavik/.cargo/registry/src/github.com-
1ecc6299db9ec823/time-0.1.38) to vendor/time
Vendoring winapi v0.2.8 (/home/vslavik/.cargo/registry/src/github.com-
1ecc6299db9ec823/winapi-0.2.8) to vendor/winapi
Vendoring winapi-build v0.1.1 (/home/vslavik/.cargo/registry/src/github.com-
1ecc6299db9ec823/winapi-build-0.1.1) to vendor/winapi-build
To use vendored sources, add this to your .cargo/config for this project:

[source.crates-io]
replace-with = "vendored-sources"

[source.vendored-sources]
directory = "/home/vslavik/helloworld/vendor"

For Red Hat Enterprise Linux 8:

$ cargo vendor

17
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

Examine the result:

$ ls
Cargo.lock Cargo.toml src target vendor
$ tree vendor
vendor
├── kernel32-sys
│ ├── build.rs
│ ├── Cargo.toml
│ ├── README.md
│ └── src
│ └── lib.rs
├── libc
│ ├── appveyor.yml
│ ├── Cargo.toml
...
75 directories, 319 files

The vendor directory contains copies of all the dependency crates needed to build the helloworld
program. Note that the crates for building the project on the Windows operating system have been
vendored, too, despite running this command on Red Hat Enterprise Linux.

NOTE

The tree tool is available from the default Red Hat Enterprise Linux repositories. To
install it:

# yum install tree

2.10. ADDITIONAL RESOURCES

A detailed description of the cargo tool and its features is beyond the scope of this document. For more
information, see the resources listed below.

Cargo documentation

cargo(1) — The manual page for the cargo tool provides detailed information on its usage. To
display the manual page for the version included in the Rust toolset:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'man cargo'

For Red Hat Enterprise Linux 8:

$ man cargo

Cargo, Rust’s Package Manager HTML book is provided as a package:

On Red Hat Enterprise Linux 7:

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

18
 CHAPTER 2. CARGO

The HTML is available at /opt/rh/rust-toolset-1.39/usr/share/doc/cargo/html/index.html

On Red Hat Enterprise Linux 8:

# yum install cargo-doc

The HTML is available at /usr/share/doc/cargo/html/index.html

Online Cargo Documentation

Official Cargo Guide

See also

Chapter 1, Rust — An overview of the Rust toolset and more information on how to install it on
your system.

19
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

CHAPTER 3. RUSTFMT
The rustfmt tool provides automatic formatting of Rust source code.

Rust is distributed with rustfmt 1.39.

3.1. INSTALLING RUSTFMT

For Red Hat Enterprise Linux 7:

# yum install rust-toolset-1.39-rustfmt

For Red Hat Enterprise Linux 8:

# dnf install rustfmt

3.2. USING RUSTFMT AS A STANDALONE TOOL

To format a rust source file and all its dependencies with the rustfmt tool:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'rustfmt source-file'

For Red Hat Enterprise Linux 8:

$ rustfmt source-file

Replace source-file with path to the source file.

By default, rustfmt modifies the affected files in place without displaying details or creating backups.
To change the behavior, use the --write-mode value option. For further details see the help mesage of
rustfmt:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'rustfmt --help'

For Red Hat Enterprise Linux 8:

$ rustfmt --help

Additionally, rustfmt accepts standard input instead of a file and provides its output in standard output.

3.3. USING RUSTFMT WITH CARGO

To format all source files in a cargo crate:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'cargo fmt'

20
 CHAPTER 3. RUSTFMT

For Red Hat Enterprise Linux 8:

$ cargo fmt

To change the rustfmt formatting options, create the configuration file rustfmt.toml in the project
directory and supply the configuration there. For further details see the help message of rustfmt:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'rustfmt --config-help'

For Red Hat Enterprise Linux 8:

$ rustfmt --config-help

3.4. ADDITIONAL RESOURCES

Help messages of rustfmt:

For Red Hat Enterprise Linux 7:

$ scl enable rust-toolset-1.39 'rustfmt --help'

$ scl enable rust-toolset-1.39 'rustfmt --config-help'

For Red Hat Enterprise Linux 8:

$ rustfmt --help
$ rustfmt --config-help

Configuring Rustfmt in Configurations.md:

Location in Red Hat Enterprise Linux 7:

/opt/rh/rust-toolset-1.37/usr/share/doc/rust-toolset-1.37-rustfmt-
1.37.0/Configurations.md

Location in Red Hat Enterprise Linux 8:

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

21
Red Hat Developer Tools 1 Using Rust 1.39 Toolset

CHAPTER 4. CONTAINER IMAGES WITH RUST TOOLSET

Rust Toolset is available as container images for RHEL 7 and RHEL 8. It can be downloaded from the
Red Hat Container Registry.

4.1. IMAGE CONTENTS

The RHEL 7 and RHEL 8 container images provide content corresponding to the following package:

Component Version Package

Rust 1.39 rust-toolset-1.39-rust

4.2. ACCESSING THE IMAGES

To pull the image, run the following command as root:

# podman pull registry.redhat.io/devtools/rust-toolset-rhel7

# podman pull registry.redhat.io/rhel8/rust-toolset

4.3. ADDITIONAL RESOURCES

Rust 1.39 container images — entries in the Red Hat Container Catalog

Using Red Hat Software Collections Container Images

22
 CHAPTER 5. CHANGES IN RUST 1.39 TOOLSET

CHAPTER 5. CHANGES IN RUST 1.39 TOOLSET

Rust Toolset has been updated from version 1.37 to 1.39. Notable changes include:

The async - .await syntax has been added to stable Rust. You can now define async functions
and blocks and .await them.

Enhanced pipelined compilation improves build time for optimized, clean builds of some crate
graphs by 10-20%.

When the by-move bindings are in the main pattern of a match expression, if guards can now
reference those bindings.

Rust is supposed to detect memory-safety bugs at compile time, but the previous borrow
checker had limitations and allowed undefined behavior and memory unsafety. The new NLL
borrow checker can find these problems and was raising warnings about that as a migration
step. These warnings are now hard errors.

The rustc compiler now provides a lint when functions mem::{uninitialized, zeroed} are used
to initialize some of the types, for example, &T and Box<T>.

The following functions are now const fn in the standard library: Vec::new, String::new,
LinkedList::new, str::len, [T]::len, str::as_bytes, abs, wrapping_abs, and overflowing_abs.

23