Cargo

Level 1 — Foundations Rust's build system and package manager; used to create, build, test, and manage projects.

1. Prerequisites

• Tokens — Basic syntactic units of Rust code and configurations.

2. Term Category

Rust Ecosystem Core (the unified package manager)

While the concept of a build system or package manager exists in other languages (npm, pip, Maven, Go modules), Cargo is Rust-specific in how it was designed from day one as an inseparable part of the Rust experience — not bolted on after the fact, but woven into the language's identity.

3. Explanation

(1) Design Motivation — "Why did we design this?"

Let me tell you a story about the early days.

Before Rust shipped 1.0, we looked around at the state of systems programming tooling and saw fragmentation everywhere. In C and C++, there was no standard build system — teams picked between Make, CMake, Autotools, Meson, Bazel, and a dozen others. And package management? Even worse. You'd manually download libraries, wrestle with include paths, fight linker errors, and pray that the version you grabbed was compatible with everything else. Every C++ project was a snowflake.

We knew that if Rust was going to succeed, it couldn't just be a better language. It needed to be a better experience. So we asked ourselves: what if there was one tool that handled everything — creating projects, resolving dependencies, compiling code, running tests, generating documentation, and publishing libraries? What if it just worked, out of the box, for every Rust project on the planet?

That's Cargo.

The trade-off was opinionation. Cargo enforces conventions — your source goes in src/, your tests go alongside your code or in tests/, your manifest is always Cargo.toml. Some developers initially bristled at this. But the payoff was enormous: any developer can clone any Rust project and run cargo build with confidence. No setup guide, no tribal knowledge, no "works on my machine."

We also studied what npm got right (easy dependency installation, a central registry) and what it got wrong (dependency hell, lack of lock files in early versions). Cargo shipped with Cargo.lock from the start — reproducible builds were non-negotiable.

(2) Reality Metaphor

Think of Cargo as a general contractor building a house.

You don't pour concrete, wire electricity, and plumb the pipes yourself. You tell the contractor what you want (the blueprint = Cargo.toml), and they:

• Source all the materials from suppliers (dependencies from crates.io)
• Coordinate the subcontractors (compile your code and all dependencies in the right order)
• Inspect the work (run tests)
• Hand you the keys to the finished house (produce the final binary)

Without a general contractor, you'd be calling individual suppliers, scheduling workers, and resolving conflicts between the electrician and the plumber. Cargo eliminates that chaos.

(3) Rust Code Examples

Short Snippet — Creating and running a project

# Create a new binary project
cargo new hello_cargo

# Move into the project directory
cd hello_cargo

# Build and run in one step
cargo run

Output:

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

Fuller Example — A real workflow with dependencies and tests

# Cargo.toml — the project manifest
[package]
name = "greeting_app"
version = "0.1.0"
edition = "2024"

[dependencies]
rand = "0.10"          # Adding an external dependency

// src/main.rs
use rand::Rng;

fn generate_greeting(name: &str) -> String {
    let greetings = ["Hello", "Hi", "Hey", "Greetings"];
    let mut rng = rand::rng();
    let index = rng.random_range(0..greetings.len()); // Pick a random greeting
    format!("{}, {}!", greetings[index], name)
}

fn main() {
    let greeting = generate_greeting("Rustacean");
    println!("{}", greeting);
}

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

    #[test]
    fn greeting_contains_name() {
        let result = generate_greeting("Alice");
        assert!(result.contains("Alice")); // The name should always appear
    }

    #[test]
    fn greeting_ends_with_exclamation() {
        let result = generate_greeting("Bob");
        assert!(result.ends_with('!'));
    }
}

# Common Cargo commands for this project:
cargo build          # Compile the project
cargo run            # Compile and run
cargo test           # Run all tests
cargo doc --open     # Generate and open documentation
cargo build --release  # Compile with optimizations for production

4. Common Mistakes & Pitfalls

Mistake 1: Forgetting to Commit Cargo.lock in Binary Applications

The mistake: Adding Cargo.lock to .gitignore when building an executable Rust binary project.

Why it's wrong: Binary applications rely on Cargo.lock to guarantee reproducible builds across developers and CI environments.

Incorrect:

# .gitignore
Cargo.lock // ❌ Breaks deterministic application builds!

Fix:

