17.1 Packages: The Top-Level Concept

A package is Cargo’s highest-level abstraction for building, testing, and distributing code. Each package must contain at least one crate, though larger packages can include multiple crates.

17.1.1 Creating a New Package

Cargo initializes new Rust projects, setting up the directory structure and a Cargo.toml manifest. You can choose to create either a binary or library package:

# Creates a new binary package
cargo new my_package

# Creates a new library package
cargo new my_rust_lib --lib

For a binary package named my_package, Cargo generates:

my_package/
├── Cargo.toml
└── src
    └── main.rs

For a library package (--lib), Cargo populates:

my_rust_lib/
├── Cargo.toml
└── src
    └── lib.rs

17.1.2 Anatomy of a Package

A typical package structure includes:

  • Cargo.toml: Declares package metadata (name, version, authors) and dependencies.
  • src/: Contains the crate root (main.rs for binaries or lib.rs for libraries) and any additional module files.
  • Cargo.lock: Auto-generated by Cargo to fix exact dependency versions for reproducible builds.
  • Optional Directories: For instance, tests/ for integration tests or examples/ for additional executable examples.

When you run cargo build, Cargo outputs compiled artifacts to a target/ directory (with subfolders like debug and release).

17.1.3 Workspaces: Managing Multiple Packages Together

For more complex projects, you can group multiple packages (and thus multiple crates) into a workspace. A workspace shares a top-level Cargo.toml that lists the member packages:

my_workspace/
├── Cargo.toml
├── package_a/
│   ├── Cargo.toml
│   └── src/
│       └── lib.rs
└── package_b/
    ├── Cargo.toml
    └── src/
        └── main.rs

A simplified root Cargo.toml might be:

[workspace]
members = ["package_a", "package_b"]

All packages in the workspace share a single Cargo.lock and a single target/ directory, ensuring consistent dependencies and faster builds due to shared artifacts.

17.1.4 Multiple Binaries in One Package

A single package can build several executables by placing additional .rs files in src/bin/. Each file in src/bin/ is compiled as its own binary:

my_package/
├── Cargo.toml
└── src/
    ├── main.rs         // Primary binary
    └── bin/
        ├── tool.rs     // Secondary binary
        └── helper.rs   // Tertiary binary

To work with multiple binaries:

  • Build all binaries: 
    cargo build --bins
  • Run a specific binary: 
    cargo run --bin tool

17.1.5 Packages vs. Crates

  • A crate is a single compilation unit, producing a library or an executable.
  • A package contains one or more crates, defined by a Cargo.toml.

You can have:

  • Exactly one library crate in a package (or none, for a purely binary package).
  • Any number of binary crates, each resulting in its own executable.

For small projects with only one crate, the difference between “package” and “crate” may seem subtle. However, once you begin managing multiple executables or libraries, understanding how packages and crates map to your folder structure and Cargo.toml dependencies becomes crucial.