A Rustaceans' introduction to the Cargo package manager

Creating, setting up and managing a Rust project using Cargo


Cargo is the Rust package manager. Cargo downloads your Rust package's dependencies, compiles your packages, makes distributable packages, and uploads them to, the Rust community's package registry.

To see if you have cargo installed, use:

cargo --version

Creating a new project

The cargo new command is used to create a new project, it creates a directory called hello_cargo that contains a file called cargo.toml, a src folder and a new git repository.

cargo new <project-name>

Note: Replace <project-name> with the name of your project. In this case, we'll use hello_cargo as the project name.

Inside of the generated directory's src folder is a file called which is the entry point of this Rust program.

Version control system

Rust also takes care of setting up a Version Control System (VCS) for us, the default option is Git. The project's repository folder (.git) is created in the project's root directory.

To use a different VCS or to disable it entirely, use the --vcs option with the cargo new command, the supported version control system's are:

  1. git
  2. hg
  3. pijul
  4. fossil
  5. none

When you use the "none" option, no version control system is initiated and repositories are created. Only the source files (src/ and cargo.toml) files are generated for the project.

Project directory

Rust expects your source files to live inside of the src folder. The root folder is for README's, licenses, config files and anything else not related to the source code of your program.

If you started with a project that doesn't use cargo but would like to add cargo to your project, create a new folder called src and move your project's source code into that folder. Then create a cargo.toml file and run cargo build. Make sure your current working directory (CWD) is the root of your project or the folder that contains your src folder.

To change the current CWD, use the cd command followed by the directory path of your project folder's root:

cd path/to/root/of/project

Contents of the cargo.toml file

The cargo.toml file is a TOML document with 2 headings, the first heading: [packages] defines a package and specifies program information. [1]

For example, the [packages] heading can include information like:

The next heading [dependencies] states the list of your programs packages, known as crates in rust. Although sometimes you might need multiple types of dependency headings:

Build, run and check

The cargo build command creates an executable from the available source code (if no compiler errors are thrown) but Cargo won't run the program after building it. To build and run a program you'd use the cargo run command. Both cargo run and cargo build will compile the code and create a new executable in the target/debug folder.

To compile your project with optimizations for distribution use: cargo build --release, however, you should keep in mind that cargo build --release is far slower than cargo build and should only be used when you actually want to build a release edition of your program.