Ce contenu n'est pas disponible dans la langue sélectionnée.
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.75.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 The Cargo Book — Package Layout.
- For in-depth information about Rust code organization, see 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.
-
Replace
On Red Hat Enterprise Linux 9:
$ cargo new --bin <project_name>-
Replace
<project_name>with your project name.
-
Replace
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
Complete the following steps to create a Rust library project using the Cargo build tool.
Procedure
To create a Rust library project, run the following command:
On Red Hat Enterprise Linux 8:
$ cargo new --lib <project_name>-
Replace
<project_name>with the name of your Rust project.
-
Replace
On Red Hat Enterprise Linux 9:
$ cargo new --lib <project_name>-
Replace
<project_name>with the name of your Rust project.
-
Replace
To edit the project code, edit the source file, lib.rs, in the src subdirectory.
Additional resources
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
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 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 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 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 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 Beta
Complete the following steps to install the WebAssembly standard library.
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-unknownReplace <command> with the Cargo command you want to run.
On Red Hat Enterprise Linux 9:
# cargo <command> --target wasm32-unknown-unknownReplace <command> with the Cargo command you want to run.
Additional resources
- For more information on WebAssembly, see the official Rust and WebAssembly documentation or the 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 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
