Learning and Documentation Map

Purpose and Scope

This page maps the main Rust learning resources into a practical route for readers who are choosing what to read next. Rust’s public learning surface is intentionally layered: new users start with guided tutorial material, then move to examples, local documentation, domain books, and finally specification-oriented or unstable material. The official Learn page names the Book, Rust by Example, Rustlings, standard library documentation, the Edition Guide, Cargo Book, rustdoc Book, rustc Book, Compiler Error Index, domain books, the Reference, and the Rustonomicon as parts of that path.

The repository evidence for this page focuses on the Unstable Book. That is useful because it shows where the public documentation map ends and implementation-adjacent documentation begins. Stable learning resources explain how to write Rust programs; the Unstable Book documents nightly-only language features, compiler flags, library features, and environment variables that require more context and caution. The generator in src/tools/unstable-book-gen/src/main.rs demonstrates that unstable documentation is not a loose collection of pages: it is produced from feature data and existing section files into a structured book summary.

Sources: src/tools/unstable-book-gen/src/main.rs, src/doc/unstable-book/src/language-features.md

Reader Path Through the Documentation

Start with The Rust Programming Language, commonly called “the Book,” when the reader needs the language from first principles. The official Book introduces installation, projects, ownership, borrowing, types, error handling, generics, traits, lifetimes, testing, smart pointers, concurrency, and more in a sequenced tutorial. It is the best first document because later resources assume the reader has a working model of Rust syntax, Cargo projects, and the ownership system. The official docs also note that the Book is available online and offline through rustup, so it can serve as a local reference while learning.

After the Book, use Rust by Example or Rustlings depending on learning style. Rust by Example is code-first: it keeps prose short and shows runnable snippets and exercises. Rustlings is command-line and environment-based: it asks the reader to install the toolchain and practice syntax locally. These resources are complementary rather than competing. A reader who understands a concept in prose but cannot yet write it fluently should use Rustlings; a reader who wants to compare patterns quickly should use Rust by Example.

Once the reader can write small programs, move to the core documentation set. The standard library documentation is the API reference for std, while the Cargo Book explains package management and build workflows. The rustdoc Book teaches crate documentation, and the rustc Book documents compiler options and behavior. The Compiler Error Index is a troubleshooting resource that explains diagnostics. The Edition Guide belongs here as well because it explains edition-driven language migration and compatibility, which matters when reading examples written for different Rust editions.

The domain-specific books come next. The Command Line Book helps readers build practical CLI applications, while the Embedded Book targets bare-metal and microcontroller work. The official embedded documentation is explicit that it teaches setup, current practices, and cookbook-style tasks such as mixing C and Rust. That sequencing matters: embedded Rust often uses #![no_std], target-specific ABIs, linker behavior, and hardware constraints, so it is much easier after a reader has absorbed the Book and basic Cargo workflows.

Use the Reference and the Rustonomicon when the task requires precision. The Reference is described by the official docs as more detailed and comprehensive than the Book, but not a formal specification. It is appropriate for exact language behavior, grammar, attributes, and memory model details. The Rustonomicon is for unsafe Rust, where the reader needs to understand invariants that the compiler cannot check. These resources are not beginner tutorials; they are precision tools for resolving questions that tutorial material intentionally simplifies.

Where the Unstable Book Fits

The Unstable Book belongs near the end of the learning map, after stable Rust, tools, and reference material. It documents features that are not yet stabilized, so its readers are usually nightly users, library authors, embedded developers, compiler contributors, or people evaluating feature gates. The source tree shows a language-features index and individual feature pages, which mirrors the reader task: discover a feature name, read its tracking issue and behavior, then decide whether nightly usage is justified.

Sources: src/doc/unstable-book/src/language-features.md, src/doc/unstable-book/src/language-features/abi-cmse-nonsecure-call.md, src/doc/unstable-book/src/language-features/abi-msp430-interrupt.md

A typical unstable language-feature page has a predictable structure. The abi_cmse_nonsecure_call page starts with the feature name and tracking issue, explains that the feature is for Armv8-M TrustZone-M targets, defines the cmse-nonsecure-call ABI, lists what the compiler does during the call, and includes a target-specific Rust example plus generated assembly. The abi_msp430_interrupt page follows the same pattern for MSP430 interrupt handlers, showing the ABI string, an interrupt vector placement example, and objdump output. These are learning documents, but they are also operational references for specialized targets.

The lang_items page shows a different kind of unstable topic: compiler-recognized items implemented by libraries and marked with #[lang = "..."]. It explains that language items are loaded lazily, that missing required items cause compiler errors, and that many are defined by core. It then gives a freestanding Box example that defines allocation, panic, and exception-personality pieces for a #![no_std] program. This is the point where the learning map crosses from ordinary Rust programming into compiler and library boundary knowledge.

