From a980c085c05708801816c23a815af7af8362ee36 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 13 Mar 2023 19:50:46 -0500 Subject: [PATCH] docs(contrib): Create a file overview in the nightly docs This is a follow up to #11809. On top of what was in the old contrib, I added links out for `.cargo/config.toml`. I'm assuming there are more files that would be worth indexing here but we can add those over time. My focus was on linking to the high-detail documentation. In some cases, this meant increasing visibility to make rustdoc happy. In the registry case, `sources::registry` is a great document to link to so I instead dropped links that rustdoc couldn't handle as they were to details covered in the bigger document or can easily be derived from it. The rest of the file docs will need to be handled in a different way as they are details for people implementing file system interactions. --- src/cargo/core/compiler/mod.rs | 2 +- src/cargo/core/resolver/mod.rs | 2 +- src/cargo/lib.rs | 21 +++++++++++ src/doc/contrib/src/architecture/files.md | 44 +---------------------- 4 files changed, 24 insertions(+), 45 deletions(-) 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