Rust — Crates

What a crate is

A crate is the smallest unit of code Rust compiles at once. Every cargo build produces at least one:

• Binary crate — compiles to an executable; requires a fn main()
• Library crate — compiles to a reusable .rlib; no main, meant for import

A package can contain both: logic lives in the lib crate, a thin interface in the bin crate.

Crate roots

Compilation starts from these fixed filenames:

src/main.rs   ← binary crate root
src/lib.rs    ← library crate root

Every mod declaration chains outward from them. In code, the crate's name comes from Cargo.toml with hyphens as underscores (my-tool → my_tool).

std is implicit

let v = vec![1, 2];                 // std::vec!
use std::collections::HashMap;

The standard library links into every crate automatically. Only external crates need declaring in Cargo.toml.

Ecosystem crates worth knowing

Crate	Purpose
serde + serde_json	serialize/deserialize anything
tokio	async runtime
clap	CLI argument parsing
rand	randomness
reqwest	HTTP client
axum / actix-web	web servers
anyhow / thiserror	ergonomic errors

[dependencies]
clap = { version = "4", features = ["derive"] }

Importing another crate's items

use rand::Rng;                     // trait MUST be in scope for its methods!

fn main() {
    let n = rand::thread_rng().gen_range(1..=6);
    println!("dice: {}", n);
}

That use rand::Rng line trips everyone exactly once — traits must be imported before their methods become visible.

Publishing your own crate

$ cargo login <api-token>          # token from your crates.io account
$ cargo publish                    # builds, verifies, uploads

Rules to know: names must be unique on crates.io · versions are permanent (yank hides but never deletes) · every re-publish needs a semver bump.

Semantic versioning ranges

rand = "0.8"         # means >=0.8.0, <0.9.0 (caret implied)
serde = "=1.0.203"   # exact pin

Cargo.lock records exact resolved versions for reproducible builds; cargo update refreshes within allowed ranges.

Docs & metadata polish

[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
description = "One-line summary shown on crates.io"
license = "MIT OR Apache-2.0"
repository = "https://github.com/you/my-crate"

docs.rs auto-builds documentation for every published release — keep those /// doc comments healthy.

Mini Practice

1. Add clap with derive; parse a --name flag into a greeting.
2. Open any crate's docs.rs page; find one example to run.
3. Split a project into lib.rs (logic) + main.rs (CLI); import across.
4. Run cargo publish --dry-run to rehearse without uploading.
5. Inspect Cargo.lock after adding a dependency; count transitive crates.

Rust track fully complete. 🦀