cargo

Cargo: Rust's build system and package manager

This article explains how Cargo works — Rust's standard build system and package manager — and is intended for developers who want to set up, compile, test, and manage Rust projects.

Prerequisites

- Rust installed via `rustup` (version 1.70 or higher recommended) - Basic knowledge of the command line - Access to crates.io for downloading dependencies (internet connection)

Check your Rust version with:

rustc --version
cargo --version

Steps

1. Creating a new project

Use `cargo init` to start a project in the current directory:

cargo init --bin

For a library, use `--lib`:

cargo init --lib

This generates a `Cargo.toml` file and a source file (`src/main.rs` for binaries, `src/lib.rs` for libraries). The `Cargo.toml` file defines all project metadata and dependencies.

2. Adding dependencies

Search for available crates on crates.io:

cargo search serde

Add a dependency by adding it directly to `Cargo.toml`:

[dependencies]
serde = "1.0"

Cargo downloads, compiles, and makes the crate available within your project. The version in `Cargo.toml` follows semantic versioning — Cargo automatically selects the latest compatible version.

3. Compiling the project

Build your project in debug mode:

cargo build

Cargo internally calls `rustc` and processes all dependencies. For an optimized production build:

cargo build --release

The `--release` flag enables optimizations that produce faster and more compact code.

4. Running tests

Rust has built-in test support. Run all tests:

cargo test

Filter tests by name:

cargo test test_name

Limit the number of concurrent test threads for debugging data races or managing system load:

cargo test -- --test-threads=1

For workspaces with multiple packages:

cargo test --workspace

5. Passing direct compiler options

Use `cargo rustc` to pass specific options directly to `rustc`:

cargo rustc -- -C target-cpu=native

This command optimizes code for the exact processor on which you are building.

6. Continuous feedback with tools

Install `bacon` for automatic checks on code changes:

cargo install bacon
bacon

Bacon continuously runs `cargo check` when you modify files and provides immediate feedback on type errors and compilation issues. Similar tools can also run `cargo test` or `cargo clippy` automatically.

7. Consulting offline documentation

Open the official Rust documentation locally:

rustup doc

This provides access to The Rust Programming Language book, the Cargo book, and the Rust Reference — all available offline.

8. Choosing a specific toolchain per directory

Use `rustup override` to select a specific Rust version or nightly build per project:

rustup override set nightly

This is necessary when different projects depend on different Rust versions. Remove the override with:

rustup override unset

Verification

Check that everything works correctly:

cargo build
cargo test

A successful build produces an executable file in `target/debug/` (or `target/release/` after `--release`). Tests report the number of passed and failed tests. Inspect your project structure:

ls -la
cat Cargo.toml

Frequently encountered problems

1. Dependency cannot be found

Problem: `cargo build` reports "no matching package found" or a network error.

Solution: Check your internet connection and whether the crate exists on crates.io. Update your local registry index:

cargo update

2. Version conflict between dependencies

Problem: Two crates require different, incompatible versions of the same dependency.

Solution: Inspect the dependency tree:

cargo tree

Adjust the version requirements in `Cargo.toml` or use `cargo update -p ` to move to a compatible version.

3. Build fails with "linker not found"

Problem: Your system lacks the C linker that Rust needs.

Solution: Install the build-essential tools for your operating system. On Ubuntu/Debian:

sudo apt install build-essential

On macOS:

xcode-select --install

Cargo is not a standalone tool — it forms the backbone of every Rust workflow, from the first `cargo init` to deploying optimized binaries. Its integration with rustup, crates.io, and the compiler makes it possible to manage projects without having to understand the underlying complexity of build systems. As your projects grow into workspaces, cross-compilation, or custom toolchains, Cargo proves to be scalable — but the question is not what Cargo can do, but which workflow you build around it.