Sources: src/doc/unstable-book/src/language-features/lang-items.md

The Unstable Book also contains compiler-flag documentation. The external-clangrt page documents an option that changes sanitizer runtime linking behavior: passing the flag makes the compiler not link its own runtime library. That kind of page is not a language tutorial; it is a focused operational note for users combining Rust sanitizers with other languages or runtimes. In the learning map, it belongs beside rustc and toolchain documentation, not beside beginner examples.

Sources: src/doc/unstable-book/src/compiler-flags/external-clangrt.md

System-to-Code Mapping

The source organization shows how unstable documentation is kept synchronized with compiler and library feature metadata. src/tools/unstable-book-gen/src/main.rs imports feature collection helpers from tidy, collects language features, library features, compiler flags, and environment variables, and then writes generated book sections. It builds summary entries from sets of feature names, converts hyphenated names into display links, creates missing section files, and emits stub pages with either tracking-issue or no-issue templates. That generator gives contributors a concrete contract: feature metadata and book pages must stay aligned.

The language feature index at src/doc/unstable-book/src/language-features.md is intentionally small in the supplied evidence, while the generator is responsible for building the richer summary around feature files. Individual pages carry the explanatory weight. The ABI feature pages demonstrate target-specific documentation style: they name the architecture, explain the calling convention, show the feature gate, and include command output or disassembly. This makes the Unstable Book useful both for readers and for reviewers checking whether a feature has enough user-facing explanation.

Reader question	Best first resource	Repository-backed signal
“I am new to Rust.”	The Book	Stable tutorial material comes before unstable feature docs.
“I learn by editing code.”	Rust by Example or Rustlings	Example-driven learning should precede nightly-only feature use.
“Which API should I call?”	Standard library docs	Stable API docs are separate from feature-gated unstable pages.
“How do I build and document crates?”	Cargo Book and rustdoc Book	Tool documentation sits before compiler flags.
“What exactly does the language allow?”	Reference	Reference-style precision is needed before unsafe or unstable topics.
“Can I use this nightly feature?”	Unstable Book	Feature pages include names, tracking issues, examples, and constraints.

Relevant Source Files

• src/doc/unstable-book/src/language-features/lang-items.md — Explains the lang_items unstable feature, lazy compiler loading of language items, common lang item categories, and a freestanding Box example for #![no_std] contexts.
• src/tools/unstable-book-gen/src/main.rs — Implements the generator that collects unstable feature names, compiler flags, environment variables, and existing section files, then writes summary and stub documentation files.
• src/doc/unstable-book/src/compiler-flags/external-clangrt.md — Documents the external-clangrt compiler flag and its relationship to sanitizer runtime linking.
• src/doc/unstable-book/src/language-features.md — Provides the language-features section entry point used by the Unstable Book structure.
• src/doc/unstable-book/src/language-features/abi-cmse-nonsecure-call.md — Documents the abi_cmse_nonsecure_call feature, its Armv8-M TrustZone-M context, compiler call behavior, and assembly-oriented example.
• src/doc/unstable-book/src/language-features/abi-msp430-interrupt.md — Documents the abi_msp430_interrupt feature for MSP430 interrupt-handler calling conventions and vector placement.

Practical Navigation Guidance

For a new user, the safest path is sequential: install Rust, read the first chapters of the Book, build a small Cargo project, then use Rust by Example or Rustlings to reinforce syntax. After that, keep the standard library docs and Cargo Book nearby for everyday development. When compiler messages block progress, use the Compiler Error Index and rustc Book. When a program’s domain becomes specialized, branch into the Command Line Book, Embedded Book, or other domain material.

For an advanced reader, the path is question-driven. If the question is about stable semantics, prefer the Reference. If the question involves unsafe invariants, prefer the Rustonomicon. If the question involves #![feature(...)], target-specific ABIs, sanitizer runtime linking, or compiler-recognized language items, use the Unstable Book and follow the tracking issue when one is provided. The repository files here show that unstable pages are expected to document feature names, constraints, and concrete examples, not just list feature gates.

Contributors should treat the documentation map as a stability gradient. Beginner and stable resources optimize for durable concepts and broad applicability. Reference and Nomicon material optimize for precision. Unstable Book pages optimize for traceability from feature metadata to user-visible behavior. When adding or reviewing an unstable feature, check that the generated summary can discover it, that the page explains the intended audience and constraints, and that examples are clearly target-specific when architecture or toolchain assumptions apply.

Next Steps

If you are learning Rust, read the Book first and keep the standard library and Cargo documentation open while building small projects. If you are maintaining documentation, compare any new unstable feature page against the ABI and lang item examples above: name the feature, link or record its tracking status, explain what the compiler or toolchain does, and show a realistic usage pattern. If you are moving from user learning into contribution work, read the compiler architecture and building-from-source pages next so the documentation map connects to the source tree you will edit.