Cargo Rust Build

Cargo cheatsheet — build, test, run, publish Rust projects. cargo build --release, cargo test, cargo add serde, cargo clippy, cargo fmt. Full Rust toolchain reference.

5 min read

What it is

Cargo is the build system and package manager for the Rust programming language, used for compiling Rust code, managing dependencies, and running tests.

Installation

Cargo is installed automatically with Rustup.

To install Rust and Cargo:

curl --proto '=https' --tlsv1.2 -sSF https://sh.rustup.rs | sh
source $HOME/.cargo/env

Core Concepts

Crates: A Rust crate is a compilation unit. It can be a library or an executable. Cargo manages dependencies between crates.
Dependencies: External crates that your project relies on. Cargo fetches and compiles them automatically.
Manifest (Cargo.toml): The configuration file for a Cargo project. It defines package metadata, dependencies, build profiles, and more.
Build Profiles: Predefined sets of compiler flags and optimizations. Common profiles are dev (for development, fast compilation) and release (for production, optimized for speed and size).
Workspaces: A feature in Cargo that allows managing multiple related crates within a single project, sharing a single Cargo.lock file and build artifacts.

Commands / Usage

Project Management

cargo new <project_name> Create a new binary (executable) project.
```
cargo new my_rust_app
```
cargo new --lib <project_name> Create a new library project.
```
cargo new --lib my_rust_lib
```
cargo init Initialize a new Cargo project in the current directory.
```
cargo init
```
cargo init --lib Initialize a new Cargo library project in the current directory.
```
cargo init --lib
```
cargo check Check a package for errors without compiling it. Faster than cargo build.
```
cargo check
```
cargo build Compile a package and its dependencies. Default is debug build.
```
cargo build
```
cargo build --release Compile a package with optimizations for release.
```
cargo build --release
```
cargo build --target <target_triple> Compile for a specific target architecture.
```
cargo build --target x86_64-unknown-linux-gnu
```
cargo clean Remove the target directory, cleaning the build artifacts.
```
cargo clean
```

Running and Testing

cargo run Compile and run a binary crate.
```
cargo run
```
cargo run --release Compile and run a binary crate with optimizations.
```
cargo run --release
```
cargo run --bin <binary_name> Compile and run a specific binary from a project with multiple binaries.
```
cargo run --bin my_other_app
```
cargo test Run all tests in a package.
```
cargo test
```
cargo test --release Run all tests with optimizations.
```
cargo test --release
```
cargo test <test_name> Run a specific test function by name.
```
cargo test test_addition
```
cargo test --doc Run documentation tests.
```
cargo test --doc
```
cargo bench Run benchmarks in a package.
```
cargo bench
```

Dependency Management

cargo build (when dependencies are missing) Automatically fetches and compiles new dependencies listed in Cargo.toml.
```
# Add serde = "1.0" to [dependencies] in Cargo.toml
cargo build
```
cargo update Update all dependencies to the latest compatible versions according to Cargo.toml and regenerate Cargo.lock.
```
cargo update
```
cargo update --package <crate_name> Update a specific dependency.
```
cargo update --package serde
```
cargo add <crate_name> Add a new dependency to Cargo.toml.
```
cargo add rand
```
cargo add <crate_name> --git <repo_url> Add a dependency from a Git repository.
```
cargo add crossbeam --git https://github.com/crossbeam-rs/crossbeam
```
cargo add <crate_name> --path <local_path> Add a local dependency.
```
cargo add my_local_lib --path ../my_local_lib
```
cargo rm <crate_name> Remove a dependency from Cargo.toml.
```
cargo rm rand
```

Publishing and Packaging

cargo publish Upload a package to crates.io. Requires authentication.
```
cargo publish
```
cargo doc Build documentation for the current crate and all its dependencies.
```
cargo doc
```
cargo doc --open Build documentation and open it in the default web browser.
```
cargo doc --open
```
cargo package Create a local copy of the current package in target/package.
```
cargo package
```

Workspaces

cargo new --workspace <path> Initialize a new workspace.

cargo new --workspace my_workspace
cd my_workspace
cargo new --lib crate_a
cargo new --lib crate_b

cargo build (in workspace root) Builds all crates in the workspace.
```
# From the my_workspace directory
cargo build
```
cargo test (in workspace root) Runs tests for all crates in the workspace.
```
# From the my_workspace directory
cargo test
```

Other Useful Commands

cargo install <crate_name> Install a binary crate from crates.io.
```
cargo install ripgrep
```
cargo install --git <repo_url> Install a binary crate from a Git repository.
```
cargo install --git https://github.com/BurntSushi/ripgrep
```
cargo search <query> Search for crates on crates.io.
```
cargo search serde
```
cargo metadata Output the project’s metadata in JSON format.
```
cargo metadata
```
cargo tree Display the dependency graph.
```
cargo tree
```
cargo tree --depth 1 Display direct dependencies only.
```
cargo tree --depth 1
```

Common Patterns

Building for production:
```
cargo build --release
```
Running a release build:
```
cargo run --release
```
Checking code quickly:
```
cargo check
```
Running tests and checking code:
```
cargo test && cargo check
```
Adding a dependency and rebuilding:
```
cargo add serde
cargo build
```
Updating all dependencies:
```
cargo update
cargo build
```
Cleaning and rebuilding from scratch:
```
cargo clean && cargo build
```

Building for a specific platform (e.g., Raspberry Pi): First, install the target:

rustup target add armv7-unknown-linux-gnueabihf

Then build:

cargo build --target armv7-unknown-linux-gnueabihf

Generating documentation and opening it:
```
cargo doc --open
```
Finding which crate provides a specific function (using cargo search):
```
cargo search "for:function_name"
```
Viewing the dependency tree:
```
cargo tree
```

Gotchas

Cargo.lock file: This file pins exact versions of your dependencies. It should be committed to version control to ensure reproducible builds. Do not edit it manually.
Build artifacts: By default, cargo build creates debug builds in target/debug/. cargo build --release creates optimized builds in target/release/.
Dependency resolution: Cargo’s dependency resolver can sometimes struggle with complex dependency graphs. cargo update can help, but occasionally you might need to adjust versions in Cargo.toml manually.
cargo install path: Binaries installed with cargo install are typically placed in $HOME/.cargo/bin/. Ensure this directory is in your system’s PATH to run them directly.
--target vs. --triple: The --target flag is used for cross-compilation. The value is a target triple (e.g., x86_64-unknown-linux-gnu).
cargo publish authentication: You need an API token from crates.io. Obtain it using cargo login.
Workspaces and Cargo.lock: In a workspace, there is a single Cargo.lock file at the workspace root, not in each individual crate directory. This ensures all crates in the workspace use compatible dependency versions.