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:
- git
- hg
- pijul
- fossil
- 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 packageversion— The version of the packageauthors— The authors of the packagerust-version— The minimal supported Rust versiondescription— A description of the packagedocumentation— URL of the package documentationreadme— Path to the package's README filelicense— The package licensekeywords— Keywords for the packagecategories— Categories of the packageworkspace— Path to the workspace for the packagebuild— Path to the package build scriptdefault-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.