Crate cargo

Cargo as a library

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

• https://docs.rs/cargo: targeted at external tool developers using cargo-the-library
  • Released with every rustc release
• https://doc.rust-lang.org/nightly/nightly-rustc/cargo: targeted at cargo contributors
  • Updated on each update of the cargo submodule in rust-lang/rust

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::resolver: The core algorithm
• 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

• Package
  • Cargo.toml: User-written project manifest, loaded with util::toml::TomlManifest and then translated to core::manifest::Manifest which maybe stored in a core::Package.
    • This is editable with util::toml_mut::manifest::LocalManifest
  • Cargo.lock: Generally loaded with ops::resolve_ws or a variant of it into a core::resolver::Resolve
    • At the lowest level, ops::load_pkg_lockfile and ops::write_pkg_lockfile are used
    • See core::resolver::encode for versioning of Cargo.lock
  • target/: Used for build artifacts and abstracted with core::compiler::layout. Layout handles locking the target directory and providing paths to parts inside. There is a separate Layout for each build target.
    • target/debug/.fingerprint: Tracker whether nor not a crate needs to be rebuilt. See core::compiler::fingerprint
• $CARGO_HOME/:
  • registry/: Package registry cache which is managed in sources::registry. Be careful as the lock util::Config::acquire_package_cache_lock must be manually acquired.
    • index/: Fast-to-access crate metadata (no need to download / extract *.crate files)
    • cache/*/*.crate: Local cache of published crates
    • src/*/*: Extracted from *.crate by sources::registry::RegistrySource
  • git/: Git source cache. See sources::git.
• **/.cargo/config.toml: Environment dependent (env variables, files) configuration. See util::config

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

• pub use crate::util::errors::AlreadyPrintedError;
• pub use crate::util::errors::InternalError;
• pub use crate::util::errors::VerboseError;
• pub use crate::util::indented_lines;
• pub use crate::util::CargoResult;
• pub use crate::util::CliError;
• pub use crate::util::CliResult;
• pub use crate::util::Config;

Modules

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

Macros

• __shell_print
• drop_eprint
• drop_eprintln
• drop_print
• drop_println
• try_old_curl
  When dynamically linked against libcurl, we want to ignore some failures when using old versions that don’t support certain features.
• try_old_curl_http2_pipewait
  Enable HTTP/2 and pipewait to be used as it’ll allow true multiplexing which makes downloads much faster.

Constants

• CARGO_ENV

Functions

• _display_error 🔒
• display_error
  Displays an error, and all its causes, to stderr.
• display_warning_with_error
  Displays a warning, with an error object providing detailed information and context.
• exit_with_error
• version
  Returns information about cargo’s version.