# .gitignore
# Keep Cargo.lock for binary projects to lock dependency trees

Mistake 2: Confusing cargo check with cargo build

The mistake: Running cargo build repeatedly during rapid development iterations.

Why it's wrong: cargo build produces full machine code binary artifacts, whereas cargo check skips code generation and only verifies types, running significantly faster.

Incorrect:

$ cargo build # ❌ Slower turnaround during quick editing loops

Fix:

$ cargo check # FAST syntax and borrow checker validation

Mistake 3: Specifying Wildcard Dependency Version Specifiers

The mistake: Writing serde = "*" inside Cargo.toml dependencies.

Why it's wrong: Wildcard versions pull breaking major updates unpredictably during compilation.

Incorrect:

# Cargo.toml
[dependencies]
serde = "*" // ❌ Unpredictable breaking changes

Fix:

# Cargo.toml
[dependencies]
serde = "1.0" // Semantic version range pin

5. Practice Exercises

Exercise 1: Workspace Dependency DAG Resolver & Topological Compilation Scheduler

Scenario: In large-scale enterprise monorepos, Cargo must parse dependency trees across multiple workspace crates to calculate parallel build schedules. If cyclic dependencies exist between workspace crates (e.g., Crate A depends on Crate B, and Crate B depends on Crate A), compilation would deadlock. Furthermore, Cargo must perform feature flag unification (combining all optional feature requirements requested by different dependent crates into a single feature matrix for shared dependencies).

Requirements: Implement a robust WorkspaceGraphResolver system that:

1. Stores workspace crate manifests (CargoManifest), including crate names (PackageId), dependency vectors, and default/optional features.
2. Detects dependency cycles using a tri-state Depth-First Search (DFS) algorithm (Unvisited, Visiting, Visited) and returns a WorkspaceError::Cycle with the exact cycle path sequence.
3. Resolves a valid topological compilation execution order where dependencies are built prior to dependent crates.
4. Performs feature flag unification across all workspace crates.

