Auto merge of #11850 - epage:file, r=weihanglo

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.

Author: bors

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