# Crate cargo

source
Expand description

## §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`

> This library is maintained by the Cargo team, primarily for use by Cargo and not intended for external use (except as a transitive dependency). This crate may make major changes to its APIs. 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 `BuildRunner`.
  - `core::compiler::build_runner`: 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::context`: This directory contains the global application context. This includes the config parser which makes heavy use of serde to merge and translate config values. The `util::GlobalContext` 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
- `cargo-util-schemas` (nightly docs): This contains the serde schemas for cargo
- `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.
- `rustfix` (nightly docs): This defines structures that represent fix suggestions from rustc, as well as generates “fixed” code from suggestions. Operations in `rustfix` are all in memory and won’t write to disks.
- `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::read_manifest` 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::GlobalContext::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::context`

### §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::GlobalContext;`

## 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.