use std::collections::{BTreeSet, HashMap};

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PackageId(pub String);

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CargoManifest {
    pub name: PackageId,
    pub dependencies: Vec<PackageId>,
    pub default_features: Vec<String>,
    pub optional_features: HashMap<String, Vec<String>>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CycleError {
    DetectedCycle { path: Vec<PackageId> },
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum WorkspaceError {
    Cycle(CycleError),
    MissingDependency { package: PackageId, dependency: PackageId },
}

#[derive(Debug, Default)]
pub struct WorkspaceGraphResolver {
    manifests: HashMap<PackageId, CargoManifest>,
}

impl WorkspaceGraphResolver {
    pub fn new() -> Self {
        Self {
            manifests: HashMap::new(),
        }
    }

    pub fn add_package(&mut self, manifest: CargoManifest) {
        self.manifests.insert(manifest.name.clone(), manifest);
    }

    pub fn resolve_compilation_order(&self) -> Result<Vec<PackageId>, WorkspaceError> {
        // Validate that all declared dependencies exist in the workspace graph
        for (pkg_id, manifest) in &self.manifests {
            for dep in &manifest.dependencies {
                if !self.manifests.contains_key(dep) {
                    return Err(WorkspaceError::MissingDependency {
                        package: pkg_id.clone(),
                        dependency: dep.clone(),
                    });
                }
            }
        }

        #[derive(Clone, Copy, PartialEq, Eq)]
        enum NodeState {
            Unvisited,
            Visiting,
            Visited,
        }

        let mut states: HashMap<PackageId, NodeState> = self
            .manifests
            .keys()
            .map(|k| (k.clone(), NodeState::Unvisited))
            .collect();

        let mut order = Vec::new();
        let mut path_stack = Vec::new();

        let mut sorted_keys: Vec<&PackageId> = self.manifests.keys().collect();
        sorted_keys.sort();

        for pkg_id in sorted_keys {
            if states.get(pkg_id) == Some(&NodeState::Unvisited) {
                self.dfs_visit(pkg_id, &mut states, &mut order, &mut path_stack)?;
            }
        }

        Ok(order)
    }

    fn dfs_visit(
        &self,
        node: &PackageId,
        states: &mut HashMap<PackageId, NodeState>,
        order: &mut Vec<PackageId>,
        path_stack: &mut Vec<PackageId>,
    ) -> Result<(), WorkspaceError> {
        states.insert(node.clone(), NodeState::Visiting);
        path_stack.push(node.clone());

        if let Some(manifest) = self.manifests.get(node) {
            let mut deps = manifest.dependencies.clone();
            deps.sort();

            for dep in deps {
                match states.get(&dep) {
                    Some(NodeState::Visiting) => {
                        let mut cycle_path = Vec::new();
                        if let Some(start_idx) = path_stack.iter().position(|p| p == &dep) {
                            cycle_path.extend_from_slice(&path_stack[start_idx..]);
                        }
                        cycle_path.push(dep.clone());
                        return Err(WorkspaceError::Cycle(CycleError::DetectedCycle {
                            path: cycle_path,
                        }));
                    }
                    Some(NodeState::Unvisited) => {
                        self.dfs_visit(&dep, states, order, path_stack)?;
                    }
                    _ => {}
                }
            }
        }

        path_stack.pop();
        states.insert(node.clone(), NodeState::Visited);
        order.push(node.clone());
        Ok(())
    }

    pub fn unify_features(
        &self,
        requested_features: &HashMap<PackageId, Vec<String>>,
    ) -> HashMap<PackageId, BTreeSet<String>> {
        let mut unified: HashMap<PackageId, BTreeSet<String>> = HashMap::new();

        for (pkg_id, manifest) in &self.manifests {
            let mut feature_set = BTreeSet::new();
            for f in &manifest.default_features {
                feature_set.insert(f.clone());
            }
            if let Some(reqs) = requested_features.get(pkg_id) {
                for f in reqs {
                    feature_set.insert(f.clone());
                }
            }
            unified.insert(pkg_id.clone(), feature_set);
        }

        unified
    }
}

fn main() {
    let mut resolver = WorkspaceGraphResolver::new();
    resolver.add_package(CargoManifest {
        name: PackageId("core_sys".to_string()),
        dependencies: vec![],
        default_features: vec!["alloc".to_string()],
        optional_features: HashMap::new(),
    });
    resolver.add_package(CargoManifest {
        name: PackageId("net_app".to_string()),
        dependencies: vec![PackageId("core_sys".to_string())],
        default_features: vec![],
        optional_features: HashMap::new(),
    });

    let order = resolver.resolve_compilation_order().unwrap();
    println!("Compilation order: {:?}", order);
}

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

    #[test]
    fn test_valid_workspace_topological_sort() {
        let mut resolver = WorkspaceGraphResolver::new();
        let core = CargoManifest {
            name: PackageId("core_lib".to_string()),
            dependencies: vec![],
            default_features: vec!["alloc".to_string()],
            optional_features: HashMap::new(),
        };
        let app = CargoManifest {
            name: PackageId("app_bin".to_string()),
            dependencies: vec![PackageId("core_lib".to_string())],
            default_features: vec![],
            optional_features: HashMap::new(),
        };

        resolver.add_package(core);
        resolver.add_package(app);

        let order = resolver.resolve_compilation_order().unwrap();
        assert_eq!(order.len(), 2);
        assert_eq!(order[0], PackageId("core_lib".to_string()));
        assert_eq!(order[1], PackageId("app_bin".to_string()));
        assert_ne!(order[0], order[1]);
    }

    #[test]
    fn test_cycle_detection() {
        let mut resolver = WorkspaceGraphResolver::new();
        let crate_a = CargoManifest {
            name: PackageId("crate_a".to_string()),
            dependencies: vec![PackageId("crate_b".to_string())],
            default_features: vec![],
            optional_features: HashMap::new(),
        };
        let crate_b = CargoManifest {
            name: PackageId("crate_b".to_string()),
            dependencies: vec![PackageId("crate_a".to_string())],
            default_features: vec![],
            optional_features: HashMap::new(),
        };

        resolver.add_package(crate_a);
        resolver.add_package(crate_b);

        let result = resolver.resolve_compilation_order();
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, WorkspaceError::Cycle(_)));
    }

    #[test]
    fn test_missing_dependency() {
        let mut resolver = WorkspaceGraphResolver::new();
        let app = CargoManifest {
            name: PackageId("app".to_string()),
            dependencies: vec![PackageId("unknown".to_string())],
            default_features: vec![],
            optional_features: HashMap::new(),
        };
        resolver.add_package(app);

        let result = resolver.resolve_compilation_order();
        assert!(matches!(result, Err(WorkspaceError::MissingDependency { .. })));
    }

    #[test]
    fn test_feature_unification() {
        let mut resolver = WorkspaceGraphResolver::new();
        let core = CargoManifest {
            name: PackageId("core".to_string()),
            dependencies: vec![],
            default_features: vec!["std".to_string()],
            optional_features: HashMap::new(),
        };
        resolver.add_package(core);

        let mut reqs = HashMap::new();
        reqs.insert(PackageId("core".to_string()), vec!["serde".to_string()]);

        let unified = resolver.unify_features(&reqs);
        let core_feats = unified.get(&PackageId("core".to_string())).unwrap();
        assert!(core_feats.contains("std"));
        assert!(core_feats.contains("serde"));
        assert_eq!(core_feats.len(), 2);
    }
}

