4.2 Introduction to Cargo

Instead of calling rustc on each file, most Rust developers rely on Cargo, Rust’s package manager and build tool. Cargo simplifies project-related tasks such as:

  • Compiling your code (including incremental builds)
  • Managing dependencies
  • Running tests
  • Building for different configurations (debug, release, etc.)

Thanks to Cargo, you rarely need to invoke rustc directly.

4.2.1 Creating a New Project with Cargo

To create a new Rust project, run:

cargo new my_project

This command creates a my_project directory with the following structure:

my_project
├── Cargo.toml
└── src
    └── main.rs
  • Cargo.toml: A manifest file containing metadata (such as the project name and version) and specifying dependencies.
  • src/main.rs: Your main source file, pre-populated with a simple ‘Hello, world!’ so you can start coding right away.

Tip: To create a library instead of an executable, use cargo new --lib my_library.

4.2.2 Compiling and Running a Program with Cargo

Once your project is set up, you can build it:

cargo build

This compiles your project and places the resulting binary in the target/debug directory by default. For an optimized release build, use:

cargo build --release

You can also compile and run your program in one step:

cargo run

To produce an optimized binary at the same time, simply append the --release flag:

cargo run --release

These commands simplify your workflow by automatically handling both compilation and execution. Note that during development, you typically use debug builds (without the --release flag) for faster compile times and executables that include full debugging functionality (for example, debug_assertions and overflow checks).

4.2.3 Managing Dependencies

One of Cargo’s most important features is its ability to manage project dependencies. You specify dependencies in your Cargo.toml file. For instance, to add the popular rand crate for generating random numbers:

[dependencies]
rand = "0.9"

When you run cargo build, Cargo automatically downloads and compiles the rand crate, along with any transitive dependencies. You can also add dependencies using the command line:

cargo add rand

This updates your Cargo.toml for you.

4.2.4 Other Useful Cargo Commands

Cargo offers several other commands to streamline your development process:

  • cargo check: Quickly checks your code for errors without producing a binary.

    cargo check

  • cargo test: Compiles and runs tests located in your project. This is useful for verifying functionality and preventing regressions:

    cargo test

  • cargo doc: Generates documentation for your project and any dependencies (based on documentation comments). You can view the docs locally in your browser:

    cargo doc --open

  • cargo fmt: Uses Rust’s official code formatter (rustfmt) to automatically format your code according to Rust style guidelines:

    cargo fmt

    Note: If this command is unavailable, install the rustfmt component via Rustup.

  • cargo clippy: Runs the Clippy linter on your code, providing helpful warnings and suggestions to improve correctness and style:

    cargo clippy

    Note: If Clippy is not installed, install the clippy component via Rustup.

These commands help you keep your codebase correct, consistent, and well-tested as it grows.

4.2.5 The Role of Cargo.toml

Every Cargo project has a Cargo.toml file that defines:

  • [package]: Metadata such as the project name, version, and authors.
  • [dependencies]: External crates needed by your project.
  • [dev-dependencies]: Dependencies required only for testing or other development tasks.
  • [build-dependencies]: Dependencies needed for custom build scripts.

Cargo uses these sections to manage and build your code efficiently, ensuring the correct versions of dependencies are fetched and compiled.

Note: When using an IDE or a specialized text editor, some Cargo commands may be executed automatically. For instance, certain editors can reformat code or check for syntax errors before saving the source file.