Manifests and Workspaces

Purpose and Scope

A Cargo manifest is the TOML file that describes a Rust package or workspace to Cargo. For an ordinary project, that file is usually Cargo.toml beside the crate source. In this repository, the root Cargo.toml is not a simple single-package manifest; it is the coordination point for a large Cargo workspace that groups the compiler crate, in-tree tools, support crates, and distribution utilities under one dependency-resolution model. Understanding it helps contributors know which parts of the tree Cargo can build together and which parts are intentionally managed outside the root workspace.

The manifest also shows that a Rust repository may have more than one package ecosystem in play. Rust itself is implemented primarily in Rust, but the root also contains package.json for JavaScript and TypeScript-based tooling dependencies. That file is not a Cargo manifest, but it matters operationally because some repository workflows, such as browser UI testing or linting frontend assets, depend on Node packages. A contributor reading the root should therefore treat Cargo.toml as the Rust workspace authority and package.json as a separate toolchain manifest for non-Rust support code.

Sources: Cargo.toml, package.json

Relevant Source Files

• Cargo.toml — Declares the root Cargo workspace, workspace resolver, member crates and tools, excluded directories, package-specific profile overrides, and the placeholder for patching crates.io dependencies.
• package.json — Declares JavaScript and TypeScript tooling dependencies used by repository workflows, including browser-ui-test, es-check, eslint, and typescript.

Workspace Structure in the Root Manifest

The root manifest starts with a [workspace] table and sets resolver = "2". In Cargo terminology, the resolver controls how dependency features are selected across the workspace. Resolver version 2 is the modern behavior used by edition-aware workspaces to avoid some unwanted feature unification across build, dev, target-specific, and normal dependencies. The important practical point for contributors is that dependency behavior is chosen once at the workspace root, so adding or moving a crate inside the workspace must be compatible with the repository-wide resolver rather than an isolated local assumption.

The members list is the clearest map of what the repository treats as workspace-managed Rust packages. It includes the compiler entry crate compiler/rustc, helper crates such as src/build_helper, workspace shim crates for the standard library under src/rustc-std-workspace, rustdoc JSON types, and a long set of tools under src/tools. That list includes familiar tools such as clippy, compiletest, miri, rustdoc, rustfmt, tidy, and x. Because these are members, Cargo can reason about them as part of one coordinated workspace graph rather than as unrelated packages.

The manifest marks the member list with tidy-alphabetical-start and tidy-alphabetical-end comments. That is a repository convention rather than a Cargo feature, but it communicates an important maintenance rule: the workspace membership list is expected to remain orderly and machine-checkable. When adding a new in-tree tool or support crate, contributors should not only add a path; they should place it consistently with the existing list so repository checks can keep the manifest maintainable over time.

Sources: Cargo.toml

Excluded Paths and Why They Matter

The root manifest also has an exclude list. In Cargo, excluding a path from a workspace prevents Cargo from treating it as part of the root workspace even if it contains a manifest below the repository tree. Here, exclusions include generated or build-output-like directories such as build, the bootstrap system in src/bootstrap, GUI rustdoc tests under tests/rustdoc-gui, the CI-related obj directory, and alternative codegen backend directories compiler/rustc_codegen_cranelift and compiler/rustc_codegen_gcc. The comment beside obj explains that CI uses /checkout/obj, so the manifest hardcodes that operational reality.

These exclusions are useful because not every Rust package in the source tree should participate in the same Cargo workspace. Some directories have their own build procedures, their own dependency constraints, or are generated during the build. If they were included accidentally, workspace commands could attempt to resolve, build, or test crates that are not meant to share the root resolver and profile settings. In a repository as large as Rust, workspace boundaries are not merely organizational; they protect build reproducibility and keep contributor workflows aligned with the bootstrap and CI systems.

Sources: Cargo.toml

Profiles, Package Overrides, and Dependency Patching

