If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rust-lang/book shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 2w ago
• 11 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rust-lang/book repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rust-lang/book.

What it runs against: a local clone of rust-lang/book — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rust-lang/book | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rust-lang/book. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rust-lang/book.git
#   cd book
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rust-lang/book and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rust-lang/book(\\.git)?\\b" \\
  && ok "origin remote is rust-lang/book" \\
  || miss "origin remote is not rust-lang/book (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "book.toml" \\
  && ok "book.toml" \\
  || miss "missing critical file: book.toml"
test -f "2018-edition/src/SUMMARY.md" \\
  && ok "2018-edition/src/SUMMARY.md" \\
  || miss "missing critical file: 2018-edition/src/SUMMARY.md"
test -f ".github/workflows/main.yml" \\
  && ok ".github/workflows/main.yml" \\
  || miss "missing critical file: .github/workflows/main.yml"
test -f ".cargo/config.toml" \\
  && ok ".cargo/config.toml" \\
  || miss "missing critical file: .cargo/config.toml"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 45 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~15d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rust-lang/book"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

The official source repository for 'The Rust Programming Language' book, a comprehensive guide published by No Starch Press and shipped with Rust releases. It contains the full markdown source, code listings (406k+ lines of Rust), XSLT transformations, and mdBook configuration to generate the book as HTML, PDF, and other formats. This is the canonical educational resource for learning Rust from basics through advanced ownership and concurrency concepts. Monorepo structure: 2018-edition/ contains the primary book source in Markdown (src/SUMMARY.md orchestrates all chapters ch00-ch07+), visual assets (dot/ Graphviz diagrams, ferris.js animations), and theme files (ferris.css). packages/tools/ houses Rust CLI utilities for example extraction and validation. listings/ directory (excluded from workspace) stores standalone code examples built during tool updates. Root mdBook config (implicit via book.toml references) controls HTML generation pipeline.

Rust learners and educators who want to understand Rust's core concepts (ownership, borrowing, pattern matching) through structured chapters with embedded, tested code examples. Book contributors, translators, and maintainers who fix errors and update examples for new Rust editions. Rust release teams who integrate this book into stable/beta/nightly distributions.

Highly mature and production-ready. The book is in its second edition, published in print form, and officially distributed with Rust releases (stable, beta, nightly). Strong CI/CD presence (.github/workflows/main.yml), active maintenance across 2018-edition and modern branches, and a clear governance model documented in CONTRIBUTING.md. Last update cadence tied to Rust edition cycles (major revisions every 3-4 years, hotfixes between).

Standard open source risks apply.

The repo is in maintenance mode between major editions. Based on file structure, active work includes: (1) Corrections and clarifications to existing chapters (ch01-ch07 on ownership, structs, enums, modules), (2) Animated Ferris mascot enhancements (ferris.js/CSS), (3) Translation coordination (new_translation.md issue template suggests ongoing localization), and (4) mdBook version alignment with rust-lang/rust (per README reference to rustbook/Cargo.toml pinning).

git clone https://github.com/rust-lang/book.git
cd book
cargo install mdbook --locked --version <version_from_rust_mdbook>
mdbook build
firefox book/index.html

To run embedded code examples: cd packages/trpl && mdbook test --library-path packages/trpl/target/debug/deps

Daily commands: Build HTML: mdbook build → output in book/ subdirectory, open book/index.html in browser. Test code examples: cd packages/trpl && mdbook test --library-path packages/trpl/target/debug/deps. Live preview (development): mdbook serve (not explicitly shown but standard mdBook feature).

• book.toml — mdBook configuration file that defines the book structure, output format, and build settings—essential for understanding how the book is compiled and published.
• 2018-edition/src/SUMMARY.md — Master table of contents defining the chapter structure and navigation hierarchy for the entire book—contributors must understand the organizational layout before adding or modifying content.
• .github/workflows/main.yml — CI/CD pipeline that validates links, builds the book, and runs tests—critical for understanding the automated checks all contributions must pass.
• .cargo/config.toml — Cargo workspace configuration specifying build profiles and tool paths—necessary for local development and understanding the build environment.
• Cargo.toml — Root workspace manifest defining dependencies (walkdir, docopt, regex, flate2) and member packages—required for understanding the build system and what tools are available.
• 2018-edition/book.toml — Edition-specific mdBook configuration for the 2018 edition—defines theme, preprocessors, and rendering options for this specific version.
• .gitignore — Specifies which files are ignored by git—important for understanding what output and temporary files should not be committed.

