23.2 Cargo Command-Line Interface

Rust’s Cargo tool is typically used from the command line. You can check your Cargo version and view available commands with:

cargo --version
cargo --help

Cargo’s most commonly used commands handle tasks like creating projects, adding dependencies, and building or running your code. Below is a summary of several important ones.

23.2.1 cargo new and cargo init

  • cargo new: Creates a new project directory with a standard structure.
  • cargo init: Initializes an existing directory as a Cargo project.

Use the --lib flag to create a library project instead of a binary application:

# Create a new binary (application) project
cargo new hello_cargo

# Create a new library project
cargo new my_library --lib

# Initialize the current directory as a Cargo project
cargo init

23.2.2 cargo build and cargo run

  • cargo build: Compiles the project in debug mode by default (favoring fast compilation over runtime performance).
  • cargo run: Builds the binary (in debug mode by default) and then runs it.
# Build in debug mode (default)
cargo build

# Build and run the binary in debug mode
cargo run

In debug mode, artifacts go into target/debug. Incremental compilation is enabled, so only the files you modify (and their dependents) are recompiled.

Release Mode

Use release mode for performance-critical builds. It enables more aggressive optimizations:

# Compile with release optimizations
cargo build --release

# Build and run in release mode
cargo run --release

# Execute the release binary manually
./target/release/my_application

Release builds reside in target/release, separate from the debug artifacts in target/debug. In release mode, incremental compilation is disabled by default to allow more thorough optimizations.

23.2.3 cargo clean

Use cargo clean to remove the target directory and all compiled artifacts. This is helpful if you need a completely fresh build or want to free up disk space by removing old build outputs.

23.2.4 cargo add (and cargo remove)

The cargo add command simplifies adding dependencies to your Cargo.toml:

cargo add serde

You can specify version constraints or development dependencies:

cargo add serde --dev --version 1.0

Remove an unneeded dependency with:

cargo remove serde

Note: Prior to Rust 1.62, cargo add and cargo remove were part of an external tool called cargo-edit. If you’re using an older version of Rust, install cargo-edit instead.

23.2.5 cargo fmt

cargo fmt formats your code using rustfmt:

cargo fmt

This enforces a consistent community style. It’s good practice to run cargo fmt regularly to avoid stylistic merge conflicts and keep the code uniform.

23.2.6 cargo clippy

cargo clippy runs Clippy, Rust’s official linter:

cargo clippy

Clippy catches common coding mistakes, inefficiencies, or unsafe patterns. It suggests improvements to make your code more idiomatic and robust.

23.2.7 cargo fix

cargo fix automatically applies suggestions from the Rust compiler to resolve warnings:

cargo fix

You can add --allow-dirty to allow fixing even if your working directory has uncommitted changes, but always review the modifications before committing.

23.2.8 cargo miri

cargo miri runs Miri, an interpreter that can detect undefined behavior in Rust (e.g., out-of-bounds memory access):

cargo miri

Miri is especially valuable for debugging unsafe code. It may require installation:

rustup component add miri

23.2.9 Scope of Cargo Commands

  • cargo clean: Removes target/ and all compiled artifacts, including those of dependencies (but not the downloaded source).

  • cargo fmt, cargo clippy, cargo fix: Operate on your project by default. You can narrow their scope to individual files if needed:

    cargo fmt -- <file-path>

23.2.10 Other Commands

Cargo supports additional commands (e.g., cargo package, cargo login). Refer to the Cargo documentation for a complete list.

23.2.11 The External Cargo-edit Tool

You can still install the cargo-edit tool for extended commands (e.g., cargo upgrade or cargo set-version):

cargo install cargo-edit

This plugin broadens Cargo’s subcommands for tasks like updating all dependencies at once.