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.

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:

This chapter lists the steps to perform before installing Rust Toolset on a Red Hat Enterprise Linux 7 system. Complete the following steps to attach a subscription that provides access to the repository for Red Hat Developer Tools, and then enable the Red Hat Developer Tools and Red Hat Software Collections repositories.

Prerequisites

Procedure

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

Additional resources

Complete the following steps to install Rust Toolset on a Red Hat Enterprise Linux system.

Installable documentation

Online documentation

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

There is a specific convention that defines 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, it 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 manifest file Cargo.toml. This file contains all the metadata needed during project compilation. See Section 2.6, “Configuring Rust project dependencies”.

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

In the command above, the option --bin was used to create a binary program. To create a library for a Cargo package instead of a program, run the cargo tool on the command line and pass the --lib option as follows:

As in the previous case, this will create a package directory structure with a root directory project_name containing a library file named lib.rs located in the src subdirectory.

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

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

# yum install tree

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

Running the cargo build command 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. This mode is used for normal development and debugging, when you need to compile the source code quickly and do not need the code optimization.

To build the project in release mode, run the cargo tool with the --release option as follows:

Compilation time is increased in this mode due to optimizations of the source code. As a result, the compiled binary will run faster. Use this mode to produce optimized artifacts suitable for release and production.

$ 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

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:

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

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);
}

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.

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"

Additional resources

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:

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

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

# yum install 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
...
92 directories, 11804 files
$ ls -d target/doc/*/
target/doc/helloworld/  target/doc/implementors/  target/doc/libc/  target/doc/src/  target/doc/time/

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.

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 the cargo-vendor package is included in Cargo, but there has been no change in the way it works.

$ 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

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

Online Cargo documentation

See also

Run the following command to install rustfmt:

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

Replace source-file with the path to a 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 message 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 RHEL 7 and RHEL 8 container images provide content corresponding to the following package:

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

Rust Toolset container image is prepared for use as a Source-to-Image (S2I) builder image.

 $ git clone https://github.com/openshift-s2i/s2i-rust.git
 $ cd s2i-rust
 $ make build

s2i build ./examples/test-app/ devtools/rust-toolset-rhel7 rust-test-app

$ docker run rust-test-app

To fully leverage the Rust as a S2I builder image, build custom images based on it, with modified S2I assemble scripts and further modifications to accomodate the particular application being built.

A detailed description of the Rust usage with Source-to-Image is beyond the scope of this document. For more information about Source-to-Image, see: