Cargo Getting Started

Purpose and Scope

Cargo is the standard package manager and build tool that most Rust users meet immediately after installing the language. The official Cargo getting-started path begins with installing Cargo together with Rust, then creating or opening a first crate. In this repository, Cargo is also a practical lens for understanding the source tree: the root manifest describes a large workspace containing the compiler package, standard-library workspace crates, rustdoc, rustfmt, Clippy, Miri, compiletest, tidy, installer tooling, and many other first-party tools. Sources: README.md, Cargo.toml

The repository README presents Rust as a language supported by comprehensive documentation and advanced tooling, explicitly naming Cargo as the package manager and build tool. That framing matters for new readers because Cargo is not only a command they run after installation; it is also the convention that gives Rust projects a predictable shape. A package has a manifest, a crate is the library or executable target Cargo builds, and workspace membership lets many packages share dependency resolution and build settings. Sources: README.md, Cargo.toml

For a new Rust user, the simplest mental model is that Cargo coordinates three early tasks: create a project, compile it, and run tests or examples as the project grows. For a repository reader, the same model scales upward. The Rust source tree has a root Cargo manifest because many internal components are ordinary Rust packages, even though building the full compiler distribution is normally handled through repository-specific bootstrap tooling rather than a plain one-command Cargo build. Sources: Cargo.toml

Relevant Source Files

• README.md — Introduces this repository as the main source code repository for Rust, links new users to Getting Started and The Book, and names Cargo as Rust's package manager and build tool.
• Cargo.toml — Defines the root Cargo workspace, resolver, workspace members, excluded paths, profile overrides, and patch guidance used by packages in this source tree.

Core Primitives

A Cargo package is described by a manifest, conventionally named Cargo.toml. The official Cargo glossary defines the manifest as the configuration file for a package, and the root manifest in this repository demonstrates the workspace form of that file. Instead of describing a single small application, it declares a workspace with resolver version two and a curated list of member packages. This tells Cargo which packages participate together when commands are run from the root and gives maintainers a central place for shared settings. Sources: Cargo.toml

A crate is the compilation unit Cargo ultimately asks rustc to build. The official glossary describes a crate as either a library or executable program, and each package target is a crate. In this repository, workspace members include crates for compiler entry points, developer tools, test infrastructure, documentation generation, and distribution helpers. The member list includes entries such as compiler/rustc, src/tools/rustdoc, src/tools/rustfmt, src/tools/clippy, src/tools/miri, and src/tools/compiletest, showing how Cargo terminology maps to the components contributors see in the tree. Sources: Cargo.toml

A workspace is useful when many related packages need to be developed together. The Rust repository uses that pattern extensively, but it also deliberately excludes some directories from the root workspace. The exclude list names build output, bootstrap, codegen backends, rustdoc GUI tests, and an object directory used by continuous integration. This distinction helps contributors avoid assuming every Rust package-shaped directory is automatically part of root workspace operations. Sources: Cargo.toml

First Steps with Cargo

The official Cargo Book starts its getting-started section with a short sequence: install Cargo and Rust, then set up a first crate. The repository README sends new users to the Rust website, Getting Started, Learn, Documentation, and The Book, with the Quick Start specifically pointing to the installation chapter. That means user installation guidance intentionally lives in the public documentation, while this repository provides the source tree and manifests that advanced users and contributors inspect after they already have the toolchain. Sources: README.md

A beginner project usually starts with a small Cargo command that creates a manifest and source directory. In a simple application, Cargo can then compile, run, test, and document the package using the manifest. The Rust repository is not a minimal example, but the same concepts remain visible. The root manifest identifies packages, selects dependency resolver behavior, and applies profile customizations. Learning Cargo on a small crate first makes the repository's larger workspace easier to interpret later. Sources: Cargo.toml

Typical first-project commands look like this:

rustup default stable
cargo new hello-rust
cd hello-rust
cargo run
cargo test

Those commands are not how the full Rust compiler distribution is normally built from source, but they are the right workflow for learning Cargo itself. After that foundation, contributors can read the root manifest with confidence: workspace members are packages Cargo can reason about, profiles tune compilation behavior for selected packages, and the commented patch section gives a place to substitute local or git dependencies when a crate needs local modifications. Sources: Cargo.toml

Repository Workspace Mapping

The root Cargo.toml begins with a workspace table and sets resolver version two. Resolver selection is important because it controls how Cargo resolves features across workspace packages. In a large repository with tools, compiler crates, and support libraries, feature resolution must be predictable across many packages. The manifest then lists members between tidy-alphabetical markers, making the list both machine-usable by Cargo and maintainable by repository checks that care about ordering. Sources: Cargo.toml

Several member names show how Cargo anchors first-party tools inside the Rust source tree. The workspace includes rustdoc for documentation generation, rustfmt for formatting, clippy for linting, miri and cargo-miri for interpreter-based checking, compiletest for test execution, and tidy for repository hygiene. This supports the README's claim that Rust's productivity story includes a compiler, documentation, diagnostics, package management, formatting, linting, and editor-related tooling as a cohesive ecosystem rather than isolated binaries. Sources: README.md, Cargo.toml

The manifest also contains package-specific profile overrides. For example, it disables overflow checks for the rustc fork of Rayon in a release profile because the comment notes intermittent CI overflows related to deadlock detection. It strips debug information for thin lld wrapper binaries shipped in rustc tarballs, and it increases optimization for a bigint-heavy float parsing test package. These are concrete examples of Cargo being used not only for package discovery, but also for build-performance, artifact-size, and CI-stability decisions. Sources: Cargo.toml

Configuration and Dependency Notes

The commented patch section at the end of the manifest is a useful bridge from beginner Cargo to repository contribution work. Cargo supports patching crates from registries with local paths or git dependencies, and the root manifest explains that local modifications can be placed there. The same comment adds a repository-specific guardrail: git dependencies should also be added to ALLOWED_SOURCES in the tidy external-dependencies logic. Even when the syntax is standard Cargo, this repository layers its own policy checks around dependency changes. Sources: Cargo.toml

The official Cargo documentation also covers support topics that become relevant after the first crate, including glossary terms and git authentication. Those topics explain how manifests, lock files, registries, and git dependencies fit together. In the Rust repository context, they are especially relevant when contributors experiment with dependency overrides or private forks. Cargo can use built-in git support or delegate fetching to the git executable through configuration, but the source evidence here only shows the repository-facing patch guidance rather than a project-specific authentication setup. Sources: Cargo.toml

Practical Reading Path

If you are new to Rust, start outside this repository with the installation chapter linked by the README and then follow the Cargo Book's getting-started pages to create a first crate. After you can run a small package locally, return to this repository and inspect Cargo.toml as a scaled-up example of the same concepts. The key difference is size and policy: the manifest coordinates many first-party packages and contains comments that encode distribution, testing, and contribution constraints. Sources: README.md, Cargo.toml

If you are joining repository development, treat Cargo knowledge as a prerequisite but not the entire build story. Use the manifest to understand package boundaries and tool membership, then follow source-building and contributor documentation for full compiler builds. A good next step is to compare this page with the manifest/workspace page for deeper Cargo.toml structure, then read the building-from-source page for bootstrap-specific commands that sit above ordinary Cargo workflows in this repository. Sources: README.md, Cargo.toml