diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs index 2699a2a216d5..7b43fd27d999 100644 --- a/src/cargo/core/compiler/mod.rs +++ b/src/cargo/core/compiler/mod.rs @@ -43,7 +43,7 @@ mod custom_build; pub(crate) mod fingerprint; pub mod future_incompat; pub(crate) mod job_queue; -mod layout; +pub(crate) mod layout; mod links; mod lto; mod output_depinfo; diff --git a/src/cargo/core/resolver/mod.rs b/src/cargo/core/resolver/mod.rs index a26eed7aa67b..ee848ac51eaf 100644 --- a/src/cargo/core/resolver/mod.rs +++ b/src/cargo/core/resolver/mod.rs @@ -78,7 +78,7 @@ pub use self::version_prefs::{VersionOrdering, VersionPreferences}; mod conflict_cache; mod context; mod dep_cache; -mod encode; +pub(crate) mod encode; pub(crate) mod errors; pub mod features; mod resolve; diff --git a/src/cargo/lib.rs b/src/cargo/lib.rs index cd60880bf1fb..1e3087e893e0 100644 --- a/src/cargo/lib.rs +++ b/src/cargo/lib.rs @@ -96,6 +96,27 @@ //! This is a dedicated package that defines tests for the [dependency //! resolver][core::resolver]. //! +//! ### File Overview +//! +//! - 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`: What the developer `cargo publish`ed. +//! - `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. diff --git a/src/doc/contrib/src/architecture/files.md b/src/doc/contrib/src/architecture/files.md index 2e6e02b07905..3d0632a5fde8 100644 --- a/src/doc/contrib/src/architecture/files.md +++ b/src/doc/contrib/src/architecture/files.md @@ -1,48 +1,6 @@ # Files -This chapter gives some pointers on where to start looking at Cargo's on-disk -data file structures. - -* [`Layout`] is the abstraction for the `target` directory. It handles locking - the target directory, and providing paths to the parts inside. There is a - separate `Layout` for each "target". -* [`Resolve`] contains the contents of the `Cargo.lock` file. See the [`encode`] - module for the different `Cargo.lock` formats. -* [`TomlManifest`] contains the contents of the `Cargo.toml` file. It is translated - to a [`Manifest`] object for some simplification, and the `Manifest` is stored - in a [`Package`]. -* The [`fingerprint`] module deals with the fingerprint information stored in - `target/debug/.fingerprint`. This tracks whether or not a crate needs to be - rebuilt. -* `cargo install` tracks its installed files with some metadata in - `$CARGO_HOME`. The metadata is managed in the - [`common_for_install_and_uninstall`] module. -* Git sources are cached in `$CARGO_HOME/git`. The code for this cache is in - the [`git`] source module. -* Registries are cached in `$CARGO_HOME/registry`. There are three parts, the - index, the compressed `.crate` files, and the extracted sources of those - crate files. - * Management of the registry cache can be found in the [`registry`] source - module. Note that this includes an on-disk cache as an optimization for - accessing the git repository. - * Saving of `.crate` files is handled by the [`RemoteRegistry`]. - * Extraction of `.crate` files is handled by the [`RegistrySource`]. - * There is a lock for the package cache. Code must be careful, because - this lock must be obtained manually. See - [`Config::acquire_package_cache_lock`]. - -[`Layout`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/layout.rs -[`Resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/resolve.rs -[`encode`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/encode.rs -[`TomlManifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/toml/mod.rs -[`Manifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/manifest.rs -[`Package`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package.rs -[`common_for_install_and_uninstall`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/common_for_install_and_uninstall.rs -[`git`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources/git -[`registry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs -[`RemoteRegistry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/remote.rs -[`RegistrySource`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs -[`Config::acquire_package_cache_lock`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1261-L1266 +See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html) ## Filesystems