Exercise 2: build.rs Directive Generator & C-Header Macro CodeGen Parser

Scenario: When integrating low-level C libraries or native peripheral controllers into Rust applications via FFI, Cargo build scripts (build.rs) communicate build instructions to rustc through formatted stdout output directives (cargo::rustc-link-lib, cargo::rerun-if-changed, etc.). Additionally, build scripts frequently parse external C headers or hardware definition files to generate Rust constant bindings written into OUT_DIR.

Construct a BuildScriptGenerator engine that:

Requirements:

1. Emits standard modern Cargo directives (cargo::key=value) for library linking (LinkKind::Static, LinkKind::Dynamic, LinkKind::Framework), search paths, rerun triggers, and custom target CFG attributes.
2. Parses C header #define MACRO_NAME literal_value lines (decimal or hex numbers) and validates that macro names form valid Rust identifiers.
3. Generates compilable Rust wrapper constant code string (e.g. pub const MACRO_NAME: u64 = value;) suitable for dynamic include! inclusion inside target crates.

use std::fmt::Write as FmtWrite;

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LinkKind {
    Static,
    Dynamic,
    Framework,
}

impl LinkKind {
    pub fn as_cargo_str(&self) -> &'static str {
        match self {
            LinkKind::Static => "static",
            LinkKind::Dynamic => "dylib",
            LinkKind::Framework => "framework",
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CargoDirective {
    pub key: String,
    pub value: String,
}

impl CargoDirective {
    pub fn link_lib(kind: LinkKind, name: &str) -> Self {
        Self {
            key: "rustc-link-lib".to_string(),
            value: format!("{}={}", kind.as_cargo_str(), name),
        }
    }

    pub fn link_search(path: &str) -> Self {
        Self {
            key: "rustc-link-search".to_string(),
            value: format!("native={}", path),
        }
    }

    pub fn rerun_if_changed(file_path: &str) -> Self {
        Self {
            key: "rerun-if-changed".to_string(),
            value: file_path.to_string(),
        }
    }

    pub fn cfg(flag: &str) -> Self {
        Self {
            key: "rustc-cfg".to_string(),
            value: flag.to_string(),
        }
    }

    pub fn to_cargo_instruction(&self) -> String {
        format!("cargo::{}={}", self.key, self.value)
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CMacroConstant {
    pub name: String,
    pub value: u64,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ParserError {
    InvalidIdentifier(String),
    InvalidValue(String),
    EmptyDirective,
}

pub struct BuildScriptGenerator {
    directives: Vec<CargoDirective>,
    parsed_constants: Vec<CMacroConstant>,
}

impl BuildScriptGenerator {
    pub fn new() -> Self {
        Self {
            directives: Vec::new(),
            parsed_constants: Vec::new(),
        }
    }

    pub fn add_directive(&mut self, directive: CargoDirective) {
        self.directives.push(directive);
    }

    pub fn parse_c_header(&mut self, header_content: &str) -> Result<usize, ParserError> {
        let mut count = 0;
        for line in header_content.lines() {
            let trimmed = line.trim();
            if trimmed.starts_with("#define") {
                let parts: Vec<&str> = trimmed.split_whitespace().collect();
                if parts.len() >= 3 {
                    let name = parts[1];
                    let val_str = parts[2];

                    if !Self::is_valid_rust_identifier(name) {
                        return Err(ParserError::InvalidIdentifier(name.to_string()));
                    }

                    if let Ok(val) = val_str.parse::<u64>() {
                        self.parsed_constants.push(CMacroConstant {
                            name: name.to_string(),
                            value: val,
                        });
                        count += 1;
                    } else if val_str.starts_with("0x") || val_str.starts_with("0X") {
                        if let Ok(val) = u64::from_str_radix(&val_str[2..], 16) {
                            self.parsed_constants.push(CMacroConstant {
                                name: name.to_string(),
                                value: val,
                            });
                            count += 1;
                        }
                    }
                }
            }
        }
        Ok(count)
    }

    fn is_valid_rust_identifier(id: &str) -> bool {
        if id.is_empty() {
            return false;
        }
        let first = id.chars().next().unwrap();
        if !first.is_ascii_alphabetic() && first != '_' {
            return false;
        }
        id.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
    }

    pub fn emit_cargo_directives(&self) -> String {
        let mut output = String::new();
        for dir in &self.directives {
            output.push_str(&dir.to_cargo_instruction());
            output.push('\n');
        }
        output
    }

    pub fn generate_rust_bindings(&self) -> String {
        let mut code = String::new();
        code.push_str("// Auto-generated by BuildScriptGenerator - DO NOT EDIT\n\n");
        for constant in &self.parsed_constants {
            let _ = writeln!(
                code,
                "pub const {}: u64 = {};",
                constant.name, constant.value
            );
        }
        code
    }
}

fn main() {
    let mut gen = BuildScriptGenerator::new();
    gen.add_directive(CargoDirective::link_lib(LinkKind::Static, "ssl"));
    gen.add_directive(CargoDirective::rerun_if_changed("wrapper.h"));
    
    let header = "#define BUF_SIZE 8192\n#define HW_ADDR 0x4000";
    gen.parse_c_header(header).unwrap();

    print!("{}", gen.emit_cargo_directives());
    println!("{}", gen.generate_rust_bindings());
}

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

    #[test]
    fn test_cargo_directive_generation() {
        let dir = CargoDirective::link_lib(LinkKind::Static, "crypto");
        assert_eq!(dir.to_cargo_instruction(), "cargo::rustc-link-lib=static=crypto");

        let search = CargoDirective::link_search("/usr/local/lib");
        assert_eq!(search.to_cargo_instruction(), "cargo::rustc-link-search=native=/usr/local/lib");

        let rerun = CargoDirective::rerun_if_changed("build.rs");
        assert_ne!(rerun.to_cargo_instruction(), "cargo::rerun-if-changed=main.rs");
    }

    #[test]
    fn test_c_header_parsing() {
        let mut gen = BuildScriptGenerator::new();
        let header = r#"
            #define MAX_CONNECTIONS 1024
            #define FLAGS 0xFF
            // Comment line
            #define 123INVALID 50
        "#;

        let res = gen.parse_c_header(header);
        assert!(matches!(res, Err(ParserError::InvalidIdentifier(_))));

        let valid_header = "#define MAX_CONNECTIONS 1024\n#define FLAGS 0xFF";
        let mut gen2 = BuildScriptGenerator::new();
        let count = gen2.parse_c_header(valid_header).unwrap();
        assert_eq!(count, 2);

        let bindings = gen2.generate_rust_bindings();
        assert!(bindings.contains("pub const MAX_CONNECTIONS: u64 = 1024;"));
        assert!(bindings.contains("pub const FLAGS: u64 = 255;"));
    }
}

Exercise 3: Cargo Profile Hardening & Dependency Compliance Auditor

Scenario: Continuous Delivery pipelines in production environments mandate strict compilation profile options in Cargo.toml to guarantee code optimization, minimal attack surfaces, and zero forbidden external dependencies. For instance, release profiles must mandate LTO (lto = "fat" or "thin"), panic strategy (panic = "abort"), cap codegen-units = 1, and prohibit insecure crates (such as unvetted crypto or outdated parsers).

Requirements: Implement a CargoProfileAuditor compliance engine that:

1. Models CargoProfile settings (opt_level, lto, codegen_units, panic_strategy, overflow_checks, strip).
2. Audits profiles against a configurable SecurityPolicy struct.
3. Scans workspace dependency lists to detect prohibited or vulnerable crates.
4. Produces an AuditReport containing diagnostic severity levels (Pass, Warning, Violation) and helper functions is_compliant() and violation_count().

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OptLevel {
    O0,
    O1,
    O2,
    O3,
    Os,
    Oz,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LtoSetting {
    Off,
    Thin,
    Fat,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PanicStrategy {
    Unwind,
    Abort,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CargoProfile {
    pub name: String,
    pub opt_level: OptLevel,
    pub lto: LtoSetting,
    pub codegen_units: u32,
    pub panic_strategy: PanicStrategy,
    pub overflow_checks: bool,
    pub strip: bool,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SecurityPolicy {
    pub min_opt_level: OptLevel,
    pub required_lto: Vec<LtoSetting>,
    pub max_codegen_units: u32,
    pub required_panic_strategy: PanicStrategy,
    pub forbidden_crates: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DiagnosticLevel {
    Pass,
    Warning,
    Violation,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AuditDiagnostic {
    pub level: DiagnosticLevel,
    pub rule: String,
    pub message: String,
}

#[derive(Debug, Default, PartialEq, Eq)]
pub struct AuditReport {
    pub diagnostics: Vec<AuditDiagnostic>,
}

impl AuditReport {
    pub fn is_compliant(&self) -> bool {
        !self
            .diagnostics
            .iter()
            .any(|d| d.level == DiagnosticLevel::Violation)
    }

    pub fn violation_count(&self) -> usize {
        self.diagnostics
            .iter()
            .filter(|d| d.level == DiagnosticLevel::Violation)
            .count()
    }
}

pub struct CargoProfileAuditor {
    policy: SecurityPolicy,
}

impl CargoProfileAuditor {
    pub fn new(policy: SecurityPolicy) -> Self {
        Self { policy }
    }

    pub fn audit_profile(&self, profile: &CargoProfile) -> AuditReport {
        let mut report = AuditReport::default();

        if profile.panic_strategy != self.policy.required_panic_strategy {
            report.diagnostics.push(AuditDiagnostic {
                level: DiagnosticLevel::Violation,
                rule: "PANIC_STRATEGY".to_string(),
                message: format!(
                    "Profile '{}' uses panic strategy '{:?}', but policy requires '{:?}'",
                    profile.name, profile.panic_strategy, self.policy.required_panic_strategy
                ),
            });
        } else {
            report.diagnostics.push(AuditDiagnostic {
                level: DiagnosticLevel::Pass,
                rule: "PANIC_STRATEGY".to_string(),
                message: "Panic strategy complies with security policy.".to_string(),
            });
        }

        if !self.policy.required_lto.contains(&profile.lto) {
            report.diagnostics.push(AuditDiagnostic {
                level: DiagnosticLevel::Violation,
                rule: "LTO_SETTINGS".to_string(),
                message: format!(
                    "Profile '{}' LTO setting '{:?}' is not permitted by policy.",
                    profile.name, profile.lto
                ),
            });
        } else {
            report.diagnostics.push(AuditDiagnostic {
                level: DiagnosticLevel::Pass,
                rule: "LTO_SETTINGS".to_string(),
                message: "LTO setting complies with security policy.".to_string(),
            });
        }

        if profile.codegen_units > self.policy.max_codegen_units {
            report.diagnostics.push(AuditDiagnostic {
                level: DiagnosticLevel::Violation,
                rule: "CODEGEN_UNITS".to_string(),
                message: format!(
                    "Profile '{}' codegen-units ({}) exceeds policy limit ({})",
                    profile.name, profile.codegen_units, self.policy.max_codegen_units
                ),
            });
        } else {
            report.diagnostics.push(AuditDiagnostic {
                level: DiagnosticLevel::Pass,
                rule: "CODEGEN_UNITS".to_string(),
                message: "Codegen-units configuration is within limits.".to_string(),
            });
        }

        report
    }

    pub fn audit_dependencies(&self, dependencies: &[String]) -> AuditReport {
        let mut report = AuditReport::default();

        for dep in dependencies {
            if self.policy.forbidden_crates.contains(dep) {
                report.diagnostics.push(AuditDiagnostic {
                    level: DiagnosticLevel::Violation,
                    rule: "FORBIDDEN_DEPENDENCY".to_string(),
                    message: format!("Forbidden crate '{}' detected in build manifest!", dep),
                });
            }
        }

        if report.diagnostics.is_empty() {
            report.diagnostics.push(AuditDiagnostic {
                level: DiagnosticLevel::Pass,
                rule: "DEPENDENCY_SAFETY".to_string(),
                message: "All dependencies pass policy verification.".to_string(),
            });
        }

        report
    }
}

fn main() {
    let policy = SecurityPolicy {
        min_opt_level: OptLevel::O3,
        required_lto: vec![LtoSetting::Fat, LtoSetting::Thin],
        max_codegen_units: 1,
        required_panic_strategy: PanicStrategy::Abort,
        forbidden_crates: vec!["insecure_crypto".to_string()],
    };

    let profile = CargoProfile {
        name: "production".to_string(),
        opt_level: OptLevel::O3,
        lto: LtoSetting::Fat,
        codegen_units: 1,
        panic_strategy: PanicStrategy::Abort,
        overflow_checks: true,
        strip: true,
    };

    let auditor = CargoProfileAuditor::new(policy);
    let report = auditor.audit_profile(&profile);
    println!("Is compliant: {}", report.is_compliant());
}

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

    #[test]
    fn test_profile_compliance_pass() {
        let policy = SecurityPolicy {
            min_opt_level: OptLevel::O3,
            required_lto: vec![LtoSetting::Fat, LtoSetting::Thin],
            max_codegen_units: 1,
            required_panic_strategy: PanicStrategy::Abort,
            forbidden_crates: vec!["insecure_crypto".to_string()],
        };

        let auditor = CargoProfileAuditor::new(policy);
        let prod_profile = CargoProfile {
            name: "release".to_string(),
            opt_level: OptLevel::O3,
            lto: LtoSetting::Fat,
            codegen_units: 1,
            panic_strategy: PanicStrategy::Abort,
            overflow_checks: true,
            strip: true,
        };

        let report = auditor.audit_profile(&prod_profile);
        assert!(report.is_compliant());
        assert_eq!(report.violation_count(), 0);
    }

    #[test]
    fn test_profile_compliance_violations() {
        let policy = SecurityPolicy {
            min_opt_level: OptLevel::O2,
            required_lto: vec![LtoSetting::Fat],
            max_codegen_units: 1,
            required_panic_strategy: PanicStrategy::Abort,
            forbidden_crates: vec!["vulnerable_parser".to_string()],
        };

        let auditor = CargoProfileAuditor::new(policy);
        let weak_profile = CargoProfile {
            name: "release".to_string(),
            opt_level: OptLevel::O0,
            lto: LtoSetting::Off,
            codegen_units: 16,
            panic_strategy: PanicStrategy::Unwind,
            overflow_checks: false,
            strip: false,
        };

        let report = auditor.audit_profile(&weak_profile);
        assert!(!report.is_compliant());
        assert_eq!(report.violation_count(), 3);
        assert_ne!(report.violation_count(), 0);

        let dep_report = auditor.audit_dependencies(&["vulnerable_parser".to_string(), "serde".to_string()]);
        assert!(matches!(dep_report.diagnostics[0].level, DiagnosticLevel::Violation));
    }
}

6. Related Terms

• Crate — the compilation unit that Cargo builds; every cargo build produces a crate
• Package — a Cargo concept: one or more crates bundled with a Cargo.toml manifest
• Cargo.toml — the manifest file where you declare metadata, dependencies, and build settings
• Cargo.lock — the auto-generated lock file that pins exact dependency versions
• Rustup — the toolchain manager that installs Cargo (and the Rust compiler) for you
• Module — Related concept: Module.

7. Key Takeaways

• Cargo is your single tool for everything — creating projects, building, testing, documenting, and publishing. You rarely need to call rustc directly.
• Cargo.toml is the blueprint — it declares your project's metadata and dependencies. Cargo handles the rest.
• Convention over configuration — Cargo enforces a standard project layout (src/, tests/, Cargo.toml), which means every Rust project looks familiar.
• Reproducible builds come free — Cargo.lock pins exact dependency versions so builds are consistent across machines.
• The ecosystem starts here — Cargo connects to crates.io, giving you access to over 100,000 community libraries with a single line in Cargo.toml.