The manifest contains several package-specific profile overrides. For rustc_thread_pool under profile.release.package, overflow checks are disabled as a workaround for intermittent CI overflows related to deadlock detection. The comments explicitly connect this choice to Rust issue 90227 and state that the workaround should be removed once the underlying issue is fixed. This is a good example of a manifest encoding project policy: build behavior is not only about optimization, but also about making the continuous integration environment reliable enough for day-to-day development.

Other profile overrides focus on distribution size and test performance. The lld-wrapper and wasm-component-ld-wrapper packages have release debug information removed and stripping enabled because they are thin wrappers shipped in every rustc tarball, so their compressed and on-disk size affects every user download. The test-float-parse package is optimized in both dev and release profiles because bigint libraries are slow without optimization. These settings show that a workspace manifest can express fine-grained tradeoffs for individual packages while still keeping the global workspace centralized.

At the end of the root manifest, the commented [patch.crates-io] section documents how contributors can temporarily use a crate with local modifications or a git dependency. The accompanying comment warns that git dependency sources must also be added to ALLOWED_SOURCES in the repository's tidy external dependency checks. Even though the patch table is commented out by default, it is an important operational hook: it gives contributors a known place to redirect dependency resolution during development without permanently changing the dependency source for the entire project.

Sources: Cargo.toml

Non-Rust Tooling Manifest

The repository root also contains package.json, a separate manifest for Node-based tooling. Its dependencies table lists browser-ui-test, es-check, eslint, and typescript. This is much smaller than the Cargo workspace manifest, but it signals that some workflows need JavaScript tooling alongside Rust tooling. For example, browser-oriented tests and JavaScript compatibility checks are naturally expressed through npm packages rather than Cargo crates.

Do not confuse the two manifests. Cargo.toml controls Rust packages, workspace membership, Cargo dependency resolution, and Cargo build profiles. package.json controls Node package dependencies used by supporting scripts and tests. They coexist at the repository root because the Rust project ships more than a compiler binary; it also maintains documentation, UI-facing tests, generated assets, and developer tools. When a change touches frontend-style test infrastructure, package.json may be relevant even if the main compiler or library work is still driven by Cargo and bootstrap commands.

Sources: package.json

Compact Reference

Manifest	Key entries	What they mean
Cargo.toml	[workspace]	Root Cargo workspace definition for repository-managed Rust crates.
Cargo.toml	resolver = "2"	Workspace-wide Cargo feature resolver selection.
Cargo.toml	members = [...]	Included workspace packages such as compiler/rustc, src/tools/rustdoc, src/tools/rustfmt, src/tools/miri, and src/tools/x.
Cargo.toml	exclude = [...]	Paths intentionally left outside the root workspace, including src/bootstrap, alternative backend trees, build output, and selected tests.
Cargo.toml	[profile.release.package.*] and [profile.dev.package.*]	Package-specific build settings for reliability, size, and speed.
Cargo.toml	commented [patch.crates-io]	Local or git dependency override hook for contributor development.
package.json	dependencies	Node tooling dependencies: browser-ui-test, es-check, eslint, and typescript.

Contributor Workflow

When adding a new Rust crate to this repository, first decide whether it belongs in the root Cargo workspace. A tool or support crate that should share the root dependency graph belongs in members; a subsystem with an independent build flow may need to remain outside and, if necessary, be listed in exclude. After editing the manifest, keep the member list ordered according to the tidy comments and consider whether profile overrides or dependency patches are truly repository-wide decisions rather than local development conveniences.

For day-to-day reading, use the root Cargo.toml as the workspace map and package.json as the Node tooling map. If your task is about Cargo packages, start with the workspace member list and follow the relevant path. If your task is about browser UI tests, JavaScript linting, ECMAScript compatibility, or TypeScript support, inspect the Node dependencies before assuming Cargo is the only build surface. Related pages to read next are Cargo Getting Started, Cargo Commands, Building Rust from Source, and Testing and CI.