Refactor Layout into BuildDirLayout and ArtifactDirLayout (#16092)

### What does this PR try to resolve?

After the recent [`build-dir`
changes](#14125), I believe the
`Layout` is now a bit overloaded now and no longer represents a single
thing. For example its not immediately clear if `fn root()` is the root
of the build-dir or artifact-dir.
Also duplicate functions are needed in some cases like `examples()` and
`build_examples()`.

This PR splits the layout into multiple self contained `struct`s while
keeping a high level `Layout` container struct.

Note: I chose the `ArtifactDirLayout` over `TargetDirLayout` as I
believe that is the direction we are going in #6790 and there has been
mention of eventually phasing out target-dir in the long term. (Though
happy to change it if there is a good reason)

### How to test and review this PR?

The existing tests should be sufficient.

Best reviewed commit by commit.

1. The first commit adds a `timings()` to the layout to bring it in line
with other directories in `target`
2. Split `Layout` internally while keeping the pub interface unchanged.
3. Change the `Layout` public interface to expose `.build_dir()` and
`.artifact_dir()` to make it explicit which directory is being used.

Author: weihanglo

src/cargo/core/compiler/build_context/target_info.rs

@@ -1141,7 +1141,7 @@ impl RustDocFingerprint {
 
         let fingerprint_path = build_runner
             .files()
-            .host_root()
+            .host_build_root()
             .join(".rustdoc_fingerprint.json");
         let write_fingerprint = || -> CargoResult<()> {
             paths::write(
@@ -1181,7 +1181,7 @@ impl RustDocFingerprint {
             .bcx
             .all_kinds
             .iter()
-            .map(|kind| build_runner.files().layout(*kind).doc())
+            .map(|kind| build_runner.files().layout(*kind).artifact_dir().doc())
             .filter(|path| path.exists())
             .try_for_each(|path| clean_doc(path))?;
         write_fingerprint()?;

src/cargo/core/compiler/build_runner/compilation_files.rs

@@ -211,13 +211,13 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
         // Docscrape units need to have doc/ set as the out_dir so sources for reverse-dependencies
         // will be put into doc/ and not into deps/ where the *.examples files are stored.
         if unit.mode.is_doc() || unit.mode.is_doc_scrape() {
-            self.layout(unit.kind).doc().to_path_buf()
+            self.layout(unit.kind).artifact_dir().doc().to_path_buf()
         } else if unit.mode.is_doc_test() {
             panic!("doc tests do not have an out dir");
         } else if unit.target.is_custom_build() {
             self.build_script_dir(unit)
         } else if unit.target.is_example() {
-            self.layout(unit.kind).build_examples().to_path_buf()
+            self.layout(unit.kind).build_dir().examples().to_path_buf()
         } else if unit.artifact.is_true() {
             self.artifact_dir(unit)
         } else {
@@ -250,36 +250,41 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
 
     /// Returns the final artifact path for the host (`/…/target/debug`)
     pub fn host_dest(&self) -> &Path {
-        self.host.dest()
+        self.host.artifact_dir().dest()
     }
 
-    /// Returns the root of the build output tree for the host (`/…/target`)
-    pub fn host_root(&self) -> &Path {
-        self.host.root()
+    /// Returns the root of the build output tree for the host (`/…/build-dir`)
+    pub fn host_build_root(&self) -> &Path {
+        self.host.build_dir().root()
     }
 
     /// Returns the host `deps` directory path.
     pub fn host_deps(&self, unit: &Unit) -> PathBuf {
         let dir = self.pkg_dir(unit);
-        self.host.deps(&dir)
+        self.host.build_dir().deps(&dir)
     }
 
     /// Returns the directories where Rust crate dependencies are found for the
     /// specified unit.
     pub fn deps_dir(&self, unit: &Unit) -> PathBuf {
         let dir = self.pkg_dir(unit);
-        self.layout(unit.kind).deps(&dir)
+        self.layout(unit.kind).build_dir().deps(&dir)
     }
 
     /// Directory where the fingerprint for the given unit should go.
     pub fn fingerprint_dir(&self, unit: &Unit) -> PathBuf {
         let dir = self.pkg_dir(unit);
-        self.layout(unit.kind).fingerprint(&dir)
+        self.layout(unit.kind).build_dir().fingerprint(&dir)
     }
 
     /// Directory where incremental output for the given unit should go.
     pub fn incremental_dir(&self, unit: &Unit) -> &Path {
-        self.layout(unit.kind).incremental()
+        self.layout(unit.kind).build_dir().incremental()
+    }
+
+    /// Directory where timing output should go.
+    pub fn timings_dir(&self) -> &Path {
+        self.host.artifact_dir().timings()
     }
 
     /// Returns the path for a file in the fingerprint directory.
@@ -314,7 +319,9 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
         assert!(!unit.mode.is_run_custom_build());
         assert!(self.metas.contains_key(unit));
         let dir = self.pkg_dir(unit);
-        self.layout(CompileKind::Host).build_script(&dir)
+        self.layout(CompileKind::Host)
+            .build_dir()
+            .build_script(&dir)
     }
 
     /// Returns the directory for compiled artifacts files.
@@ -338,7 +345,11 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
                 invalid
             ),
         };
-        self.layout(unit.kind).artifact().join(dir).join(kind)
+        self.layout(unit.kind)
+            .build_dir()
+            .artifact()
+            .join(dir)
+            .join(kind)
     }
 
     /// Returns the directory where information about running a build script
@@ -348,7 +359,9 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
         assert!(unit.target.is_custom_build());
         assert!(unit.mode.is_run_custom_build());
         let dir = self.pkg_dir(unit);
-        self.layout(unit.kind).build_script_execution(&dir)
+        self.layout(unit.kind)
+            .build_dir()
+            .build_script_execution(&dir)
     }
 
     /// Returns the "`OUT_DIR`" directory for running a build script.
@@ -367,7 +380,7 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
         bcx: &BuildContext<'_, '_>,
     ) -> CargoResult<PathBuf> {
         assert!(target.is_bin());
-        let dest = self.layout(kind).dest();
+        let dest = self.layout(kind).artifact_dir().dest();
         let info = bcx.target_data.info(kind);
         let (file_types, _) = info
             .rustc_outputs(
@@ -435,11 +448,14 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
         let filename = file_type.uplift_filename(&unit.target);
         let uplift_path = if unit.target.is_example() {
             // Examples live in their own little world.
-            self.layout(unit.kind).examples().join(filename)
+            self.layout(unit.kind)
+                .artifact_dir()
+                .examples()
+                .join(filename)
         } else if unit.target.is_custom_build() {
             self.build_script_dir(unit).join(filename)
         } else {
-            self.layout(unit.kind).dest().join(filename)
+            self.layout(unit.kind).artifact_dir().dest().join(filename)
         };
         if from_path == uplift_path {
             // This can happen with things like examples that reside in the

src/cargo/core/compiler/build_runner/mod.rs

@@ -401,7 +401,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
             let layout = files.layout(kind);
             self.compilation
                 .root_output
-                .insert(kind, layout.dest().to_path_buf());
+                .insert(kind, layout.artifact_dir().dest().to_path_buf());
             if self.bcx.gctx.cli_unstable().build_dir_new_layout {
                 for (unit, _) in self.bcx.unit_graph.iter() {
                     let dep_dir = self.files().deps_dir(unit);
@@ -411,7 +411,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
             } else {
                 self.compilation
                     .deps_output
-                    .insert(kind, layout.legacy_deps().to_path_buf());
+                    .insert(kind, layout.build_dir().legacy_deps().to_path_buf());
             }
         }
         Ok(())

src/cargo/core/compiler/layout.rs

@@ -111,38 +111,8 @@ use std::path::{Path, PathBuf};
 ///
 /// See module docs for more information.
 pub struct Layout {
-    /// The root directory: `/path/to/target`.
-    /// If cross compiling: `/path/to/target/$TRIPLE`.
-    root: PathBuf,
-    /// The final artifact destination: `$root/debug` (or `release`).
-    dest: PathBuf,
-    /// The directory with rustc artifacts: `$dest/deps`
-    deps: PathBuf,
-    /// The directory for build scripts: `$dest/build`
-    build: PathBuf,
-    /// The directory for artifacts, i.e. binaries, cdylibs, staticlibs: `$dest/deps/artifact`
-    artifact: PathBuf,
-    /// The directory for incremental files: `$dest/incremental`
-    incremental: PathBuf,
-    /// The directory for fingerprints: `$dest/.fingerprint`
-    fingerprint: PathBuf,
-    /// The directory for examples: `$dest/examples`
-    examples: PathBuf,
-    /// The directory for pre-uplifted examples: `$build-dir/debug/examples`
-    build_examples: PathBuf,
-    /// The directory for rustdoc output: `$root/doc`
-    doc: PathBuf,
-    /// The directory for temporary data of integration tests and benches: `$dest/tmp`
-    tmp: PathBuf,
-    /// The lockfile for a build (`.cargo-lock`). Will be unlocked when this
-    /// struct is `drop`ped.
-    _lock: FileLock,
-    /// Same as `_lock` but for the build directory.
-    ///
-    /// Will be `None` when the build-dir and target-dir are the same path as we cannot
-    /// lock the same path twice.
-    _build_lock: Option<FileLock>,
-    is_new_layout: bool,
+    artifact_dir: ArtifactDirLayout,
+    build_dir: BuildDirLayout,
 }
 
 impl Layout {
@@ -182,9 +152,10 @@ impl Layout {
         // For now we don't do any more finer-grained locking on the artifact
         // directory, so just lock the entire thing for the duration of this
         // compile.
-        let lock = dest.open_rw_exclusive_create(".cargo-lock", ws.gctx(), "build directory")?;
+        let artifact_dir_lock =
+            dest.open_rw_exclusive_create(".cargo-lock", ws.gctx(), "build directory")?;
 
-        let build_lock = if root != build_root {
+        let build_dir_lock = if root != build_root {
             Some(build_dest.open_rw_exclusive_create(
                 ".cargo-lock",
                 ws.gctx(),
@@ -201,23 +172,112 @@ impl Layout {
         let artifact = deps.join("artifact");
 
         Ok(Layout {
-            deps,
-            build: build_dest.join("build"),
-            artifact,
-            incremental: build_dest.join("incremental"),
-            fingerprint: build_dest.join(".fingerprint"),
-            examples: dest.join("examples"),
-            build_examples: build_dest.join("examples"),
-            doc: root.join("doc"),
-            tmp: build_root.join("tmp"),
-            root,
-            dest,
-            _lock: lock,
-            _build_lock: build_lock,
-            is_new_layout,
+            artifact_dir: ArtifactDirLayout {
+                dest: dest.clone(),
+                examples: dest.join("examples"),
+                doc: root.join("doc"),
+                timings: root.join("cargo-timings"),
+                _lock: artifact_dir_lock,
+            },
+            build_dir: BuildDirLayout {
+                root: build_root.clone(),
+                deps,
+                build: build_dest.join("build"),
+                artifact,
+                incremental: build_dest.join("incremental"),
+                fingerprint: build_dest.join(".fingerprint"),
+                examples: build_dest.join("examples"),
+                tmp: build_root.join("tmp"),
+                _lock: build_dir_lock,
+                is_new_layout,
+            },
         })
     }
 
+    /// Makes sure all directories stored in the Layout exist on the filesystem.
+    pub fn prepare(&mut self) -> CargoResult<()> {
+        self.artifact_dir.prepare()?;
+        self.build_dir.prepare()?;
+
+        Ok(())
+    }
+
+    pub fn artifact_dir(&self) -> &ArtifactDirLayout {
+        &self.artifact_dir
+    }
+
+    pub fn build_dir(&self) -> &BuildDirLayout {
+        &self.build_dir
+    }
+}
+
+pub struct ArtifactDirLayout {
+    /// The final artifact destination: `<artifact-dir>/debug` (or `release`).
+    dest: PathBuf,
+    /// The directory for examples
+    examples: PathBuf,
+    /// The directory for rustdoc output
+    doc: PathBuf,
+    /// The directory for --timings output
+    timings: PathBuf,
+    /// The lockfile for a build (`.cargo-lock`). Will be unlocked when this
+    /// struct is `drop`ped.
+    _lock: FileLock,
+}
+
+impl ArtifactDirLayout {
+    /// Makes sure all directories stored in the Layout exist on the filesystem.
+    pub fn prepare(&mut self) -> CargoResult<()> {
+        paths::create_dir_all(&self.examples)?;
+
+        Ok(())
+    }
+    /// Fetch the destination path for final artifacts  (`/…/target/debug`).
+    pub fn dest(&self) -> &Path {
+        &self.dest
+    }
+    /// Fetch the examples path.
+    pub fn examples(&self) -> &Path {
+        &self.examples
+    }
+    /// Fetch the doc path.
+    pub fn doc(&self) -> &Path {
+        &self.doc
+    }
+    /// Fetch the cargo-timings path.
+    pub fn timings(&self) -> &Path {
+        &self.timings
+    }
+}
+
+pub struct BuildDirLayout {
+    /// The root directory: `/path/to/build-dir`.
+    /// If cross compiling: `/path/to/build-dir/$TRIPLE`.
+    root: PathBuf,
+    /// The directory with rustc artifacts
+    deps: PathBuf,
+    /// The primary directory for build files
+    build: PathBuf,
+    /// The directory for artifacts, i.e. binaries, cdylibs, staticlibs
+    artifact: PathBuf,
+    /// The directory for incremental files
+    incremental: PathBuf,
+    /// The directory for fingerprints
+    fingerprint: PathBuf,
+    /// The directory for pre-uplifted examples: `build-dir/debug/examples`
+    examples: PathBuf,
+    /// The directory for temporary data of integration tests and benches
+    tmp: PathBuf,
+    /// The lockfile for a build (`.cargo-lock`). Will be unlocked when this
+    /// struct is `drop`ped.
+    ///
+    /// Will be `None` when the build-dir and target-dir are the same path as we cannot
+    /// lock the same path twice.
+    _lock: Option<FileLock>,
+    is_new_layout: bool,
+}
+
+impl BuildDirLayout {
     /// Makes sure all directories stored in the Layout exist on the filesystem.
     pub fn prepare(&mut self) -> CargoResult<()> {
         if !self.is_new_layout {
@@ -226,16 +286,10 @@ impl Layout {
         }
         paths::create_dir_all(&self.incremental)?;
         paths::create_dir_all(&self.examples)?;
-        paths::create_dir_all(&self.build_examples)?;
         paths::create_dir_all(&self.build)?;
 
         Ok(())
     }
-
-    /// Fetch the destination path for final artifacts  (`/…/target/debug`).
-    pub fn dest(&self) -> &Path {
-        &self.dest
-    }
     /// Fetch the deps path.
     pub fn deps(&self, pkg_dir: &str) -> PathBuf {
         if self.is_new_layout {
@@ -248,22 +302,13 @@ impl Layout {
     pub fn legacy_deps(&self) -> &Path {
         &self.deps
     }
-    /// Fetch the examples path.
-    pub fn examples(&self) -> &Path {
-        &self.examples
-    }
-    /// Fetch the build examples path.
-    pub fn build_examples(&self) -> &Path {
-        &self.build_examples
-    }
-    /// Fetch the doc path.
-    pub fn doc(&self) -> &Path {
-        &self.doc
-    }
-    /// Fetch the root path (`/…/target`).
     pub fn root(&self) -> &Path {
         &self.root
     }
+    /// Fetch the build examples path.
+    pub fn examples(&self) -> &Path {
+        &self.examples
+    }
     /// Fetch the incremental path.
     pub fn incremental(&self) -> &Path {
         &self.incremental