Chapter 2. cargo

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