docs(contrib): Create a file overview in the nightly docs

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;

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;

src/cargo/lib.rs

@@ -22,6 +22,8 @@
 //!
 //! ## Overview
 //!
+//! Major components of cargo include:
+//!
 //! - [`ops`]:
 //!   Every major operation is implemented here. Each command is a thin wrapper around ops.
 //!   - [`ops::cargo_compile`]:
@@ -96,6 +98,29 @@
 //!   This is a dedicated package that defines tests for the [dependency
 //!   resolver][core::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.

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