Cargo Basics

Beginner ~20 min read

Cargo is Rust's build system and package manager. It handles building your code, downloading dependencies, and building those dependencies. In this lesson, you'll learn how to create projects with Cargo, understand project structure, and use essential Cargo commands.

What is Cargo?

Cargo is the official Rust build tool that comes installed with Rust. It provides:

Cargo Features:

Project Management: Create and organize Rust projects
Build System: Compile your code and dependencies
Package Manager: Download and manage external libraries (crates)
Testing: Run tests with cargo test
Documentation: Generate docs with cargo doc

While you can use rustc directly for simple programs, Cargo is the standard tool for Rust development.

Creating a New Project

Create a new Rust project with cargo new:

cargo new hello_cargo
cd hello_cargo

This creates a new directory with the following structure:

hello_cargo/
├── Cargo.toml          # Project configuration
└── src/
    └── main.rs         # Your code

Naming Convention: Rust uses snake_case for project names (e.g., hello_cargo, not HelloCargo).

Understanding Project Structure

Cargo.toml

The Cargo.toml file contains project metadata and dependencies:

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

[dependencies]
# External crates go here

TOML Format:

[package] - Project metadata section
name - Project name
version - Semantic version (major.minor.patch)
edition - Rust edition (2015, 2018, 2021)
[dependencies] - External libraries

src/main.rs

Cargo automatically creates a "Hello, World!" program in src/main.rs:

fn main() {
    println!("Hello, world!");
}

Essential Cargo Commands

cargo build

Compile your project:

cargo build

This creates an executable in target/debug/hello_cargo (or target/debug/hello_cargo.exe on Windows).

Release Build: For optimized production builds, use cargo build --release. This creates a faster executable in target/release/.

cargo run

Compile and run your project in one command:

cargo run

Output:

   Compiling hello_cargo v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 0.50s
     Running `target/debug/hello_cargo`
Hello, world!

Best Practice: Use cargo run during development—it's faster than building and running separately.

cargo check

Check if your code compiles without creating an executable:

cargo check

This is much faster than cargo build and useful for quick error checking during development.

cargo clean

Remove the target directory to free up space:

cargo clean

Cargo vs rustc

Task	With rustc	With Cargo
Create project	Manual setup	`cargo new project_name`
Compile	`rustc main.rs`	`cargo build`
Run	`./main`	`cargo run`
Dependencies	Manual management	Automatic via Cargo.toml

Adding Dependencies

To use external libraries (called "crates" in Rust), add them to Cargo.toml:

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

Cargo will automatically download and compile these dependencies when you build your project.

Finding Crates: Browse available crates at crates.io, the official Rust package registry.

Common Mistakes

1. Running rustc instead of cargo

Problem: Using rustc main.rs in a Cargo project

Solution: Always use cargo build or cargo run in Cargo projects

2. Forgetting to rebuild after changes

Problem: Running old executable after code changes

Solution: Use cargo run which automatically rebuilds if needed

3. Incorrect dependency syntax

Wrong:

[dependencies]
rand: "0.8.5"  # Wrong: uses colon instead of equals

Correct:

[dependencies]
rand = "0.8.5"  # Correct: uses equals sign

Summary

Cargo is Rust's build system and package manager
Create projects with cargo new project_name
Cargo.toml contains project configuration and dependencies
cargo build compiles your project
cargo run compiles and runs in one command
cargo check quickly checks for compilation errors
Add dependencies in the [dependencies] section of Cargo.toml
Use --release flag for optimized production builds

What's Next?

Congratulations! You've completed the Getting Started module. You now know how to install Rust, write basic programs, and use Cargo to manage projects. In the next module, we'll dive into Rust's type system, starting with variables, mutability, and data types—the building blocks of every Rust program.

Previous Hello World

Next Variables & Mutability