OpenWikirust-lang/rust

Cargo Commands

Purpose and Scope

Cargo is the Rust package manager and build tool, and the Rust repository treats it as part of the normal developer experience rather than as an optional add-on. The repository README names Cargo alongside rustfmt, Clippy, and rust-analyzer as advanced tooling that supports productivity, while also explaining that this repository contains the compiler, standard library, and documentation. For readers coming from the official Cargo Book command index, the important connection is that Cargo commands are not only for application crates; they also shape how a large Rust workspace declares packages, builds tools, and delegates work during compiler bootstrapping.

Sources: README.md, Cargo.toml, src/bootstrap/README.md

The official Cargo command index groups commands into families: general commands, build commands, manifest commands, package commands, publishing commands, report commands, and deprecated or removed commands. This page explains that taxonomy through the source tree you are reading. In ordinary projects, these families answer questions such as “what package am I in?”, “how do I compile or test it?”, “how is its manifest represented?”, and “how would it be published or inspected?”. In rust-lang/rust, the same ideas appear at repository scale: one root workspace manifest coordinates compiler, library, documentation, and tool crates, while bootstrap uses Cargo to perform much of the actual Rust compilation work.

Relevant Source Files

  • README.md - identifies this repository as the main Rust source tree and explicitly describes Cargo as Rust's package manager and build tool in the productivity tooling set.
  • Cargo.toml - defines the root Cargo workspace, member crates, excluded paths, package-specific profiles, and patch guidance that determine how Cargo sees this repository.
  • src/bootstrap/README.md - explains how the bootstrap build system relies on Cargo for complicated rustc and rustdoc invocations while handling staging and artifact movement itself.

Command Families in Practice

Cargo's command families are easiest to understand as layers around a package graph. General commands help a user discover or initialize work. Build commands compile, check, test, run, document, and clean packages. Manifest commands interpret or modify the package manifest. Package commands prepare local package artifacts. Publishing commands communicate with crates.io or another registry. Report commands expose metadata, dependency trees, and other state. The official command index presents these as separate chapters, but a real repository often uses several families together in a single workflow.

In the Rust repository, the package graph begins with the root Cargo.toml. It declares [workspace], sets resolver = "2", and lists many workspace members, including compiler/rustc, src/build_helper, src/rustdoc-json-types, and many tools under src/tools. That structure is the concrete reason Cargo commands can target separate packages while still sharing one workspace. A cargo check -p rustc-style mental model depends on the manifest's package membership, while metadata-oriented commands derive their view from the same source.

Sources: Cargo.toml

The same manifest also shows that command behavior is shaped by more than the member list. It excludes paths such as build, compiler/rustc_codegen_cranelift, compiler/rustc_codegen_gcc, src/bootstrap, tests/rustdoc-gui, and obj. Exclusion matters because Cargo commands operate on the workspace as Cargo understands it, not simply on every directory containing Rust code. In a large monorepo, an excluded path can still be important to the project, but it is intentionally outside the root workspace command surface unless invoked through another build path.

Sources: Cargo.toml

Repository Workflow: Cargo and Bootstrap

For normal Rust users, Cargo commands often directly call rustc, rustdoc, test harnesses, and package tooling behind the scenes. The bootstrap README makes the same relationship explicit for building Rust itself: the build system defers most complicated logic for managing invocations of rustc and rustdoc to Cargo. Bootstrap then adds the repository-specific orchestration that Cargo does not model by itself, such as moving through compiler stages, copying artifacts, applying configured steps, and managing outputs under the build directory.

Sources: src/bootstrap/README.md

This division of responsibility is central to understanding which command to reach for. Cargo understands packages, manifests, dependency resolution, profiles, rustc invocations, rustdoc invocations, and build artifacts. Bootstrap understands how a compiler is built using an earlier compiler, how stage0 binaries are acquired, how stage1 and stage2 compilers are produced, and how distribution artifacts are organized. If you are working on an ordinary crate in the workspace, a Cargo command may be enough. If you are building the compiler, standard library, or distribution artifacts as Rust project deliverables, the repository's x bootstrap entry points are the intended high-level interface.

The bootstrap README describes a staged flow. First, an entry point script such as x, x.ps1, or x.py downloads stage0 compiler and Cargo binaries, compiles the bootstrap build system, and invokes the bootstrap binary. Then the bootstrap binary reads configuration, performs sanity checks, and prepares a stage1 compiler and libraries using the prebuilt stage0 compiler. Finally, the stage0 compiler and standard library build the stage1 compiler, the stage1 compiler builds the stage1 standard library, and the stage1 compiler is used again to produce the stage2 compiler. Cargo participates in that process, but bootstrap decides the stage ordering.