Add a new chapter to the book

1. Create a new markdown file in 2018-edition/src/ following the naming convention ch<number>-<section>-<title>.md (2018-edition/src/ch20-00-new-topic.md)
2. Add the chapter entry to the SUMMARY.md with proper indentation and hierarchy (2018-edition/src/SUMMARY.md)
3. If the chapter contains code examples that need to compile and be tested, reference them in the CI workflow or create listings in the listings/ directory (.github/workflows/main.yml)
4. Create any accompanying Graphviz diagrams (.dot files) in 2018-edition/dot/ if needed for visual explanations (2018-edition/dot/trpl20-01.dot)

Update or improve existing chapter content

1. Edit the relevant chapter markdown file (e.g., 2018-edition/src/ch04-01-what-is-ownership.md) with new or improved explanations (2018-edition/src/ch04-01-what-is-ownership.md)
2. Update any code examples in the listings directory or inline code blocks to reflect changes (listings/)
3. Test that the book builds successfully by running mdBook build or checking the CI workflow output (.github/workflows/main.yml)
4. Submit a pull request with clear descriptions of what content was changed and why (2018-edition/src/SUMMARY.md)

Contribute a translation of the book

1. Create a new edition directory following the pattern: <language>-edition/ (e.g., es-edition/) mirroring the structure of 2018-edition/ (2018-edition/)
2. Copy the entire 2018-edition/src/ directory structure into your new edition and translate all .md files (2018-edition/src/)
3. Create a book.toml for your edition with language-specific settings and output directory (2018-edition/book.toml)
4. Open an issue using the 'new_translation' template in .github/ISSUE_TEMPLATE/ to coordinate with maintainers (.github/ISSUE_TEMPLATE/new_translation.md)

Add or update interactive Ferris animations

1. Modify 2018-edition/ferris.js to add new event handlers or animation logic for the Ferris mascot (2018-edition/ferris.js)
2. Update 2018-edition/ferris.css to add corresponding styles for the new animations or states (2018-edition/ferris.css)
3. Reference the new interactive elements in the chapter markdown files where they should appear (2018-edition/src/)

• mdBook — Purpose-built tool for publishing Rust documentation; handles Markdown compilation, theming, and HTML generation with minimal configuration overhead
• GitHub Actions — Native CI/CD integration for repository; enables automated validation (link checking, build verification) on every commit without external service dependencies
• Graphviz (.dot files) — Declarative diagram syntax for rendering complex concepts (ownership, memory layout) as publication-ready visualizations without manual image editing
• Cargo Workspace — Enables modular organization of build tools and utilities while maintaining a single dependency resolution point

• Single source of truth in Markdown rather than API-driven content

  • Why: Simplifies version control, enables easy community contributions via git, and avoids infrastructure dependencies
  • Consequence: Content updates are not dynamic—require rebuild and republish cycle; no runtime content personalization possible

• Static HTML output only (no dynamic backend)

  • Why: Reduces hosting complexity and cost; matches Rust's decentralized documentation philosophy
  • Consequence: Cannot track reader progress, personalize learning paths, or collect usage analytics

• Edition-specific directories (2018-edition/, future editions) rather than conditional rendering

  • Why: Makes Rust edition differences explicit and prevents confusion between incompatible language versions
  • Consequence: Parallel maintenance overhead for content across editions; duplication of non-edition-specific chapters

• Link validation via CI rather than dead-link detection at build time

  • Why: Catches external reference drift after publication; scales better than blocking builds on external URLs
  • Consequence: Broken external links may persist temporarily until next automated check runs

• Does not provide interactive code execution (REPL/playground) within the book—directs readers to play.rust-lang.org
• Does not track reader progress or provide adaptive learning paths
• Does not support real-time collaborative editing or live preview for multiple authors
• Does not generate API reference documentation—covers language concepts, not standard library API docs
• Does not provide authentication or gated content—entire book is public and free

