๐ŸŽ“ A1Learner
๐Ÿ”

Rust Cargo Commands

A Cargo command is a word typed after cargo that tells Cargo one job to do. The everyday commands are new, build, run, check and test.

Find a crate, then add it

search lists each match from crates.io with its newest version and a one-line description. add writes the crate into Cargo.toml for you. remove takes it out again.

cargo search itoa
cargo add itoa
cargo remove itoa

Move the lockfile, not the ranges

update re-solves Cargo.lock with the newest versions your ranges allow โ€” the ranges stay untouched. Pin one library exactly with --precise, and preview any update with --dry-run.

cargo update
cargo update itoa --precise 1.0.0

Download without building

fetch downloads every library in Cargo.lock and builds nothing โ€” the standard trick before working offline.

cargo fetch

See the shape of your dependencies

tree prints who depends on whom. The -e features form shows which features are switched on. -i works backwards from one library to whoever pulled it in.

cargo tree
cargo tree -e features
cargo tree -i greet

Spot a library that arrives twice

Two versions of one library can live in one project. One is an old one you asked for. The other is a new one a library needed. The -d flag lists only the repeats. In a test project it listed itoa twice โ€” 0.4.8 asked for directly, and 1.0.18 pulled in by serde_json:

cargo tree -d

Hunt dependencies you never use

cargo machete is a plug-in tool, not a built-in. It reads your code and names the crates in Cargo.toml that nothing uses. One install adds it:

// in your terminal:
// $ cargo install cargo-machete
// $ cargo machete

Used by a macro still counts as used

In that same test project, serde stayed off the list. The code touched serde only through its derive macro. That touch was enough. Machete reads real use, not just plain function calls:

#[derive(serde::Serialize)]
struct Card {
    name: String,
}

Preview a publish, erase a build

package --list shows exactly which files a publish would upload, including the generated Cargo.toml.orig. clean deletes the whole target folder. The next build starts from nothing.

cargo package --list
cargo clean

Example

fn main() {
    println!("cargo search itoa   -> find crates on crates.io");
    println!("cargo add itoa      -> write it into Cargo.toml");
    println!("cargo update        -> refresh Cargo.lock");
    println!("cargo clean         -> delete the target folder");
}

Key points

  • A command is one instruction to Cargo: the word after cargo names the job.
  • The flags keep the same meaning on nearly every command here: --release, --features and -p.
  • The flags match their meaning on cargo build.
  • Duplicate versions are legal.
  • Each crate keeps the version it asked for.
  • Use cargo tree -d to find the repeats.
  • cargo machete can flag a crate that only a build script or another crate's macros need.
  • Its own report prints the remedy: an ignored list under package.metadata.cargo-machete in Cargo.toml tells it to leave that crate alone.
  • Any program in your PATH called cargo-thing can be run as cargo thing, which is how the family grows.

In this example, the program is just a pocket cheat-sheet: four println! lines, one per command. The first line is how you find a crate before adding it. The second writes the crate into Cargo.toml for you. The third refreshes the lockfile when newer versions appear inside the ranges you allowed. The fourth throws the whole target folder away.

Note

Many Cargo commands are separate programs plugged into Cargo โ€” fmt, clippy and doc among them.

Try it Yourself

Edit the code, then press Run.

Running is simulated ยท Rust Playground

Exercise

Cargo.lock pins a library at an older patch release, and your Cargo.toml range allows a newer one. Which command moves the lockfile forward?