Working with Cargo

Cargo is Rust's package and dependency manager, like Bundler, npm, pub, or pip for other languages. Although you can write Rust programs without it, Cargo is nearly indispensable for any larger project. It works the same whether you work on a Windows, Linux, or OS X system. The installation procedure from the previous section includes the Cargo tool, cargo, so Rust is shipped with the batteries included.

Cargo does the following things for you:

• It makes a tidy folder structure and some templates for your project, with the following command:

    cargo new  

• It compiles (builds) your code, using the following command:

    cargo build

• It runs your project, using the following command:

    cargo run

• If your project contains unit-tests, it can execute them for you, using the following command:

    cargo test

• If your project depends on packages, it will download them and it will build these packages according to the needs of your code, using the following command:

    cargo update

We'll introduce how to use Cargo now, and we'll come back to it later, but you can find more info at http://doc.crates.io/guide.html.

Let's remake our first project, welcome, using Cargo through the following steps:

1. Start a new project, welcomec, with the following command:

cargo new welcomec --bin  

• The option --bin tells Cargo that we want to make an executable program (a binary). This outputs the message Created binary (application) `welcomec` project and creates the following directory structure:
  
• A folder with the same name as the project is created as a local Git project. In this folder, you can put all kinds of general info such as a License file, a README file, and so on. Also, a subfolder, src, is created, containing a template source file named main.rs (this contains the same code as our welcome.rs, but prints out the string "Hello, world!").
• The file Cargo.toml (with a capital C) is the configuration file or manifest of your project; it contains all the metadata Cargo needs to compile your project. It follows the so called TOML format (for more details about this format, see https://github.com/toml-lang/toml), and contains the following text with information about the project:

[package] 
name = "welcomec" 
version = "0.1.0" 
authors = ["Your name <you@example.com>"] 
[dependencies]

• This file is editable and other sections can be added. For example, you can add a section to tell Cargo that we want a binary with name:

welcome: 
[[bin]]   
name = "welcome" 

1. We build our project (no matter how many source files it contains) with the following command:

cargo build

• Which gives us the following output (on Linux):

    Compiling welcomec v0.1.0 (file:///home/ivo/Rust_Book/welcomec)
    Finished dev [unoptimized + debuginfo] target(s) in 0.66 secs

• Now, the following folder structure is produced:
  
• The target/debugdirectory contains the executable welcome.

1. To execute this program, give the following command:

    cargo run

• Which produces as output:

    Running `target/debug/welcome`
    Hello, world!

Step 2 has also produced a file called Cargo.lock; this is used by Cargo to keep track of dependencies in your application. At this moment, it contains only the following:

[root] 
name = "welcomec" 
version = "0.1.0" 

The same format is used to lock down the versions of libraries or packages your project depends on. If your project is built in the future, when updated versions of the libraries are available, Cargo will make sure that only the versions recorded in Cargo.lock are used, so that your project is not built with an incompatible version of a library. This ensures a repeatable build process.

The cargo -list gives you an overview of the commands you can use within this tool.

The site https://crates.io/ is the central repository for Rust packages, or crates as they are called, containing over 10000 crates at the end of June 2017. You can search for crates with specific terms, or browse them alphabetically or by number of downloads. The site looks like the following: