Chapter 2. cargo

2.1. Installing cargo
Copiar o link

In Rust Toolset, cargo is provided by the rust-toolset-1.29-cargo package and is automatically installed with the rust-toolset-1.29 package. See Section 1.4, “Installing Rust Toolset”.

2.2. Creating a New Project
Copiar o link

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

scl enable rust-toolset-1.29 'cargo new --bin project_name'

$ scl enable rust-toolset-1.29 'cargo new --bin project_name'

Copy to Clipboard

Toggle word wrap

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:

scl enable rust-toolset-1.29 'cargo new --lib project_name'

$ scl enable rust-toolset-1.29 'cargo new --lib project_name'

Copy to Clipboard

Toggle word wrap

Note that you can execute any command using the scl utility, 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.29 'bash'

$ scl enable rust-toolset-1.29 'bash'

Copy to Clipboard

Toggle word wrap

Example 2.1. Creating a Project using cargo

Create a new Rust project called helloworld and examine the result:

scl enable rust-toolset-1.29 'cargo new --bin helloworld'
cd helloworld
tree
cat src/main.rs

$ scl enable rust-toolset-1.29 'cargo new --bin helloworld'
     Created binary (application) helloworld project
$ cd helloworld
$ tree
.
├── Cargo.toml
└── src
    └── main.rs

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

Copy to Clipboard

Toggle word wrap

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.

Note

The tree tool is available from the default Red Hat Enterprise Linux repositories. To install it:

yum install tree

# yum install tree

Copy to Clipboard

Toggle word wrap

2.3. Building a Project
Copiar o link

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

scl enable rust-toolset-1.29 'cargo build'

$ scl enable rust-toolset-1.29 'cargo build'

Copy to Clipboard

Toggle word wrap

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:

scl enable rust-toolset-1.29 'cargo build --release'

$ scl enable rust-toolset-1.29 'cargo build --release'

Copy to Clipboard

Toggle word wrap

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, build the project, and examine the result:

scl enable rust-toolset-1.29 'cargo build'
tree

$ scl enable rust-toolset-1.29 'cargo build'
   Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld)
    Finished dev [unoptimized + debuginfo] target(s) in 0.51 secs
$ tree
.
├── Cargo.lock
├── Cargo.toml
├── src
│   └── main.rs
└── target
    └── debug
        ├── build
        ├── deps
        │   └── helloworld-b7c6fab39c2d17a7
        ├── examples
        ├── helloworld
        ├── helloworld.d
        ├── incremental
        └── native

8 directories, 6 files

Copy to Clipboard

Toggle word wrap

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.

Note

The tree tool is available from the default Red Hat Enterprise Linux repositories. To install it:

yum install tree

# yum install tree

Copy to Clipboard

Toggle word wrap

2.4. Checking a Program
Copiar o link

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:

scl enable rust-toolset-1.29 'cargo check'

$ scl enable rust-toolset-1.29 'cargo check'

Copy to Clipboard

Toggle word wrap

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:

scl enable rust-toolset-1.29 'cargo check --release'

$ scl enable rust-toolset-1.29 'cargo check --release'

Copy to Clipboard

Toggle word wrap

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:

scl enable rust-toolset-1.29 'cargo check'

$ scl enable rust-toolset-1.29 'cargo check'
   Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld)
    Finished dev [unoptimized + debuginfo] target(s) in 0.5 secs

Copy to Clipboard

Toggle word wrap

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

Copy to Clipboard

Toggle word wrap

2.5. Running a Program
Copiar o link

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:

scl enable rust-toolset-1.29 'cargo run'

$ scl enable rust-toolset-1.29 'cargo run'

Copy to Clipboard

Toggle word wrap

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:

scl enable rust-toolset-1.29 'cargo run --release'

$ scl enable rust-toolset-1.29 'cargo run --release'

Copy to Clipboard

Toggle word wrap

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:

scl enable rust-toolset-1.29 'cargo run'

$ scl enable rust-toolset-1.29 'cargo run'
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running target/debug/helloworld
Hello, world!

Copy to Clipboard

Toggle word wrap

cargo first rebuilds the project, and then runs the resulting executable file.

Note that 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
Copiar o link

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

scl enable rust-toolset-1.29 'cargo test'

$ scl enable rust-toolset-1.29 'cargo test'

Copy to Clipboard

Toggle word wrap

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:

scl enable rust-toolset-1.29 'cargo test --release'

$ scl enable rust-toolset-1.29 'cargo test --release'

