Understanding Cargo.toml

Cargo.toml is your project's ID card, listing its name, version, and everything else it depends on.

In this page:

The Package Section
The Dependencies Section
Cargo.toml vs Cargo.lock
Rust Editions

The Package Section

The [package] section of Cargo.toml records your project's name, version, and the Rust edition it targets, forming the core identity of the crate.

Example: The Package Section

bash

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"

⚠️ Run this command in your terminal.

The Dependencies Section

The [dependencies] section lists external crates your project needs, along with version requirements that Cargo uses to resolve compatible versions.

Example: The Dependencies Section

bash

[dependencies]
serde = "1.0"
rand = "0.8"

⚠️ Run this command in your terminal.

Cargo.toml vs Cargo.lock

While you edit Cargo.toml by hand to declare what you depend on, Cargo automatically generates and maintains Cargo.lock, recording the exact versions actually resolved and used for a reproducible build.

Example: Cargo.toml vs Cargo.lock

markup

fn main() {
    println!("Cargo.toml: what you declare");
    println!("Cargo.lock: what was actually resolved and locked in");
}

Rust Editions

The edition field lets Cargo compile your code against a specific set of language rules (like 2015, 2018, or 2021), allowing the language to evolve while keeping older code compiling unchanged.

Example: Rust Editions

markup

fn main() {
    let editions = ["2015", "2018", "2021"];
    for e in editions.iter() {
        println!("Rust edition: {}", e);
    }
}

Common Mistakes

Editing the [dependencies] section with an incorrect version format, which causes cargo build to fail to resolve dependencies.
Confusing Cargo.toml (the manifest you edit by hand) with Cargo.lock (the exact resolved versions, usually auto-managed).
Forgetting to bump the version field before publishing an updated crate to crates.io.

Chapter Summary

Cargo.toml is the manifest file describing a project's metadata, edition, and dependencies.
The [package] section holds name, version, and edition; [dependencies] lists external crates.
Cargo.lock records exact resolved dependency versions and is usually committed for binaries, auto-generated by Cargo.
Editions (like 2021) let Rust evolve syntax/semantics over time without breaking older projects.

🔒

Chapter Quiz — Complete all 8 topics to unlock

0/8 topics done

Complete these topics first:

← Previous Lesson Introduction to Tokio Next Lesson → Using Crates from crates.io