Packages & Crates

A crate is the smallest amount of code that the Rust compiler considers at a time. A package is one or more crates that provide a set of functionality. Understanding packages and crates is essential for organizing your Rust code and managing dependencies with Cargo.

What is a Crate?

A crate is a compilation unit in Rust. There are two types of crates:

1. Binary Crate

A binary crate is a program you can compile to an executable that you can run. Every package has at most one binary crate, and it must be in src/main.rs.

// src/main.rs - Binary crate
fn main() {
    println!("Hello, world!");
}

2. Library Crate

A library crate doesn't have a main() function and doesn't compile to an executable. Instead, it defines functionality intended to be shared with multiple projects. Library crates are in src/lib.rs.

// src/lib.rs - Library crate
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

What is a Package?

A package is one or more crates that provide a set of functionality. A package contains a Cargo.toml file that describes how to build those crates.

Rules for packages:

• A package must contain at most one library crate
• A package can contain as many binary crates as you want
• A package must contain at least one crate (either library or binary)

Cargo.toml File

The Cargo.toml file defines your package:

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

[dependencies]
serde = "1.0"
serde_json = "1.0"

Click Run to execute your code

Managing Dependencies

Dependencies are external crates your package needs. They're specified in Cargo.toml:

Adding Dependencies

Add dependencies to the [dependencies] section:

[dependencies]
serde = "1.0"
serde_json = "1.0"
tokio = { version = "1.0", features = ["full"] }

Then run cargo build to download and compile dependencies.

Version Specifications

You can specify versions in different ways:

Dependency Sources

Dependencies can come from different sources:

1. From crates.io (Default)

[dependencies]
serde = "1.0"  # From crates.io

2. From Git Repository

[dependencies]
my_crate = { git = "https://github.com/user/repo", branch = "main" }

3. From Local Path

[dependencies]
my_crate = { path = "../my_crate" }

4. From Workspace

[dependencies]
my_crate = { workspace = true }

Click Run to execute your code

Features

Many crates support optional features that you can enable:

[dependencies]
tokio = { version = "1.0", features = ["full", "macros"] }
serde = { version = "1.0", features = ["derive"] }

Development Dependencies

Dependencies needed only for development (tests, benchmarks) go in [dev-dependencies]:

[dev-dependencies]
mockito = "1.0"
criterion = "0.5"

Using External Crates

Once you've added a dependency to Cargo.toml, you can use it in your code:

// In Cargo.toml:
// [dependencies]
// serde = "1.0"

// In your code:
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct User {
    name: String,
    age: u32,
}

Publishing to crates.io

To publish your crate to crates.io:

1. Create an account: Sign up at crates.io and get an API token
2. Add metadata: Ensure your Cargo.toml has required fields:

   [package]
   name = "my_crate"
   version = "0.1.0"
   edition = "2021"
   description = "A short description"
   license = "MIT OR Apache-2.0"
   repository = "https://github.com/user/repo"

3. Publish: Run cargo publish

Workspaces

A workspace is a set of packages that share a Cargo.lock and output directory:

# Cargo.toml at workspace root
[workspace]
members = [
    "crate1",
    "crate2",
    "crate3",
]

[workspace.dependencies]
shared_dep = "1.0"

When to Use Packages vs Crates

Best Practices

Common Mistakes

// Wrong - Missing edition
[package]
name = "my_project"
version = "0.1.0"

// Correct - Specify edition
[package]
name = "my_project"
version = "0.1.0"
edition = "2021"

// Wrong - Too permissive
[dependencies]
serde = "*"  // Can break with any update

// Correct - Specify compatible version
[dependencies]
serde = "1.0"  // Compatible with 1.x.x

// Wrong - Using crate without adding to Cargo.toml
use serde::Serialize;  // Error: can't find crate

// Correct - Add to Cargo.toml first
// [dependencies]
// serde = "1.0"
use serde::Serialize;  // OK

# Wrong - Dependencies not downloaded
# Added to Cargo.toml but didn't run cargo build

# Correct - Build to download dependencies
cargo build

Exercise: Packages & Crates Practice

Click Run to execute your code

# Cargo.toml
[package]
name = "calculator"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = "1.0"
serde_json = "1.0"

# Binary crate: src/main.rs (has main function)
# Library crate: src/lib.rs (no main function)
# Package: Contains Cargo.toml and one or more crates

# Dependency sources:
# 1. From crates.io: serde = "1.0"
# 2. From Git: my_crate = { git = "https://github.com/user/repo" }
# 3. From local: my_crate = { path = "../my_crate" }

Summary

What's Next?

Now that you understand packages and crates, you'll learn about iterators - one of Rust's most powerful features for processing collections. Iterators allow you to write efficient, functional-style code that's both readable and performant.