As with any other script, Cargo works (by default) on the current working directory. (For example, while writing this chapter, my working directory for the example code is ~/Developer/Rust/chapter0 on the Mac and Linux boxes, and J:\Developer\Rust\Chapter0 on the Windows 10 machine.)

In its simplest form, Cargo can generate the correct file structure like this:

cargo new demo_app_name -bin

The preceding command tells Cargo to create a new structure called demo_app_name, and that it is to be a binary. If you remove -bin, it creates a structure called, which is going to be a library (or more accurately, something other than a binary).

If you don't wish to use the root (say you want to create a library within your binary framework), then instead of demo_app_name, you append the structure before the name relating to your working directory.

In the small example I gave earlier, if I wanted to create a library within my binary structure, I would use the following:

cargo new app_name/mylib

That will create a structure like this:

The Cargo.toml file requires no editing (at this stage), as it contains the information we had to enter manually when we created the project by hand.

When the Rust compiler compiles the source files, it generates something known as an object file. The object file takes the source file (which we can read and understand) and compiles this into a form that can be joined with other libraries to create a binary.

This is a good idea, as it cuts down on compilation time; if a source file has not been changed, there is no need to recompile the file, as the object file will be the same.

Sometimes, the object file becomes out of date, or code in another object file causes a panic due to conflicts. In this case, it is not uncommon to "clean" the build. This removes the object files, and the compiler then has to recompile all the source files.

Also, it should always be performed prior to creating a release build.

The standard Unix make program performs this with the clean command (make clean). Cargo performs the clean operation in a way similar to the make utility in Unix:

cargo clean

A comparison of the directories shows what happens when using the preceding Cargo command:

The entire target directory structure has simply been removed (the preceding screenshot was from a Mac, hence the dSYM and plist files. These do not exist on Linux and Windows).

As with other languages, Rust is able to create documentation based on meta tags with the source files. Take the following example:

fn main() 
{ 
   print_multiply(4, 5); 
} 
 
/// A simple function example 
/// 
/// # Examples 
/// 
/// ``` 
/// print_multiply(3, 5); 
///  
/// ``` 
 
fn print_multiply(x: i32, y: i32) 
{ 
   println!("x * y = {}", x * y); 
} 

The comments preceded by /// will be converted into documentation.

The documentation can be created in one of two ways: via Cargo or by using the rustdoc program.

cargo docrustdoc src/main.rs

Hopefully, unit testing is not something you will be unfamiliar with. A unit test is a test that operates on a specific function or method rather than an entire class or namespace. It ensures that the function operates correctly on the data it is presented with.

Unit tests within Rust are very simple to create (two examples are given in the assert_unittest and unittest directories). The following has been taken from the unittest example:

fn main() { 
    println!("Tests have not been compiled, use rustc --test instead (or cargo test)"); 
} 
 
#[test] 
fn multiply_test() 
{ 
   if 2 * 3 == 5 
   { 
      println!("The multiply worked"); 
   } 
} 

When this is built and executed, you may be surprised by the following result:

We have hit a limitation of unit testing: if we are not testing the data but the operation, how can we know that the result itself is correct?

#[test] 
fn multiply() 
{ 
   assert_eq!(5, 2 * 3); 
} 

For a Rust developer, Cargo is an amazing utility. In addition to these common facilities, it also has other commands, which are listed in the table that follows. All commands follow this form:

cargo <command> <opts>

fetch

generate-lockfile

git-checkout

cargo git-checkout -url=URL

locate-project

login

cargo login -host=HOST   token

owner

package

pkgid

publish

read-manifest

rustc

search

update

verify-project

version

yank

As you can now appreciate, the Cargo utility script is extremely powerful and flexible.