Cargo Projects and Commands

Every Rust project is a crate, and cargo is the only sane way to make one. Run cargo new hello and you get a directory containing exactly what a minimal crate needs:

hello/
├── Cargo.toml      manifest: package metadata + dependencies
├── .gitignore      ignores /target
└── src/
    └── main.rs     fn main() { println!("Hello, world!"); }

cargo new --lib hello swaps main.rs for lib.rs and generates a src/lib.rs with a unit-test module. That binary-versus-library choice is the crate's kind: a binary crate produces an executable with an entry point, a library crate produces a .rlib that other crates can use. Real projects almost always start as a library with a thin binary attached, because code you want to test must live in the library target.

The manifest is small but every field does work:

[package]
name = "orders"          # crate name; lib crates conventionally use underscores
version = "0.1.0"        # your crate's version, semver-interpreted
edition = "2021"         # language/idiom version: 2015, 2018, 2021, 2024
rust-version = "1.78"    # minimum supported compiler (MSRV)

[dependencies]
serde = { version = "1", features = ["derive"] }

The edition field deserves attention because it changes how your code compiles without changing the compiler: edition 2018 introduced the extern crate-less module system and uniform paths, 2021 added disjoint crate captures for closures and IntoIterator for arrays, 2024 tightens lifetime-capture and unsafe rules. Editions never break old code silently — the compiler migrates you with cargo fix --edition.

A crate with multiple executables puts each in its own file under src/bin/:

src/
├── lib.rs        the library target: pub fn parse(...)
├── main.rs       binary "orders": calls orders::parse
└── bin/
    └── importer.rs   binary "importer": a second executable in one crate

This layout is the standard interview answer to "how do you ship a CLI and a server from one package?" — one package, one library, N binaries. Modules inside a target are declared with mod, and files like src/parse.rs join the tree as mod parse;; the module system is genuinely covered in a later topic, so the rule to hold now is: lib.rs/main.rs are crate roots, everything else hangs off a mod declaration.

Finally, cargo new initializes a git repository and a .gitignore with /target in one step. Committing target/ is a classic beginner mistake — it holds hundreds of megabytes of regenerable build artifacts.

Two related commands trip people up: cargo init creates a manifest in a directory that already exists, while cargo new refuses if the target directory is non-empty and scaffolds it fresh. Both default to a git repo; --vcs none disables that for directories already under version control.

Names follow rules you only meet when they are enforced. A package name may contain letters, digits, -, and _, must start with a letter, and hyphens become underscores when you import the crate: a package named orders-api is written use orders_api::parse; because cargo passes --crate-name orders_api to rustc. That is why library packages conventionally use underscores — the name you publish and the name you use then agree.

Sizing the manifest up a notch, three fields change what cargo builds:

[package]
name = "orders-api"
default-run = "orders"      # which binary `cargo run` picks
autobins = false            # stop auto-discovering src/bin/*

[lib]
name = "orders_core"        # rename the library target only
path = "src/core/lib.rs"    # move its root off the default

default-run is the practical one when a package ships src/main.rs plus src/bin/importer.rs: plain cargo run would otherwise fail and demand --bin. Renaming the lib target changes only the artifact name — the package name in Cargo.toml still identifies the dependency to everyone else.

The interview framing for this whole section is "how do you lay out a crate so it stays testable?" The answer in one line: put the logic in the library target and keep binaries as thin dispatchers, because tests/ integration crates and doc tests can only reach library code, never fn main.

Cargo's build commands differ in how much work they do, and knowing which to reach for is the difference between a five-second and a five-minute feedback loop.

cargo check is the command you run constantly while editing: it skips LLVM code generation entirely, which is roughly 60–70% of compile time, and still produces every error you care about — type errors, borrow-checker errors, trait resolution. The trade is that it cannot produce a runnable binary, so cargo run does the full debug build before executing.

Debug versus release is not a minor flag — it changes program behavior:

[profile.dev]
opt-level = 0        # fast compiles, slow runs; assertions ON
overflow-checks = true

[profile.release]
opt-level = 3        # slow compiles, fast runs; assertions OFF
lto = "thin"         # link-time optimization across crates
codegen-units = 16
strip = true

Integer overflow panics in debug builds and wraps in release builds (you will meet this precisely in Primitive Types and Overflow), and debug_assert! runs only in dev. A benchmark run against a debug binary measures nothing real; a bug that "only happens in production" is often a debug assertion that release compiled away. cargo run --release exists for exactly this reason.

