This section is also available in the form of film.

1.3 Cargo

When your project starts getting large, it can be quite the job keeping track of all your projects’ files—as well as manually having to compile a whole bunch of files every single time you wish to run your program.

Rust solves the pain of tending to huge projects by introducing Cargo, which is a system for building and managing packages. It has the capability of building your code, downloading Rust libraries—or dependencies—that your project is dependent on, as well as building those libraries. This means that using Cargo you can create organized projects containing all your files, including project dependent files—everything to give you an easier time programming inside the Rust programming language.

Cargo comes bundled up togeter with the installer for Rust and should already be on your computer unless you installed Rust using some other means—other than that from the section Get-go. Similarly to how we checked what version Rust was in, we can check what version Cargo currently is in by running cargo with the --version flag appended:

$ cargo --version

The word cargo is the name of the command used to access anything that has to do with Rust’s package manager Cargo. The --version flag makes cargo print the version of Cargo we’ve installed on our computers:

cargo 0.13.0-nightly (109cb7c 2016-08-19)

Just like Rust might have different versions depending on the time you decide to run it, our outputs as for the version will look somewhat different from one anothers’.

Creating a new project

Let us recreate the program we created in the section Get-go. It’s extremely easy to set up a new project using Cargo:

$ cargo new hello_world --bin

The keyword new after cargo tells Cargo we wish to create a new project. The word hello_world is the name of the project. By convention, Cargo project names are written using lowercase snake case. Finally, the flag --bin tells Cargo that the type of project we’re creating is a binary project. Without this flag specified, Cargo will generate a library project for us, which is really only used when we create code that’s meant to be used by other binary projects.

Inside the folder where you ran the command, you’ll now find a beautifully laid out Rust Cargo project before your eyes:

+ hello_world
|-- src
|  `--main.rs
|-- Cargo.toml
`-- .gitignore

For now, we’ve no real use for the .gitignore, as that file mainly is used for git repositories. In fact, the whole Cargo project is set up in a way that we can use it as a git project had we wanted to.

Cargo.toml

The first file we will find real use for is the Cargo.toml. This is a .toml file, whose extension is short for ‘Tom’s Obvious, Minimal Language’. TOML is used by Cargo to manage the project in ways such as requiring dependencies (libraries), as well as editing the project’s basic information.

Opening it in a text editor will confront you with something similar to this:

[package]
name = "hello_world"
version = "0.1.0"
authors = ["user"]

[dependencies]

Anyting inside [] is a label. There are two labels in this example: package and dependencies. The package section contains information regarding your project: its name, its version written using semantic versioning, as well as its authors. The dependencies section contains a list of all dependencies—or libraries if you will—contained by your project. Whenever you launch your application, dependencies will automatically be downloaded from crates.io, followed by being built.

Before you carry on from here, it’s recommended that you input the correct authors for your project. By convention, the authors are supposed to be formatted like this:

authors = ["John Doe <john@example.com>"]

John Doe is the name of the author, whilst whatever is located inside the <> is that author’s email. Providing an email address is optional and multiple authors may be added by seperating the entries inside the [] by ,.

Sorce folder

Another interesting piece of the project Cargo generated for us is the src folder. This is where you keep all your source files—containing code—for you program, at the same time as this is where Cargo builds your code from. You may notice that there’s already a file located inside the src folder—a file called main.rs. Go ahead and open that in your text editor of choice:

fn main() {
    println!("Hello, world!");
}

Cargo was kind enough to generate some basic code for us. This sure looks a lot like the code from our previous encounters with Rust code, does it not? The only real difference is that the code block begins right after the fn main(), when we chose to put it after a line break when we wrote it.

Whilst technically Rust’s convention is to write your curly braces on the same line as whatever they’re connected to, there are good reasons as to why you shouldn’t do this. Usually as one gets more experienced, one switches to putting curly braces on a new line in order to improve on readability.

Whatever style you feel fits you the best—stick to it—as long as you are continuously using the same style for all your code: otherwise navigating it may become a slight bit more difficult.

Building and running

There are two important commands that you most certainly should learn by heart as soon as you start using Cargo: build and run. The former compiles our project for us, the latter both compiles and runs it. Do not feel scared to use run oftenly: it only compiles what files are necessary to be compiled. In order to execute any of these commands, you need to be located inside the base-folder of a Cargo project. In our case, that’s the folder hello_world.

Let’s build the piece of code Cargo generated for us:

$ cargo build Hello, world!

The result of this program is the same to that of the program we made ourselves, considering the code is almost identical. Cargo will tell us that it’s compiled the program successfully—unless it runs into exceptions—which needs all be handled or solved before being able to carry on.

In order to run the program, we need to use the way we ran it earlier. This is why manually building may feel tedious and run might feel as though a better way to go.

Here is how you run it using the previous way on a Unix-based system, upon being located inside the hello_world folder:

$ ./target/debug/hello_world Hello, world!

The compiled version of our program appears in a new folder called debug located under another new folder by the name of target. We use that path to run it the same way we previously have. This way is—as mentioned earlier—quite a tedious way to go. For that reason, it might very well suit us better to both compile and run the program at the same time using Cargo’s run command:

$ cargo run
    Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
    Running target\debug\test3.exe
Hello, world!

Suddenly we’ve both compiled and run our program. Both by running one single command.

Moreover

By not using Cargo, managing your projects are almost required to have another solution than that of compiling and running using the standard method. Once your projects start getting huge, Cargo is a huge relief for both the seasoned and unseasoned programmer.