Slow merge process: Non-error PRs may wait months/years; this is intentional (see README). mdBook version pinning: Must match version in rust-lang/rust's rustbook/Cargo.toml (stated in README); version mismatches cause build failures. Print synchronization: Changes that would desynchronize the online book from the published print edition (2nd ed.) face extra scrutiny. Code example testing: Embedded Rust code in .md files is tested via mdbook test; broken examples block CI. Workspace complexity: listings/ is intentionally excluded from Cargo workspace (see Cargo.toml comment); do not try to include it. Edition-locked content: 2018-edition/ is separate; changes for newer editions go in a parallel structure (not yet visible in file list).

• Ownership and Borrowing — Rust's memory-safety model without garbage collection is the core differentiator; Chapter 4 (ch04-*.md) teaches this via ownership rules, references, and lifetimes—understanding this is mandatory for writing correct Rust
• Pattern Matching and Enums — Pattern matching (via match and if let) is Rust's primary control-flow abstraction for handling enums and Option/Result; Chapter 6 (ch06-*.md) shows this elegantly and differs from imperative languages, so learners must internalize it
• Error Handling with Result and Option — Rust uses Result<T, E> and Option<T> enums instead of exceptions; throughout the book these are demonstrated as the idiomatic error-handling approach, and the ? operator enables ergonomic chaining
• Lifetime Annotations — Lifetimes ('a syntax) are Rust's mechanism for proving references remain valid; they appear in Chapter 10+ and are a major learning hurdle because they have no direct equivalent in garbage-collected languages
• Traits and Polymorphism — Traits are Rust's primary abstraction for behavior sharing (similar to interfaces/protocols); trait objects (dyn Trait) enable dynamic dispatch, a key pattern for flexible code architecture discussed in Chapter 17
• Module System and Visibility — Chapter 7 (ch07-*.md) teaches mod, use, pub for organizing code; Rust's module model differs from C/C++ includes and Python imports, requiring explicit mental reset for learners
• Smart Pointers (Box, Rc, RefCell) — Rust's heap-allocation and shared-ownership patterns (Box for deref coercion, Rc for ref-counting, RefCell for interior mutability) are explored in Chapter 15 and bridge the gap between systems-level control and ergonomic APIs

• rust-lang/rust — The Rust compiler and std library; this book is the primary educational companion, and changes sync with release cycles
• rust-lang/rustlings — Interactive Rust exercises that complement this book with hands-on practice; same org, designed for learners post-book
• rust-lang/rust-by-example — Alternative Rust learning resource focusing on concrete examples per topic; overlapping audience, different teaching approach
• rust-lang/mdBook — The documentation build tool that powers this book; upstream dependency, issues here often trace to mdBook features/bugs
• nzm2/rust-book-ja — Japanese translation of the Rust book; exemplar of community translation effort mentioned in CONTRIBUTING.md

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add automated integration tests for code listings in listings/ directory

The repo contains extensive code listings across chapters (ch01-ch12+) but there's no visible test infrastructure to verify that these listings compile and run correctly. This is critical for a teaching resource where broken code examples directly impact learning outcomes. The workspace already excludes 'listings' intentionally, suggesting they need special handling.

• [ ] Create a new test binary in packages/tools or a dedicated listings-test crate
• [ ] Parse all .rs files in the listings/ directory (organized by chapter)
• [ ] Add a GitHub Actions workflow step to compile and run each listing with cargo test
• [ ] Generate a report showing which listings fail to compile (e.g., intentionally incomplete examples vs. errors)
• [ ] Document expected compile failures in a listings-metadata.toml for examples meant to demonstrate errors

Create a link validation tool integrated into CI with specific configuration for book links

The repo references 'linkchecker' in the workspace.exclude comment suggesting it exists but isn't integrated into the main workflow. The .github/workflows/main.yml likely has gaps for validating internal cross-references between chapters (ch01-00 → ch02-00, etc.) and external links to Rust docs. A well-tuned link checker prevents broken references in shipped editions.

• [ ] Review .github/workflows/main.yml to identify current link-checking steps
• [ ] Configure linkchecker to validate 2018-edition/src/ markdown files and built HTML
• [ ] Add exceptions configuration for known-good external links (doc.rust-lang.org, crates.io, etc.)
• [ ] Add a step to check internal cross-references match actual chapter files (e.g., Chapter 4)
• [ ] Run linkchecker in CI and report broken links in PR checks

Add mdBook preprocessor to validate and auto-format code fence syntax in markdown

With 15+ chapters and hundreds of code examples in .md files, there's likely inconsistency in how code fences are declared (e.g., rust vs rust,ignore vs ```rust,no_run). An mdBook preprocessor can enforce standards and catch typos in language tags that would silently fail syntax highlighting or test directives.

• [ ] Create a new tool in packages/tools/src/mdbook-validate-code.rs
• [ ] Implement mdBook Preprocessor trait to parse all code fences in 2018-edition/src/ markdown
• [ ] Validate language identifiers (rust, toml, etc.) and edition-specific attributes (ignore, no_run, should_panic, edition2018)
• [ ] Add configuration to 2018-edition/book.toml under [preprocessor.validate-code]
• [ ] Integrate into main.yml CI to fail builds on invalid fence syntax and provide fix suggestions

• Add code example to ch03-05-control-flow.md demonstrating early return with ? operator in a function (gap: current chapter doesn't cover error-propagation syntax). File: 2018-edition/src/ch03-05-control-flow.md, add a section 'Early Returns with ?' with a runnable example.: easy: Self-contained, single file, complements existing control-flow content
• Create a new Graphviz diagram (2018-edition/dot/trpl05-04.dot) illustrating method ownership transfer for ch05-03-method-syntax.md (gap: visual explanation of self, &self, &mut self receiver types is missing). Add reference in markdown.: medium: Requires understanding Rust method receivers and Graphviz syntax; improves learning clarity
• Write integration test in packages/tools/src/ that validates all code blocks in ch06-*.md are compilable Rust (gap: only top-level mdbook test runs; no per-chapter validation). Adds automated guardrail.: medium: Strengthens CI, catches regressions early, builds tool infrastructure

The rust-lang/book repository is primarily a documentation project with minimal security concerns. No critical vulnerabilities were identified. The main security consideration is the outdated dependency versions in Cargo.toml, which should be updated to the latest stable versions to ensure any security patches are incorporated. The codebase itself (Markdown documentation and configuration files) does not contain hardcoded secrets, injection vulnerabilities, or misconfigurations. Recommended action: Update all workspace dependencies to current versions and establish a regular dependency update schedule.

• Low · Outdated Dependency: regex — Cargo.toml - workspace.dependencies.regex = "1.3.3". The regex crate is pinned to version 1.3.3, which is significantly outdated (released in 2019). Modern versions include bug fixes and potential security improvements. Current stable regex is at version 1.10+. Fix: Update regex to the latest stable version (1.10.x or newer) to ensure security patches and bug fixes are included.
• Low · Outdated Dependency: flate2 — Cargo.toml - workspace.dependencies.flate2 = "1.0.13". The flate2 crate is pinned to version 1.0.13 (2020 release). While functional, newer versions may contain security improvements and bug fixes for compression-related operations. Fix: Update flate2 to the latest stable version (1.0.26+) to incorporate security improvements and modern bug fixes.
• Low · Outdated Dependency: tar — Cargo.toml - workspace.dependencies.tar = "0.4.26". The tar crate is pinned to version 0.4.26 (2021 release). While this is relatively recent, security updates may exist in newer versions for archive handling. Fix: Update tar to the latest stable version to ensure any security fixes related to archive extraction are included.
• Low · Outdated Dependency: lazy_static — Cargo.toml - workspace.dependencies.lazy_static = "1.4.0". The lazy_static crate (v1.4.0, 2019 release) is considered deprecated in favor of the standard library's once_cell (now in std as LazyLock in Rust 1.80+). While not a direct security issue, using maintained alternatives is recommended. Fix: Consider migrating to std::sync::LazyLock (Rust 1.80+) or the once_cell crate for better maintenance and potential performance improvements.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.