Using Rust Toolset

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 cargo-vendor plug-in, the rustfmt tool, and required libraries.

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 Rust Toolset:

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

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. In order to install 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.

Once the subscription is attached to the system and repositories enabled, you can install Red Hat Rust Toolset as described in Section 1.4, “Installing Rust Toolset”.

Additional Resources

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 in order to install 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 Rust Toolset, see Section 1.3, “Getting Access to Rust Toolset on Red Hat Enterprise Linux 7”.

A detailed description of the Rust programming language and all its features is beyond the scope of this book. For more information, see the resources listed below.

Installed Documentation

Online Documentation

In Rust Toolset on Red Hat Enterprise Linux 7, cargo is provided by the rust-toolset-1.31-cargo package and is automatically installed with the rust-toolset-1.31 package. On Red Hat Enterprise Linux 8, cargo is provided by the rust-toolset module. See Section 1.4, “Installing Rust Toolset”.

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

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:

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 Toolset binaries available. This allows you to run a shell session with Rust Toolset cargo command directly available:

scl enable rust-toolset-1.31 'bash'

$ scl enable rust-toolset-1.31 'bash'

cd helloworld
tree
cat src/main.rs

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

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

yum install tree

# yum install tree

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

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:

tree

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

8 directories, 6 files

yum install tree

# yum install tree

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:

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

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:

date
ls -l target/debug/helloworld

$ 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

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:

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

Using cargo to run a Rust program during development is preferred, because it will correctly resolve the output path independent 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:

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

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:

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

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

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

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

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’s dependencies. Each dependency is listed on a new line in the following format:

crate_name = version

crate_name = version

Rust code packages are called crates.

extern crate time;

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

extern crate time;

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

[package]
name = "helloworld"
version = "0.1.0"
authors = ["Your Name <yourname@example.com>"]

[dependencies]
time = "0.1"

[package]
name = "helloworld"
version = "0.1.0"
authors = ["Your Name <yourname@example.com>"]

[dependencies]
time = "0.1"

Additional Resources

Rust code can contain comments marked for extraction into documentation. These comments support the Markdown language. To build project documentation using the cargo tool, change to the project directory and run the cargo tool as follows:

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

Note that the cargo doc command extracts documentation comments only for public functions, variables and members.

The command cargo doc uses the rustdoc utility. Using cargo doc is preferred to rustdoc.

//! 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();
}

//! 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();
}

tree

$ tree
.
├── 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

tree
ls -d target/doc/*/

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

yum install tree

# yum install tree

Additional Resources

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

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.

The cargo vendor command for vendoring dependencies is supplied by the cargo plug-in cargo-vendor.

To install cargo-vendor 0.1.22 :

To vendor dependencies for a cargo project, change to the project directory and run the cargo tool as follows:

This creates a directory vendor and downloads sources of all dependencies to this directory. Additional configuration steps are printed to command line.

The cargo vendor command gathers the dependencies for a platform-independent result. Dependency crates for all potential target platforms are downloaded.

ls
tree vendor

$ 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

yum install tree

# yum install tree

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

Installed Documentation

Online Documentation

See Also

On Red Hat Enterprise Linux 7, the rustfmt tool is provided by the rust-toolset-1.31-rustfmt-preview package. To install it:

yum install rust-toolset-1.31-rustfmt-preview

# yum install rust-toolset-1.31-rustfmt-preview

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

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:

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

To format all source files in a cargo crate:

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:

The devtools/rust-toolset-1.31-rhel7 image provides content corresponding to the following packages:

To pull the devtools/rust-toolset-1.31-rhel7 image, run the following command as root:

podman pull registry.access.redhat.com/devtools/rust-toolset-1.31-rhel7

# podman pull registry.access.redhat.com/devtools/rust-toolset-1.31-rhel7

Rust has been updated from version 1.29.0 to 1.31.1. Notable changes include:

The cargo tool has been updated from version 1.29.0 to 1.31.0. Notable changes include: