Overview
Purpose and Scope
This page orients new readers to the Rust repository as the upstream source tree for the Rust programming language implementation. The repository README states the central scope directly: this is the main source code repository for Rust, and it contains the compiler, the standard library, and documentation. That framing matters because many readers arrive with different goals. Some want to install Rust and write programs, some want to understand the compiler, and some want to contribute to first-party tools. The repository is therefore both a product source tree and an entry point into the larger Rust documentation ecosystem.
Sources: README.md
The README presents Rust around three user-facing promises: performance, reliability, and productivity. Performance is described in terms of fast, memory-efficient systems software that can fit critical services, embedded devices, and interoperability with other languages. Reliability is tied to the type system and ownership model, which are intended to catch memory and thread-safety problems at compile time. Productivity is connected to documentation, diagnostics, Cargo, rustfmt, Clippy, and rust-analyzer. In other words, the repository is not only a compiler checkout; it is the root of a coordinated language, library, documentation, and tooling distribution.
Sources: README.md
For most users, the first action should not be cloning and building this repository. The README’s Quick Start sends readers to the Installation chapter of The Rust Programming Language, and its source-installation note explicitly says installing from source is not recommended for ordinary setup. That distinction is important for docs navigation: installation and learning pages should use the public Rust documentation path, while contributor and implementation pages should use this repository’s source layout and build system. Treat this repository as the authoritative implementation source, not as the beginner installation mechanism.
Sources: README.md
Relevant Source Files
- README.md — Defines the repository’s public identity, links to the Rust website, Getting Started, Learn, Documentation, and Contributing pages, summarizes Rust’s main value propositions, and points readers toward installation, help, contribution, licensing, and trademark information.
- Cargo.toml — Defines the top-level Cargo workspace, including the rustc crate and many first-party tools under src/tools, while also recording selected workspace exclusions and package-specific profile overrides.
System-to-Code Mapping
At the highest level, the README names three major bodies of work: compiler, standard library, and documentation. The root Cargo workspace then gives a concrete source-level view into how parts of that work are organized for Cargo-based development. Its members include compiler/rustc, standard-library workspace support crates under src/rustc-std-workspace, rustdoc JSON types, and a broad set of tools under src/tools. This mapping is useful because it turns the README’s broad description into navigable areas: compiler work starts around compiler/rustc, documentation generation connects to rustdoc-related tools, and distribution or validation tasks are represented by specialized workspace tools.
Sources: README.md, Cargo.toml
The workspace list also shows that the Rust repository carries more than the language compiler itself. It includes tools such as src/tools/rustdoc, src/tools/rustfmt, src/tools/clippy, src/tools/miri, src/tools/compiletest, src/tools/tidy, src/tools/linkchecker, and src/tools/x. Those names align with the README’s productivity emphasis: Rust is distributed with documentation tooling, formatting, linting, testing infrastructure, and editor-facing support elsewhere in the ecosystem. A reader should expect many repository tasks to involve these tools rather than a single monolithic compiler binary.
Sources: README.md, Cargo.toml
The root manifest also uses workspace exclusions for areas such as build, compiler/rustc_codegen_cranelift, compiler/rustc_codegen_gcc, src/bootstrap, tests/rustdoc-gui, and obj. An exclusion does not mean those directories are unrelated to Rust; it means they are not ordinary members of the root Cargo workspace. This is a practical distinction for contributors. Some subsystems are built through bootstrap or their own workflows rather than as normal workspace packages. When a command behaves differently in one of those areas, first check whether it is managed by the root workspace, by bootstrap, or by a subsystem-specific script.
Sources: Cargo.toml
| Reader goal | Start here | Why it matters |
|---|---|---|
| Learn Rust as a language user | README.md links to Getting Started, Learn, Documentation, and The Book installation chapter | The repository directs users to the official learning path before source builds |
| Understand the compiler implementation | README.md contribution section and Cargo.toml workspace member compiler/rustc | rustc is a first-class workspace package and the README points to the rustc-dev-guide for architecture |
| Explore first-party tools | Cargo.toml workspace members under src/tools | Tooling such as rustdoc, rustfmt, Clippy, Miri, compiletest, and tidy is represented in the workspace |
| Contribute to the repository | README.md Contributing section and Cargo.toml workspace layout | Contribution work depends on understanding both public guidance and the workspace organization |
Documentation and Learning Entry Points
The README’s link strip is a compact documentation map: Website, Getting started, Learn, Documentation, and Contributing. Use those links as the first layer of navigation. Getting Started is the setup-oriented path for installing Rust and beginning development. Learn collects educational resources such as tutorial material and examples. Documentation is the usage-oriented reference area for the language, standard library, compiler, Cargo, and tools. Contributing is the path for people changing the repository itself. This separation helps prevent a common confusion: product documentation teaches Rust, while repository documentation teaches how Rust is built.
Sources: README.md
The README specifically points beginners to The Book’s Installation chapter for quick start. That signal matches the official Rust documentation spine: The Book is the primary tutorial, Rust By Example is the runnable-example path, and the rustc book explains compiler invocation for readers who need direct compiler control. This overview uses those resources as orientation, but the repository source evidence for the entry points is the README. If you are deciding what to read next, choose based on task: The Book for learning the language, Rust By Example for examples, rustc documentation for compiler flags, and repository contributor docs for source changes.
Sources: README.md
The Contributing section makes one especially important distinction for implementation readers: it points to CONTRIBUTING.md for process and to the rustc-dev-guide for a detailed explanation of compiler architecture and how to begin contributing. That means compiler architecture documentation is intentionally not all contained in the root README. The README acts as a routing page, while deeper explanations live in specialized guides. For OpenWiki navigation, overview pages should therefore introduce the repository and then hand off to focused pages on rustc, standard library layers, Cargo manifests, bootstrap, codegen, tests, and tools.
Sources: README.md
Workspace Shape and Operational Signals
Cargo.toml shows the repository using Cargo workspace resolver version 2. That is a concrete signal that many Rust packages in this tree are coordinated as a single workspace for dependency resolution and package operations. The member list is alphabetized under tidy comments, which also hints at repository hygiene conventions: tooling enforces organization, not just compilation. Contributors changing workspace membership should expect tidy-related checks and should preserve the structure rather than treating the manifest as an ad hoc list.
Sources: Cargo.toml
The manifest includes package-specific profile overrides that reveal operational constraints. For example, release builds of rustc_thread_pool disable overflow checks because the rustc fork of Rayon has deadlock detection code that intermittently causes overflows in CI. The lld-wrapper and wasm-component-ld-wrapper release profiles reduce debug information and strip binaries because they are thin wrappers shipped in rustc tarballs and add download and disk size. These comments show that the root manifest encodes distribution and CI tradeoffs, not only local developer preferences.
Sources: Cargo.toml
The test-float-parse package receives optimization in both dev and release profiles because bigint libraries are slow without optimization, and release also uses a single codegen unit while noting that LTO cannot be enabled for binaries in a workspace. These details are valuable when diagnosing performance or CI behavior: build profiles may be intentionally uneven across packages. If a package behaves differently from default Cargo expectations, inspect the root manifest before assuming a local configuration problem.
Sources: Cargo.toml
Practical Navigation
A practical first pass through the repository starts with purpose, then narrows to task. If you are learning Rust, follow the README’s public documentation links instead of trying to infer language concepts from compiler code. If you are investigating the compiler, begin with the rustc overview and the rustc-dev-guide link called out by the README. If you are examining standard library behavior, use the standard library pages and then inspect library crates. If you are working on tools, locate the relevant src/tools workspace member and check whether it is a normal workspace package or has a specialized workflow.
Sources: README.md, Cargo.toml
The next step after this overview is to choose a more specific page. New users should read Install Rust or the Learning and Documentation Map. Contributors should read Building Rust from Source, Compiler Architecture, and Testing and CI. Tool users should continue to the rustc, rustdoc, Cargo, or rust-analyzer pages depending on the command or editor integration they need. Keep the README’s division in mind: the repository introduces Rust’s implementation and points outward to official learning material, while the root Cargo manifest shows how many implementation and tooling components are wired together for development.
Sources: README.md, Cargo.toml