Sources: src/bootstrap/README.md

A useful way to read this repository is therefore to separate “Cargo commands as package operations” from “bootstrap commands as Rust-distribution operations.” Cargo remains the engine for many Rust crate builds; bootstrap is the conductor for compiler stages and artifact layout. This is why src/bootstrap is excluded from the root workspace manifest even though bootstrap itself is crucial. It is built and run as part of a special early phase using the downloaded stage0 Cargo and rustc, rather than being treated as just another workspace member in the top-level package graph.

Sources: Cargo.toml, src/bootstrap/README.md

Compact Command-Family Reference

  • General commands: use these to discover help, create a package, or inspect the installed Cargo tool. In this repository, the README points new users to official installation and learning resources before source-build workflows.
  • Build commands: use these to compile, check, test, run, document, or clean packages. In rust-lang/rust, build activity is split between ordinary Cargo package operations and bootstrap-managed compiler-stage operations.
  • Manifest commands: use these when the central artifact is Cargo.toml, package metadata, dependency declarations, or workspace configuration. The root Cargo.toml is the source of workspace membership and exclusions.
  • Package commands: use these to assemble package artifacts from manifest-described crates. The Rust repository contains many workspace crates and tools, but distribution of Rust itself is managed through bootstrap and release infrastructure rather than by publishing the whole repository as one crate.
  • Publishing commands: use these for registry workflows such as crates.io publication. The root manifest includes patch guidance for local modifications, including a note that git dependencies require an allowed-source update in tidy configuration, which signals that dependency sources are controlled in this repository.
  • Report commands: use these to inspect metadata, package trees, and build state. In a workspace with compiler crates, standard-library workspace crates, rustdoc tools, and test utilities, report commands are often the safest way to understand what Cargo believes the package graph contains before changing build behavior.

Sources: README.md, Cargo.toml, src/bootstrap/README.md

The root manifest includes package-specific profile settings that also matter to command behavior. For example, it changes overflow checks for rustc_thread_pool, strips or reduces debug information for wrapper packages, and raises optimization for test-float-parse. These settings are not separate commands, but they modify the result of build-family commands by changing how selected packages are compiled in dev or release profiles. When a Cargo build command produces surprising output, profiles and package overrides in Cargo.toml are part of the command's effective configuration.

Sources: Cargo.toml

The manifest also includes a commented [patch.crates-io] section with guidance for using a crate with local modifications. That is a practical bridge between manifest commands and day-to-day development. A developer may edit the manifest to point a dependency at a local path or git source, then run build or report commands to verify resolution. The note about adding git sources to an allowed-source list underscores a repository policy: dependency changes are not only Cargo syntax; they are reviewed as part of the Rust project's supply-chain and tidy checks.

Sources: Cargo.toml

Execution Flow Examples

For a small Rust project, a typical Cargo sequence might be cargo new, cargo build, cargo test, cargo doc, and eventually cargo publish. In this repository, the analogous work is distributed. A contributor may inspect Cargo.toml to find the relevant workspace member, use Cargo concepts to understand package boundaries, and then rely on repository-specific bootstrap commands when the task crosses into compiler staging, standard-library building, rustdoc distribution, or multi-step test orchestration. The official command families still provide the vocabulary, but the repository adds scale and staging constraints.

Sources: Cargo.toml, src/bootstrap/README.md

A practical reading path is to begin with the README's positioning: Rust is a language project with compiler, standard library, documentation, and first-party tools. Then inspect the root workspace manifest to see which crates Cargo can reason about directly from the top level. Finally, read the bootstrap README before attempting source builds, because it explains why building Rust is not the same as running a single Cargo command over the workspace. That sequence helps avoid a common misunderstanding: Cargo is essential here, but it is deliberately embedded inside a larger bootstrap system.

Sources: README.md, Cargo.toml, src/bootstrap/README.md

Next Steps

If your goal is to learn Cargo as an end user, continue with the official Cargo Book command chapters and practice on a small package before applying the same concepts to this repository. If your goal is to contribute to Rust itself, treat Cargo knowledge as necessary background and then follow the source-build and bootstrap documentation. For workspace-oriented changes, keep Cargo.toml close at hand; for compiler or distribution changes, read the bootstrap flow before assuming that a direct Cargo invocation is the supported entry point.

Ask a question...