Introduction

Cargo is the Rust package manager. Cargo downloads your Rust package's dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io, 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 main.rs 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/main.rs 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:

  • name — The name of the package
  • version — The version of the package
  • authors — The authors of the package
  • rust-version — The minimal supported Rust version
  • description — A description of the package
  • documentation — URL of the package documentation
  • readme — Path to the package's README file
  • license — The package license
  • keywords — Keywords for the package
  • categories — Categories of the package
  • workspace — Path to the workspace for the package
  • build — Path to the package build script
  • default-run — The default binary to run by cargo run

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:

  • [dependencies] — Package library dependencies
  • [dev-dependencies] — Dependencies for examples, tests, and benchmarks
  • [build-dependencies] — Dependencies for build scripts
  • [target] — Platform-specific dependencies

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.