Build and test Rust applications

Use the Cargo build tool to create, build, test, and run Rust projects on Red Hat Enterprise Linux, including release builds and WebAssembly binaries.

Prerequisites

  • Rust Toolset is installed.

Cargo project layout

The Cargo build tool uses conventions for directory structure and file placement within a Cargo package. Running the cargo new command generates the package structure and templates for a manifest and a project file. By default, it 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.

Create a Rust project

Create a new Rust project that follows Cargo conventions. For more information on Cargo conventions, see Cargo project layout.

Procedure

  1. Create a Rust project:
    $ cargo new --bin <project_name>

    Replace <project_name> with your project name.

  2. To edit the project code, edit the main executable file main.rs and add new source files to the src subdirectory.

Build a Rust project

Build your Rust project by using the Cargo build tool. Cargo resolves all dependencies of your project, downloads missing dependencies, and compiles it using the rustc compiler.

Before you begin

About this task

By default, projects are built and compiled in debug mode. For information on compiling your project in release mode, see Build a Rust project in release mode.

Procedure

  1. In the Rust project directory, build the project:
    $ cargo build
  2. To verify that your Rust program can be built when you do not need to build an executable file, enter:
    $ cargo check

Build a Rust project in release mode

Build your Rust project in release mode by 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.

Before you begin

About this task

Cargo resolves all dependencies of your project, downloads missing dependencies, and compiles it by using the rustc compiler.

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

Procedure

  1. In the Rust project directory, build the project in release mode:
    $ cargo build --release
  2. To verify that your Rust program can be built when you do not need to build an executable file, enter:
    $ cargo check

Run a Rust program

In a Cargo project directory, run cargo run command to compile when needed and start your binary. The executable you launch matches your active debug or release profile.

Before you begin

Procedure

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

If your program has not been built yet, Cargo builds your program before running it.

Test a Rust project

Test your Rust program by using the Cargo build tool. Cargo rebuilds your project and then runs the tests found in the project. By default, Rust projects are tested in debug mode.

Before you begin

About this task

By default, Rust projects are tested in debug mode.

Procedure

  1. Add the #[test] attribute in front of your function.
  2. Enter in the project directory:
    $ cargo test

Test a Rust project in release mode

Test your Rust program in release mode by using the Cargo build tool. Cargo rebuilds your project and then runs the tests found in the project. Release mode optimizes your source code, which can increase compilation time while producing a binary that runs faster.

Before you begin

About this task

Cargo first rebuilds your project and then runs the tests found in the project. Test functions must be 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.

Procedure

  1. Add the #[test] attribute in front of your function.
  2. Enter in the project directory:
    $ cargo test --release

Compile code into a WebAssembly binary with Rust

Install the WebAssembly standard library to compile Rust code into WebAssembly binaries.

Before you begin

Procedure

  1. Install the WebAssembly standard library:
    • On RHEL 8, enter:
      # yum install rust-std-static-wasm32-unknown-unknown
    • On RHEL 9 and 10, enter:
      # dnf install rust-std-static-wasm32-unknown-unknown
  2. Use WebAssembly with Cargo:
    $ cargo <command> --target wasm32-unknown-unknown

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