Chapter 2. cargo

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

$ scl enable rust-toolset-7 '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!");
}

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.

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-7 '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

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.

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-7 'cargo check'
   Compiling helloworld v0.1.0 (file:///home/vslavik/helloworld)
    Finished dev [unoptimized + debuginfo] target(s) in 0.5 secs

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

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-7 'cargo run'
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running target/debug/helloworld
Hello, world!

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.

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

The function my_test marked as a test has been added.

Save the file, and run the test:

$ scl enable rust-toolset-7 '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

cargo first rebuilds the project, and then runs the tests found in the project. The test my_test has been succesfully passed.

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

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"

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

$ scl enable rust-toolset-7 '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

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.

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

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-7 '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

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-7 '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/

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

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-7 '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

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.