Project 6: Rust Workspace Engineering & Toolchain Governance

Build a multi-crate Rust workspace with deterministic build behavior and CI-enforced format/lint/doc/test policy.

Quick Reference

Attribute Value
Difficulty Level 2: Intermediate
Time Estimate 4-6 days
Main Programming Language Rust
Alternative Programming Languages Go, C++
Coolness Level Level 3: Genuinely Clever
Business Potential 3. The “Service & Support” Model
Prerequisites Projects 1-3, Cargo basics
Key Topics Cargo workspaces, feature flags, build.rs, Clippy, rustfmt, rustdoc

1. Learning Objectives

By completing this project, you will:

  1. Design workspace crate boundaries for a real Rust repository.
  2. Define a feature matrix that is additive and testable.
  3. Implement deterministic build.rs behavior with explicit rerun inputs.
  4. Enforce formatting, linting, tests, and docs as CI gates.

2. Theoretical Foundation

2.1 Core Concepts

  • Workspace architecture: Crate boundaries define dependency direction, build times, and team ownership.
  • Feature unification: Features are additive across dependency graph edges; accidental capability expansion is common.
  • Build determinism: build.rs should be predictable, idempotent, and explicit about trigger conditions.
  • Policy gates: rustfmt, Clippy, and rustdoc are reproducibility and maintainability controls.

2.2 Why This Matters

Most production Rust issues in large repos are process failures: inconsistent style, silent feature drift, stale generated files, or undocumented API behavior. This project prevents those early.

2.3 Common Misconceptions

  • “Features are runtime flags” -> no, compile-time graph switches.
  • “build.rs can do anything” -> it can, but it should not.
  • “Docs are optional” -> docs are API contracts.

3. Project Specification

3.1 What You Will Build

A workspace with:

  • core crate (pure logic)
  • server crate (runtime)
  • cli crate (tooling entrypoint)
  • feature matrix (default, minimal, optional integrations)
  • deterministic build.rs in one crate
  • CI-style check script for fmt/clippy/test/doc

3.2 Functional Requirements

  1. Build from clean checkout using one command.
  2. Compile with default features and with --no-default-features.
  3. Enforce lint/style/doc checks.
  4. Document feature contract and quality policy.

3.3 Non-Functional Requirements

  • Reliability: No non-deterministic build outputs.
  • Usability: New contributor can run checks in less than 5 commands.
  • Maintainability: Every lint suppression has rationale.

3.4 Example Usage / Output

$ cargo fmt --all --check
All done!

$ cargo clippy --workspace --all-targets --all-features -- -D warnings
Finished dev [unoptimized + debuginfo] target(s) in 2.31s

$ cargo doc --workspace --no-deps
Generated target/doc/index.html

3.5 Real World Outcome

Your repo behaves predictably on laptops and CI runners. A reviewer can clone, run checks, and trust that formatting/lints/docs/features are enforced before merge.

4. Solution Architecture

4.1 High-Level Design

Workspace Root
├── crates/core      (domain logic, minimal deps)
├── crates/server    (runtime + optional features)
├── crates/cli       (operator tooling)
└── scripts/check.sh (fmt + lint + test + doc)

4.2 Key Components

Component Responsibility Key Decision
Workspace manifest Membership, shared policy Centralize profile/lint policy
Feature matrix doc Compile-time capability contract Explicit default/minimal sets
build.rs module Generated metadata Strict rerun triggers only
Quality check script Standardized validation Same commands in local + CI

5. Implementation Guide

5.1 The Core Question You’re Answering

“How do I make repository behavior deterministic and reviewable across machines?”

5.2 Concepts You Must Understand First

  1. Cargo workspaces and lockfile semantics.
  2. Feature unification and additive behavior.
  3. Clippy lint levels and policy trade-offs.
  4. Rustdoc + doctest value for API trust.

5.3 Questions to Guide Your Design

  1. Which crates must not depend on runtime-only features?
  2. Which features can be safely defaulted?
  3. Which checks should block merges?

5.4 Thinking Exercise

Draw your crate graph and feature matrix on paper. Mark invalid dependencies (e.g., core depending on server) and define a command that would catch each violation.

5.5 The Interview Questions They’ll Ask

  1. “How do Cargo features interact across dependencies?”
  2. “What makes a build script reproducible?”
  3. “Why deny Clippy warnings in CI?”
  4. “How do docs prevent operational mistakes?”

5.6 Hints in Layers

  • Hint 1: Start with crate boundaries, not implementation.
  • Hint 2: Document feature intent before adding flags.
  • Hint 3: Keep build.rs side-effect free and explicit.
  • Hint 4: Use one check script for local and CI parity.

5.7 Books That Will Help

Topic Book Chapter
Workspace organization “The Rust Programming Language” Ch. 14
Build orchestration Cargo Book Workspaces / Features / Build scripts
Engineering hygiene “Effective Rust” Project-quality items

6. Testing Strategy

  • Unit tests: crate-local invariants.
  • Integration tests: public API behavior across crates.
  • Feature matrix tests: default + minimal + selected optional sets.
  • Doc tests: executable API examples.

7. Common Pitfalls & Debugging

Pitfall Symptom Solution
Hidden feature activation Different behavior in CI Inspect cargo tree -e features
Non-deterministic build.rs Frequent rebuild churn Add precise rerun directives
Lint fatigue Many ignored warnings Separate deny vs warn policy

8. Self-Assessment Checklist

  • Workspace graph is intentional and documented.
  • Feature matrix compiles in CI variants.
  • build.rs contract and triggers are documented.
  • fmt/clippy/test/doc checks are mandatory gates.

9. Completion Criteria

Minimum Viable Completion

  • Workspace compiles with default + minimal features.
  • Quality checks pass locally and in CI.

Full Completion

  • Includes feature matrix docs and deterministic build evidence.

Excellence

  • Adds trend reporting for lint/test/doc regressions and contributor onboarding notes.