Incremental compilation is on by default in dev: cargo fingerprints every crate and recompiles only what changed, keeping per-crate artifacts in target/debug/incremental/. Two habits defeat it needlessly — cargo clean on every hiccup (cargo rebuilds fine without it) and editing files cargo cannot see (generated sources must be declared cargo:rerun-if-changed in build.rs). Build scripts are a crate's build.rs that runs before compilation and can emit linker flags, generate code, and probe the system — you will meet them when C interop arrives.

For a workspace of many crates, every command takes -p <crate> to target one package and --workspace to run across all. cargo run --bin importer disambiguates which executable when a crate ships several. These flags, plus --release and --target, cover most real invocations; anything else is one cargo help away.

Two more dials on the build loop are worth having. cargo build --timings writes an HTML report showing exactly which crates dominate your compile time — the fastest way to discover that one dependency is 40% of your wall clock. And when a heavy dependency makes debug runs crawl, you can optimize it without slowing your own edit-compile cycle:

[profile.dev.package.regex]
opt-level = 3      # slow dependency builds fast, your crate still compiles at 0

The same mechanism in reverse explains a common production surprise: code that takes 5 ms in debug takes 0.5 ms in release, so any timing claim about your program is meaningless until you name the profile it ran under.

Passing arguments and isolating builds are daily needs:

cargo run --bin importer -- --input data.csv   # everything after -- goes to your program
CARGO_TARGET_DIR=/scratch/target cargo build   # move the artifact tree (shared CI caches)
cargo build --offline                          # fail instead of touching the network

That last one matters on CI and planes: a clean checkout with a populated cache builds fully offline, proving the lock file and vendored sources are sufficient — reproducibility you can test with a flag. Finally, cargo fix applies the compiler's own suggested edits (including edition migrations) so mechanical repairs land as a diff you review rather than keystrokes you retype.

cargo test is not one test runner — it compiles your crate plus every test target and executes them through a generated harness. Three kinds of tests exist, and each lives in a different place.

Unit tests sit inside the module they test, gated by #[cfg(test)] so they compile only under the test harness:

// src/lib.rs
pub fn add(left: u64, right: u64) -> u64 { left + right }

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn adds_two_numbers() {
        assert_eq!(add(2, 2), 4);
    }
}

Integration tests live as separate crates under tests/, compiled against your library's public API — they cannot reach private items, which is precisely the point:

tests/
└── api.rs    use orders::parse;  // only the pub surface

Doc tests are the third kind and unique to Rust: every fenced rust block in a /// doc comment is compiled and run by cargo test:

/// Adds two numbers.
///
/// ```
/// let sum = orders::add(2, 2);
/// assert_eq!(sum, 4);
/// ```
pub fn add(left: u64, right: u64) -> u64 { left + right }

That makes documentation executable — an example that stops compiling fails CI. Each test runs as a thread inside a harness binary, and one #[test] panicking marks only that test failed; the harness catches the panic and keeps going. Two practical controls: cargo test add_two filters by substring name, and cargo test -- --test-threads=1 serializes execution for tests that share a resource. Mark resource-heavy tests #[ignore] and opt them in with cargo test -- --ignored.

Dependencies round out the workflow. cargo add serde --features derive edits Cargo.toml for you, then cargo build downloads crates into ~/.cargo/registry and compiles them into target/debug/deps. The version requirement "1.2" means >=1.2.0, <2.0.0 — caret semantics — so compatible patch and minor updates flow in on the next cargo update. Cargo.lock is committed for applications: it pins the exact resolved versions so every machine and CI builds the same graph. Libraries publish their Cargo.toml requirements; consumers' lock files decide what those resolve to.

Assertions are not the only contract a test can state. A test may return Result so ? works directly, and failure of the returned Err fails the test:

#[test]
fn parses_order() -> Result<(), ParseError> {
    let order = orders::parse("A-100,3")?;
    assert_eq!(order.qty, 3);
    Ok(())
}

#[test]
#[should_panic(expected = "index out of bounds")]
fn rejects_empty_input() {
    orders::parse("");
}

Doc tests get escape hatches for examples that are illustrative but not runnable: ```rust,ignore compiles nothing, ```rust,no_run compiles without executing — the right choice for a snippet that opens a network port — and ```text opts out entirely.

Dependency inspection has one command worth memorizing: cargo tree prints the resolved graph with duplicates collapsed, -e features shows which feature flags pulled a crate in, and -i serde inverts the tree to answer "who depends on this?" When two versions of one crate appear, cargo tree -d names them and tells you which requirement blocked unification. Repairing the graph is equally direct: cargo update -p serde --precise 1.0.199 re-resolves a single crate to an exact version while leaving the rest of the lock file untouched — the rollback you want when a point release breaks the build.

Test-only dependencies belong in [dev-dependencies]: criterion for benchmarks and tempfile for scratch directories land there, are compiled for cargo test and cargo bench, and are never compiled into the artifact you ship.