Crate cargo

source ·
Expand description

Cargo as a library

There are two places you can find API documentation of cargo-the-library,

WARNING: Using Cargo as a library has drawbacks, particularly the API is unstable, and there is no clear path to stabilize it soon at the time of writing. See The Cargo Book: External tools for more on this topic.

Overview

Major components of cargo include:

  • ops: Every major operation is implemented here. Each command is a thin wrapper around ops.
    • ops::cargo_compile: 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.
  • ops::resolve: Top-level API for dependency and feature resolver (e.g. ops::resolve_ws)
  • core::compiler: This is the code responsible for running rustc and rustdoc.
    • core::compiler::build_context: 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.
    • 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.
    • core::compiler::fingerprint: The fingerprint module contains all the code that handles detecting if a crate needs to be recompiled.
  • sources::source: The sources::source::Source trait is an abstraction over different sources of packages. Sources are uniquely identified by a core::SourceId. Sources are implemented in the sources directory.
  • util: This directory contains generally-useful utility modules.
  • util::config: This directory contains the config parser. It makes heavy use of serde to merge and translate config values. The util::Config is usually accessed from the core::Workspace though references to it are scattered around for more convenient access.
  • util::toml: This directory contains the code for parsing Cargo.toml files.
    • ops::lockfile: This is where Cargo.lock files are loaded and saved.

Related crates:

  • cargo-platform (nightly docs): This library handles parsing cfg expressions.
  • cargo-util (nightly docs): This contains general utility code that is shared between cargo and the testsuite
  • crates-io (nightly docs): This contains code for accessing the crates.io API.
  • home: This library is shared between cargo and rustup and is used for finding their home directories. This is not directly depended upon with a path dependency; cargo uses the version from crates.io. It is intended to be versioned and published independently of Rust’s release system. Whenever a change needs to be made, bump the version in Cargo.toml and cargo publish it manually, and then update cargo’s Cargo.toml to depend on the new version.
  • cargo-test-support (nightly docs): This contains a variety of code to support writing tests
  • cargo-test-macro (nightly docs): This is the #[cargo_test] proc-macro used by the test suite to define tests.
  • credential This subdirectory contains several packages for implementing the credential providers.
  • mdman (nightly docs): This is a utility for generating cargo’s man pages. See Building the man pages for more information.
  • resolver-tests This is a dedicated package that defines tests for the dependency resolver.

File Overview

Files that interact with cargo include

Contribute to Cargo documentations

The Cargo team always continues improving all external and internal documentations. If you spot anything could be better, don’t hesitate to discuss with the team on Zulip t-cargo stream, or submit an issue right on GitHub. There is also an issue label A-documenting-cargo-itself, which is generally for documenting user-facing The Cargo Book, but the Cargo team is welcome any form of enhancement for the Cargo Contributor Guide and this API documentation as well.

Re-exports

Modules

  • macros 🔒
  • The trait for sources of Cargo packages and its built-in implementations.
  • version 🔒
    Code for representing cargo’s release version number.

Macros

Constants

Functions