Cargo is Rust’s built-in package manager and the build system. It can be used to,
- Create a new project:
- Create a new project in an existing directory:
- Build the project:
- Run the project:
- Update project dependencies:
- Run tests:
- Run benchmarks:
- Generate the project documentation via rustdoc:
- Analyze the project to see it has any errors, without building it:
In addition, there are
cargo commands to publish the project as a crate/ package to Rust’s official crate registry, crates.io.
💡 We need to get an API token from crates.io to publish a crate to it. The API token can be found in the Account Settings page, after login to that site. We will discuss more about this under code organization with crates.
- Login to crates.io with the API token:
- Make the local crate uploadable to crates.io:
- Upload the crate to crates.io:
- Install a Rust binary:
- Uninstall a Rust binary:
A crate is a package, which can be shared via crates.io. A crate can produce an executable or a library. In other words, it can be a binary crate or a library crate.
cargo new crate_name --binor
cargo new crate_name: Produces an executable
cargo new crate_name --lib: Produces a library
The first one generates,
├── Cargo.toml └── src └── main.rs
and the second one generates,
├── Cargo.toml └── src └── lib.rs
- Cargo.toml(capital c) is the configuration file which contains all of the metadata that Cargo needs to compile your project.
- src folder is the place to store the source code.
- Each crate has an implicit crate root/ entry point. main.rs is the crate root for a binary crate and lib.rs is the crate root for a library crate.
💡 When we build a binary crate via
cargo run, the executable file will be stored in the target/debug/ folder. But when building it via
cargo build --releasefor a release it will be stored in the target/release/ folder. The release builds are applying more optimizations while compiling the code, to make the code run faster. But it takes more compile time.
This is how Cargo documentation describes about the recommended project layout,
. ├── Cargo.toml ├── Cargo.lock ├── src │ ├── main.rs │ ├── lib.rs │ └── bin │ └── another_executable.rs ├── tests │ └── some_integration_tests.rs ├── benches │ └── simple_bench.rs └── examples └── simple_example.rs
- The source code goes in the
- The default executable file is
- The default library file is
- Other executables can be placed in
- The default executable file is
- Integration tests go in the
testsdirectory (unit tests go in each file they’re testing).
- Benchmarks go in the
- Examples go in the
After the initial release in 2015, according to the feedback got from user communities, the Rust team was focusing to increase the productivity of the language and the ecosystem. After 3 years of hard work in 2018, a new Rust edition was released with new features, simplified syntax and better tooling. We call it Rust 2018 edition.
To keep the promise of supporting backward compatibility, the new
edition = "2018" configuration was added to the
Cargo.toml file. For new projects, the
cargo new command adds this configuration by default. So, you don’t need to care. But on legacy crates, if you can not see any
edition configuration, Cargo will consider it as a Rust 2015 edition crate.
.cargo/bindirectory of your home directory is the default location of Rust binaries. Not only the official binaries like
rlsand also the binaries you can install via
cargo installcommand, will be stored in this directory.
Even though the initial convention for naming crates and file names is using the
snake_case, some crate developers are using
kebab-caseon both crates and file names. To make your code more consistent, use the initial convention
snake_case; especially on file names.
Create an executable crate via
cargo newcommand and run it via
Create a library crate via
cargo newcommand and run