Copy to Clipboard

Toggle word wrap

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:

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

Copy to Clipboard

Toggle word wrap

The function my_test marked as a test has been added.

Save the file, and run the test:

scl enable rust-toolset-1.29 'cargo test'

$ scl enable rust-toolset-1.29 'cargo test'
   Compiling helloworld v0.1.0 (file:///home/vslavik/Documentation/rusttest/helloworld)
    Finished dev [unoptimized + debuginfo] target(s) in 0.26 secs
     Running target/debug/deps/helloworld-9dd6b83647b49aec

running 1 test
test my_test ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

Copy to Clipboard

Toggle word wrap

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
Copiar o link

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

Copy to Clipboard

Toggle word wrap

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:

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

Copy to Clipboard

Toggle word wrap

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:

[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"

Copy to Clipboard

Toggle word wrap

Finally, run the cargo run command to build the project and run the resulting executable file:

scl enable rust-toolset-1.29 'cargo run'

$ scl enable rust-toolset-1.29 'cargo run'
    Updating registry `https://github.com/rust-lang/crates.io-index`
 Downloading time v0.1.38
 Downloading libc v0.2.32
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/helloworld`
Hello, world!
Time is: Fri, 13 Oct 2017 11:08:57

Copy to Clipboard

Toggle word wrap

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
Copiar o link

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:

scl enable rust-toolset-1.29 'cargo doc --no-deps'

$ scl enable rust-toolset-1.29 'cargo doc --no-deps'

Copy to Clipboard

Toggle word wrap

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.

To include dependencies in the generated documentation, including third party libraries, omit the --no-deps option.
To show the generated documentation in your browser, add the --open option.

The command cargo doc uses the rustdoc utility. Using cargo doc is preferred to rustdoc.

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:

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

Copy to Clipboard

Toggle word wrap

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 and examine the result:

scl enable rust-toolset-1.29 'cargo doc --no-deps'
tree

$ scl enable rust-toolset-1.29 'cargo doc --no-deps'
 Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld)
    Finished dev [unoptimized + debuginfo] target(s) in 0.31 secs
$ 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

Copy to Clipboard

Toggle word wrap

cargo builds the project documentation. To actually view the documentation, open the file target/doc/helloworld/index.html in your browser.

Note that the generated documentation does not contain any mention of the main() function, because it is not public.

Finally, run the cargo doc command without the --no-deps option to build the project documentation, including the dependency libraries time and libc, and examine the result:

scl enable rust-toolset-1.29 'cargo doc'
tree
ls -d target/doc/*/

$ scl enable rust-toolset-1.29 '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 secs
$ tree
...
92 directories, 11804 files
$ ls -d target/doc/*/
target/doc/helloworld/  target/doc/implementors/  target/doc/libc/  target/doc/src/  target/doc/time/

Copy to Clipboard

Toggle word wrap

The resulting documentation now covers also the dependency libraries time and libc, with each present as another subdirectory in the target/doc/ directory.

Note

The tree tool is available from the default Red Hat Enterprise Linux repositories. To install it:

yum install tree

# yum install tree

Copy to Clipboard

Toggle word wrap

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.

Documentation — The official book The Rust Programming Language has a section on documentationin the first edition.

2.9. Vendoring Project Dependencies
Copiar o link

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 plugin cargo-vendor. Rust Toolset is distributed with cargo-vendor 0.1.17. To install cargo-vendor:

yum install rust-toolset-1.29-cargo-vendor

# yum install rust-toolset-1.29-cargo-vendor

Copy to Clipboard

Toggle word wrap

To vendor dependencies for a cargo project, change to the project directory and run the cargo tool as follows:

scl enable rust-toolset-1.29 'cargo vendor'

$ scl enable rust-toolset-1.29 'cargo vendor'

Copy to Clipboard

Toggle word wrap

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.

Important

The cargo vendor command is an experimental, unofficial plugin 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, run the cargo vendor command to vendor the project with dependencies and examine the result:

scl enable rust-toolset-1.29 'cargo vendor'
ls
tree vendor

$ scl enable rust-toolset-1.29 'cargo vendor'
 Downloading kernel32-sys v0.2.2
 Downloading redox_syscall v0.1.31
 Downloading winapi-build v0.1.1
 Downloading winapi v0.2.8
   Vendoring kernel32-sys v0.2.2 (/home/vslavik/.cargo/registry/src/github.com-1ecc6299db9ec823/kernel32-sys-0.2.2) to vendor/kernel32-sys
   Vendoring libc v0.2.32 (/home/vslavik/.cargo/registry/src/github.com-1ecc6299db9ec823/libc-0.2.32) to vendor/libc
   Vendoring redox_syscall v0.1.31 (/home/vslavik/.cargo/registry/src/github.com-1ecc6299db9ec823/redox_syscall-0.1.31) to vendor/redox_syscall
   Vendoring time v0.1.38 (/home/vslavik/.cargo/registry/src/github.com-1ecc6299db9ec823/time-0.1.38) to vendor/time
   Vendoring winapi v0.2.8 (/home/vslavik/.cargo/registry/src/github.com-1ecc6299db9ec823/winapi-0.2.8) to vendor/winapi
   Vendoring winapi-build v0.1.1 (/home/vslavik/.cargo/registry/src/github.com-1ecc6299db9ec823/winapi-build-0.1.1) to vendor/winapi-build
To use vendored sources, add this to your .cargo/config for this project:

    [source.crates-io]
    replace-with = "vendored-sources"

    [source.vendored-sources]
    directory = "/home/vslavik/helloworld/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

Copy to Clipboard

Toggle word wrap

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.

Note

The tree tool is available from the default Red Hat Enterprise Linux repositories. To install it:

yum install tree

# yum install tree

Copy to Clipboard

Toggle word wrap

2.10. Additional Resources
Copiar o link

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

cargo(1) — The manual page for the cargo tool provides detailed information on its usage. To display the manual page for the version included in Rust Toolset:
```
scl enable rust-toolset-1.29 'man cargo'
```
```
$ scl enable rust-toolset-1.29 'man cargo'
```
Copy to Clipboard Toggle word wrap
Cargo, Rust’s Package Manager — Documentation on the cargo tool can be optionally installed:
```
yum install rust-toolset-1.29-cargo-doc
```
```
# yum install rust-toolset-1.29-cargo-doc
```
Copy to Clipboard Toggle word wrap
Once installed, HTML documentation is available at /opt/rh/rust-toolset-1.29/root/usr/share/doc/cargo/html/index.html.

Online Documentation

Cargo Guide — The cargo tool documentation provides detailed information on cargo's usage.

Este conteúdo não está disponível no idioma selecionado.

2.1. Installing cargo
Copiar o link

2.2. Creating a New Project
Copiar o link

2.3. Building a Project
Copiar o link

2.4. Checking a Program
Copiar o link

2.5. Running a Program
Copiar o link

2.6. Running Project Tests
Copiar o link

2.7. Configuring Project Dependencies
Copiar o link

Additional Resources

2.8. Building Project Documentation
Copiar o link

Additional Resources

2.9. Vendoring Project Dependencies
Copiar o link

2.10. Additional Resources
Copiar o link

Installed Documentation

Online Documentation

See Also

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Tornando o open source mais inclusivo

Sobre a Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Este conteúdo não está disponível no idioma selecionado.

Chapter 2. cargo

2.1. Installing cargoCopiar o linkLink copiado para a área de transferência!

2.2. Creating a New ProjectCopiar o linkLink copiado para a área de transferência!

2.3. Building a ProjectCopiar o linkLink copiado para a área de transferência!

2.4. Checking a ProgramCopiar o linkLink copiado para a área de transferência!

2.5. Running a ProgramCopiar o linkLink copiado para a área de transferência!

2.6. Running Project TestsCopiar o linkLink copiado para a área de transferência!

2.7. Configuring Project DependenciesCopiar o linkLink copiado para a área de transferência!

Additional Resources

2.8. Building Project DocumentationCopiar o linkLink copiado para a área de transferência!

Additional Resources

2.9. Vendoring Project DependenciesCopiar o linkLink copiado para a área de transferência!

2.10. Additional ResourcesCopiar o linkLink copiado para a área de transferência!

Installed Documentation

Online Documentation

See Also

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Tornando o open source mais inclusivo

Sobre a Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.1. Installing cargo
Copiar o link

2.2. Creating a New Project
Copiar o link

2.3. Building a Project
Copiar o link

2.4. Checking a Program
Copiar o link

2.5. Running a Program
Copiar o link

2.6. Running Project Tests
Copiar o link

2.7. Configuring Project Dependencies
Copiar o link

2.8. Building Project Documentation
Copiar o link

2.9. Vendoring Project Dependencies
Copiar o link

2.10. Additional Resources
Copiar o link