Ce contenu n'est pas disponible dans la langue sélectionnée.
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.
NoteConsider 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.
Rust Toolset is distributed with cargo 1.35.0.
2.1. Installing cargo Copier lienLien copié sur presse-papiers!
Install Rust Toolset, see Section 1.4, “Installing Rust Toolset”.
Notecargo is installed as a part of Rust Toolset.
On Red Hat Enterprise Linux 7, cargo is provided by the rust-toolset-1.35-cargo package.
On Red Hat Enterprise Linux 8, cargo is provided by the rust-toolset module.
2.2. Creating a New Project Copier lienLien copié sur presse-papiers!
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.35 'cargo new --bin project_name'
$ scl enable rust-toolset-1.35 'cargo new --bin project_name'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo new --bin project_name
$ cargo new --bin project_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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:
For Red Hat Enterprise Linux 7:
scl enable rust-toolset-1.35 'cargo new --lib project_name'
$ scl enable rust-toolset-1.35 'cargo new --lib project_name'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo new --lib project_name
$ cargo new --lib project_nameCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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.35 'bash'
$ scl enable rust-toolset-1.35 '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.35 'cargo new --bin helloworld'
$ scl enable rust-toolset-1.35 'cargo new --bin helloworld' Created binary (application) helloworld projectCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo new --bin helloworld
$ cargo new --bin helloworld Created binary (application) helloworld projectCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Examine the result:
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.
The tree tool is available from the default Red Hat Enterprise Linux repositories. To install it:
yum install tree
# yum install tree
2.3. Building a Project Copier lienLien copié sur presse-papiers!
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.35 'cargo build'
$ scl enable rust-toolset-1.35 'cargo build'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo build
$ cargo buildCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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.35 'cargo build --release'
$ scl enable rust-toolset-1.35 'cargo build --release'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo build --release
$ cargo build --releaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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.35 'cargo build'
$ scl enable rust-toolset-1.35 'cargo build' Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.51 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo build
$ cargo build Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.51 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Examine the result:
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.
The tree tool is available from the default Red Hat Enterprise Linux repositories. To install it:
yum install tree
# yum install tree
2.4. Checking a Program Copier lienLien copié sur presse-papiers!
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.35 'cargo check'
$ scl enable rust-toolset-1.35 'cargo check'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo check
$ cargo checkCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Consider using cargo check over cargo build 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.
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.35 'cargo check --release'
$ scl enable rust-toolset-1.35 'cargo check --release'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo check --release
$ cargo check --releaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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.35 'cargo check'
$ scl enable rust-toolset-1.35 'cargo check' Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.5 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo check
$ cargo check Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.5 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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 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
2.5. Running a Program Copier lienLien copié sur presse-papiers!
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.35 'cargo run'
$ scl enable rust-toolset-1.35 'cargo run'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo run
$ cargo runCopy to Clipboard Copied! Toggle word wrap Toggle overflow
If the program has not been built yet, cargo will run a build before running the program.
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.35 'cargo run --release'
$ scl enable rust-toolset-1.35 'cargo run --release'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo run --release
$ cargo run --releaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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.35 'cargo run'
$ scl enable rust-toolset-1.35 'cargo run' Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs Running target/debug/helloworld Hello, world!Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo run
$ cargo run Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs Running target/debug/helloworld Hello, world!Copy to Clipboard Copied! Toggle word wrap Toggle overflow
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 Copier lienLien copié sur presse-papiers!
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.35 'cargo test'
$ scl enable rust-toolset-1.35 'cargo test'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo test
$ cargo testCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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.35 'cargo test --release'
$ scl enable rust-toolset-1.35 'cargo test --release'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo test --release
$ cargo test --releaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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:
The function my_test marked as a test has been added.
Save the file, and run the test:
For Red Hat Enterprise Linux 7:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
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 Copier lienLien copié sur presse-papiers!
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.
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:
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:
Run the cargo run command to build the project and run the resulting executable file:
For Red Hat Enterprise Linux 7:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
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 Copier lienLien copié sur presse-papiers!
Consider using cargo doc over rustdoc. The command cargo doc utilizes the rustdoc utility.
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.35 'cargo doc --no-deps'
$ scl enable rust-toolset-1.35 'cargo doc --no-deps'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo doc --no-deps
$ cargo doc --no-depsCopy to Clipboard Copied! Toggle word wrap Toggle overflow
This extracts documentation stored from the special comments in the source code of your project and writes the documentation in HTML format.
-
Omit the
--no-depsoption to include dependencies in the generated documentation, including third party libraries. -
Add the
--openoption 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:
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.35 'cargo doc --no-deps'
$ scl enable rust-toolset-1.35 'cargo doc --no-deps' Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.31 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo doc --no-deps
$ cargo doc --no-deps Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.31 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Install tree tool (Available in the default Red Hat Enterprise Linux repositories.), if not already installed:
yum install tree
# yum install tree
Examine the result:
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.35 'cargo doc'
$ scl enable rust-toolset-1.35 '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 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo doc
$ 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 secsCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Examine the resulting folder structure with tree command:
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/
The resulting documentation now covers also the dependency libraries time and libc, with each present as another subdirectory in the target/doc/ directory.
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.
- Making Useful Documentation Comments from the official Rust Programming Language documentation.
2.9. Vendoring Project Dependencies Copier lienLien copié sur presse-papiers!
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.23 :
For Red Hat Enterprise Linux 7:
yum install rust-toolset-1.35-cargo-vendor
# yum install rust-toolset-1.35-cargo-vendorCopy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
dnf install cargo-vendor
# dnf install cargo-vendorCopy to Clipboard Copied! Toggle word wrap Toggle overflow
To vendor dependencies for a cargo project, change to the project directory and run the cargo tool as follows:
For Red Hat Enterprise Linux 7:
scl enable rust-toolset-1.35 'cargo vendor'
$ scl enable rust-toolset-1.35 'cargo vendor'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo vendor
$ cargo vendorCopy to Clipboard Copied! Toggle word wrap Toggle overflow
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.
The cargo vendor command is an experimental, unofficial plug-in for the cargo tool.
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:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
cargo vendor
$ cargo vendorCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Examine the result:
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.
The tree tool is available from the default Red Hat Enterprise Linux repositories. To install it:
yum install tree
# yum install tree
2.10. Additional Resources Copier lienLien copié sur presse-papiers!
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.
Cargo Documentation
cargo(1) — The manual page for the
cargotool provides detailed information on its usage. To display the manual page for the version included in Rust Toolset:For Red Hat Enterprise Linux 7:
scl enable rust-toolset-1.35 'man cargo'
$ scl enable rust-toolset-1.35 'man cargo'Copy to Clipboard Copied! Toggle word wrap Toggle overflow For Red Hat Enterprise Linux 8:
man cargo
$ man cargoCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Cargo, Rust’s Package Manager HTML book is provided as a package:
On Red Hat Enterprise Linux 7:
yum install rust-toolset-1.35-cargo-doc
# yum install rust-toolset-1.35-cargo-docCopy to Clipboard Copied! Toggle word wrap Toggle overflow The HTML is available at
/opt/rh/rust-toolset-1.35/usr/share/doc/cargo/html/index.htmlOn Red Hat Enterprise Linux 8:
yum install cargo-doc
# yum install cargo-docCopy to Clipboard Copied! Toggle word wrap Toggle overflow The HTML is available at
/usr/share/doc/cargo/html/index.html
Online Cargo Documentation
See Also
- Chapter 1, Rust Toolset — An overview of Rust Toolset and more information on how to install it on your system.