Codebase Overview

This is a very high-level overview of the Cargo codebase.

  • src/bin/cargo — Cargo is split in a library and a binary. This is the binary side that handles argument parsing, and then calls into the library to perform the appropriate subcommand. Each Cargo subcommand is a separate module here. See SubCommands.

  • src/cargo/ops — Every major operation is implemented here. This is where the binary CLI usually calls into to perform the appropriate action.

    • src/cargo/ops/cargo_compile.rs — This is the entry point for all the compilation commands. This is a good place to start if you want to follow how compilation starts and flows to completion.
  • src/cargo/core/resolver — This is the dependency and feature resolvers.

  • src/cargo/core/compiler — This is the code responsible for running rustc and rustdoc.

    • src/cargo/core/compiler/build_context/mod.rs — The BuildContext is the result of the "front end" of the build process. This contains the graph of work to perform and any settings necessary for rustc. After this is built, the next stage of building is handled in Context.

    • src/cargo/core/compiler/context — The Context is the mutable state used during the build process. This is the core of the build process, and everything is coordinated through this.

    • src/cargo/core/compiler/fingerprint.rs — The fingerprint module contains all the code that handles detecting if a crate needs to be recompiled.

  • src/cargo/core/source — The Source trait is an abstraction over different sources of packages. Sources are uniquely identified by a SourceId. Sources are implemented in the src/cargo/sources directory.

  • src/cargo/util — This directory contains generally-useful utility modules.

  • src/cargo/util/config — This directory contains the config parser. It makes heavy use of serde to merge and translate config values. The Config is usually accessed from the Workspace, though references to it are scattered around for more convenient access.

  • src/cargo/util/toml — This directory contains the code for parsing Cargo.toml files.

  • src/doc — This directory contains Cargo's documentation and man pages.

  • src/etc — These are files that get distributed in the etc directory in the Rust release. The man pages are auto-generated by a script in the src/doc directory.

  • crates — A collection of independent crates used by Cargo.

Extra crates

Some functionality is split off into separate crates, usually in the crates directory.