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 inrust-lang/rust
- Updated on each update of the
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 runningrustc
andrustdoc
.core::compiler::build_context
: TheBuildContext
is the result of the “front end” of the build process. This contains the graph of work to perform and any settings necessary forrustc
. After this is built, the next stage of building is handled inContext
.core::compiler::context
: TheContext
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
: Thefingerprint
module contains all the code that handles detecting if a crate needs to be recompiled.
sources::source
: Thesources::source::Source
trait is an abstraction over different sources of packages. Sources are uniquely identified by acore::SourceId
. Sources are implemented in thesources
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. Theutil::Config
is usually accessed from thecore::Workspace
though references to it are scattered around for more convenient access.util::toml
: This directory contains the code for parsingCargo.toml
files.ops::lockfile
: This is whereCargo.lock
files are loaded and saved.
Related crates:
cargo-platform
(nightly docs): This library handles parsingcfg
expressions.cargo-util
(nightly docs): This contains general utility code that is shared between cargo and the testsuitecrates-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 apath
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 andcargo publish
it manually, and then update cargo’sCargo.toml
to depend on the new version.cargo-test-support
(nightly docs): This contains a variety of code to support writing testscargo-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 withutil::toml::TomlManifest
and then translated tocore::manifest::Manifest
which maybe stored in acore::Package
.- This is editable with
util::toml_mut::manifest::LocalManifest
- This is editable with
Cargo.lock
: Generally loaded withops::resolve_ws
or a variant of it into acore::resolver::Resolve
- At the lowest level,
ops::load_pkg_lockfile
andops::write_pkg_lockfile
are used - See
core::resolver::encode
for versioning ofCargo.lock
- At the lowest level,
target/
: Used for build artifacts and abstracted withcore::compiler::layout
.Layout
handles locking the target directory and providing paths to parts inside. There is a separateLayout
for each buildtarget
.target/debug/.fingerprint
: Tracker whether nor not a crate needs to be rebuilt. Seecore::compiler::fingerprint
$CARGO_HOME/
:registry/
: Package registry cache which is managed insources::registry
. Be careful as the lockutil::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 cratessrc/*/*
: Extracted from*.crate
bysources::registry::RegistrySource
git/
: Git source cache. Seesources::git
.
**/.cargo/config.toml
: Environment dependent (env variables, files) configuration. Seeutil::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
- macros 🔒
- The trait for sources of Cargo packages and its built-in implementations.
- version 🔒Code for representing cargo’s release version number.
Macros
- When dynamically linked against libcurl, we want to ignore some failures when using old versions that don’t support certain features.
- Enable HTTP/2 and pipewait to be used as it’ll allow true multiplexing which makes downloads much faster.
Constants
Functions
- Displays an error, and all its causes, to stderr.
- Displays a warning, with an error object providing detailed information and context.
- Returns information about cargo’s version.