The single-file trap
You write a Rust file. You run rustc main.rs. It compiles. You feel productive. Then you decide to parse some JSON. You download a JSON library, figure out the version, compile it, and link it to your binary. You do this for three more crates. Now you have a folder of source code, a tangle of version constraints, and a build command that takes forty seconds to type. You realize managing dependencies by hand is a trap. Cargo exists to break you out of that trap.
Cargo is the standardized workshop
Cargo is Rust's build system, package manager, and convention engine rolled into one. Think of it as a standardized workshop. In other languages, you might juggle a package manager for downloads, a build tool for compilation, a linter for style, and a test runner for checks. Each tool has its own config file and its own quirks. Cargo gives you one command that does all of them. It also enforces a directory structure so every Rust project looks the same. When you open a random Rust repo, you know exactly where the code lives, where the tests are, and how to build it. No hunting for Makefile or package.json.
Trust the convention. If your project looks like every other Rust project, you're doing it right.
Your first build
Cargo creates a project skeleton with a single command. The structure includes a src/ directory for code, a Cargo.toml manifest for configuration, and a .gitignore that excludes build artifacts.
# Create a new project with standard structure
cargo new hello-cargo
cd hello-cargo
# Build and run in one step
cargo run
The src/main.rs file contains a minimal program. Cargo compiles it and executes the result.
fn main() {
// Print a message to stdout
println!("Hello from Cargo!");
}
Run cargo run again. The output appears instantly. Cargo cached the build. It checks timestamps and skips compilation when nothing changed. This makes the edit-run loop fast.
What happens when you run cargo
When you invoke cargo run, Cargo reads Cargo.toml. This file lists your project metadata and dependencies. Cargo checks if any source files changed. If nothing changed, it skips compilation and runs the binary immediately. If you edited a file, Cargo recompiles only what's necessary. It stores all build artifacts in a target/ directory. This keeps your source tree clean. You never see object files or compiled binaries cluttering your project folder.
Cargo also generates a Cargo.lock file. This file records the exact versions of every dependency, including transitive dependencies. If your code depends on serde, and serde depends on serde_derive, the lock file pins both versions. This ensures reproducible builds. Every developer and every CI server gets the exact same dependency graph.
Convention aside: Applications commit Cargo.lock to version control. Libraries do not. Applications need reproducible builds. Libraries need flexibility so downstream users can resolve conflicts. Cargo handles this distinction automatically when you run cargo new --lib.
Treat Cargo.lock as the source of truth for your build. Commit it for applications.
Adding dependencies the right way
Real projects need external crates. Cargo fetches them from crates.io. You declare dependencies in Cargo.toml. Cargo resolves versions, downloads sources, compiles crates, and links them to your binary.
[package]
name = "json-example"
version = "0.1.0"
edition = "2021"
[dependencies]
# Serde handles serialization
# The derive feature enables macros
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
The code uses the dependency. Cargo makes the crate available in your namespace.
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize)]
struct Config {
name: String,
port: u16,
}
fn main() {
let config = Config {
name: String::from("my-app"),
port: 8080,
};
// Serialize to JSON string
let json = serde_json::to_string(&config).unwrap();
println!("{}", json);
}
Some crates split functionality behind feature flags. serde is a large crate. The base version provides traits. The derive feature adds macros that generate boilerplate code. If you omit the feature, the macros don't exist. Cargo allows you to enable only what you need. This keeps compile times down and binary size small.
Convention aside: Use cargo add serde --features derive instead of editing Cargo.toml by hand. The cargo add command updates the manifest, fetches the crate, and checks for conflicts in one step. It's the modern way to manage dependencies.
Don't guess version numbers. Let Cargo resolve the graph.
Common pitfalls
New Rust developers often hit a wall when they import a crate but forget to add it to Cargo.toml. The compiler rejects the code with E0432 (use of undeclared crate or module). The fix is always the same: check your manifest. The compiler cannot see crates that aren't declared.
Another trap is using rustc directly on a project that uses Cargo. rustc doesn't know about Cargo.toml. It doesn't fetch dependencies. It doesn't understand the project structure. If you run rustc src/main.rs on a project with dependencies, you get a flood of errors. Stick to cargo build or cargo run. Cargo invokes rustc with the correct flags and dependency paths.
Feature flags cause subtle errors. If you add serde but don't enable derive, the #[derive(Serialize)] macro won't exist. The compiler rejects the code with E0277 (trait bound not satisfied) because the trait isn't in scope. Always check the crate documentation for required features.
If the compiler can't find the crate, check the manifest before checking the code.
When to use Cargo
Use Cargo for any project that has dependencies, multiple files, or tests. It is the standard toolchain. It handles builds, tests, documentation, and publishing.
Use rustc directly only when you are learning how the compiler works, writing a single-file experiment with no external crates, or debugging a build issue that Cargo obscures.
Use cargo test to run your test suite. It discovers tests automatically and runs them in parallel.
Use cargo doc to generate documentation. It links between crates and produces a browsable HTML site.
Reach for Cargo. If you aren't using Cargo, you're fighting the ecosystem.