Implemented build.build-dir config option (#15104)

## What does this PR try to resolve?

This PR adds a new `build.build-dir` configuration option that was
proposed in
#14125 (comment)

This new config option allows the user to specify a directory where
intermediate build artifacts should be stored.
I have shortened it to just `build-dir` from `target-build-dir`,
although naming is still subject to change.

### What is a final artifact vs an intermediate build artifact

#### Final artifacts
These are the files that end users will typically want to access
directly or indirectly via a third party tool.

* binary executable for bin crates
* binary executable for examples
* `.crate` files output from `cargo package`
* [depinfo
files](https://doc.rust-lang.org/cargo/reference/build-cache.html#dep-info-files)
(`.d` files) for third party build-system integrations (see
https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint/mod.rs#L194)
* `cargo doc` output (html/css/js/etc)
* Cargo's
[`--timings`](https://doc.rust-lang.org/cargo/reference/timings.html)
HTML report

#### Intermediate build artifact, caches, and state
These are files that are used internally by Cargo/Rustc during the build
process

* other depinfo files (generated by rustc, fingerprint, etc. See
https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint/mod.rs#L164)
* rlibs and debug info from dependencies
* build script `OUT_DIR`
* output from proc macros (previously stored in `target/build`)
* [incremental
build](https://doc.rust-lang.org/rustc/codegen-options/index.html#incremental)
output from rustc
* fingerprint files used by Cargo for rebuild detection
* scratchpad used for `cargo package` verify step
* Cache of rustc invocations (`.rustc_info.json`)
* "pre and non uplifted" binary executables. (ie. bins for `examples`
that contain the hash in the name, bins for `benches`, proc macros,
build scripts)
* `CARGO_TARGET_TMPDIR` files (see rational for this
[here](#14125 (comment)))
*
[future-incompat-report](https://doc.rust-lang.org/cargo/reference/future-incompat-report.html)'s
`.future-incompat-report.json` file

## Feature Gating Strategy

We are following the "Ignore the feature that is used without a gate"
approach as described
[here](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/core/features/index.html).

The rational for this is:
The `build.build-dir` is likely going to be set by by users "globally"
(ie. `$CARGO_HOME/config.toml`) to set a shared build directory to
reduce rebuilding dependencies. For users that multiple cargo versions
having having an error would be disrupted.
The fallback behavior is to revert to the behavior of the current stable
release (building in `$CARGO_TARGET_DIR`)

## Testing Strategy

* We have the existing Cargo testsuite to be sure we do not introduce
regressions.
* I have also run the testsuite locally with the cli flag remove to
verify all tests pass with the default build dir (which falls back to
the target dir)
* For testing thus far, I have been using small hello world project with
a few dependencies like `rand` to verify files are being output to the
correct directory.
* When this PR is closer to merging, I plan to test with some larger
projects with more dependencies, build scripts, ect.
* Other testing recommendations are welcome 🙇

## How should we test and review this PR?

This is probably best reviewed commit by commit. I documented each
commit.
I tied to follow the atomic commits recommendation in the Cargo
contributors guide, but I split out some commits for ease of review.
(Otherwise I think this would have ended up being 1 or 2 large commits
😅)

## Questions

- [x] What is the expected behavior of `cargo clean`?
* At the time of writing it only cleans `target` and does not impact the
build-dir but this is easily changable.
* Answer: See
#15104 (comment)
- [x] When using `cargo package` are was expecting just the `.crate`
file to be in `target` while all other output be stored in
`build.build-dir`? Not sure if we consider things like `Cargo.toml`, `
Cargo.toml.orig`, `.cargo_vcs_info.json` part of the user facing
interface.
* Current consensus is that only `.crate` is considered a final artifact
- [x] Where should `cargo doc` output go? HTML/JS for many crates can be
pretty large. Moving to the build-dir would help reduce duplication if
we find the that acceptable. For `cargo doc --open` this is not a
problem but may be problematic for other use cases?
* Answer:
#15104 (comment)
- [x] Are bins generated from `benches` considered final artifacts?
* Since bins from `examples` are considered final artifacts, it seems
natural that `benches` should also be considered final artifacts.
However, unlike `examples` the `benches` bins are stored in
`target/{profile}/deps` instead of a dedicated directory (like
`target/{profile}/examples`). We could move them into a dedicated
directory (`target/{profile}/benches`) but that mean would also be
changing the structure of the `target` directory which feels out of
scope for this change. If we decide that `benches` are final artifacts,
it would probably be better to consider that changes as part of
#6790
* Answer:
#15104 (comment)
- [ ] [Do we want to include a `CARGO_BUILD_DIR` shortcut env
var?](#15104 (comment))
* The current commit (2af0c91) has
included the `CARGO_BUILD_DIR` shortcut. This can be removed before
merging if there a good reason to.

## TODO

- Implementation
  - [x] Add support in `cargo clean`
  - [ ] ~~Implement templating for `build.build-dir`~~
* Will implement in a follow up PR [as
suggested](#15104 (comment))
- [x] Fix issue with `target/examples` still containing "pre-uplifted"
binaries
  - [x] Verify `build-dir` with non-bin crate types
- Prepare for review
  - [x] Clean up/improve docs
  - [x] Review tests and add more as needed
  - [x] Fix tests in CI (Windows is currently failing)
  - [x] Clean up commits
  - [ ] Resolve remaining questions
- [x] Request review

Author: epage

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

@@ -217,7 +217,7 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
         } else if unit.target.is_custom_build() {
             self.build_script_dir(unit)
         } else if unit.target.is_example() {
-            self.layout(unit.kind).examples().to_path_buf()
+            self.layout(unit.kind).build_examples().to_path_buf()
         } else if unit.artifact.is_true() {
             self.artifact_dir(unit)
         } else {

src/cargo/core/compiler/custom_build.rs

@@ -1124,7 +1124,7 @@ fn prepare_metabuild(
     let path = unit
         .pkg
         .manifest()
-        .metabuild_path(build_runner.bcx.ws.target_dir());
+        .metabuild_path(build_runner.bcx.ws.build_dir());
     paths::create_dir_all(path.parent().unwrap())?;
     paths::write_if_changed(path, &output)?;
     Ok(())

src/cargo/core/compiler/fingerprint/dep_info.rs

@@ -51,9 +51,9 @@ pub struct RustcDepInfo {
 pub enum DepInfoPathType {
     /// src/, e.g. src/lib.rs
     PackageRootRelative,
-    /// target/debug/deps/lib...
+    /// {build-dir}/debug/deps/lib...
     /// or an absolute path /.../sysroot/...
-    TargetRootRelative,
+    BuildRootRelative,
 }
 
 /// Same as [`RustcDepInfo`] except avoids absolute paths as much as possible to
@@ -126,7 +126,7 @@ impl EncodedDepInfo {
         for _ in 0..nfiles {
             let ty = match read_u8(bytes)? {
                 0 => DepInfoPathType::PackageRootRelative,
-                1 => DepInfoPathType::TargetRootRelative,
+                1 => DepInfoPathType::BuildRootRelative,
                 _ => return None,
             };
             let path_bytes = read_bytes(bytes)?;
@@ -210,7 +210,7 @@ impl EncodedDepInfo {
         for (ty, file, checksum_info) in self.files.iter() {
             match ty {
                 DepInfoPathType::PackageRootRelative => dst.push(0),
-                DepInfoPathType::TargetRootRelative => dst.push(1),
+                DepInfoPathType::BuildRootRelative => dst.push(1),
             }
             write_bytes(dst, paths::path2bytes(file)?);
             write_bool(dst, checksum_info.is_some());
@@ -292,14 +292,14 @@ pub fn translate_dep_info(
     cargo_dep_info: &Path,
     rustc_cwd: &Path,
     pkg_root: &Path,
-    target_root: &Path,
+    build_root: &Path,
     rustc_cmd: &ProcessBuilder,
     allow_package: bool,
     env_config: &Arc<HashMap<String, OsString>>,
 ) -> CargoResult<()> {
     let depinfo = parse_rustc_dep_info(rustc_dep_info)?;
 
-    let target_root = crate::util::try_canonicalize(target_root)?;
+    let build_root = crate::util::try_canonicalize(build_root)?;
     let pkg_root = crate::util::try_canonicalize(pkg_root)?;
     let mut on_disk_info = EncodedDepInfo::default();
     on_disk_info.env = depinfo.env;
@@ -351,8 +351,8 @@ pub fn translate_dep_info(
         let canon_file =
             crate::util::try_canonicalize(&abs_file).unwrap_or_else(|_| abs_file.clone());
 
-        let (ty, path) = if let Ok(stripped) = canon_file.strip_prefix(&target_root) {
-            (DepInfoPathType::TargetRootRelative, stripped)
+        let (ty, path) = if let Ok(stripped) = canon_file.strip_prefix(&build_root) {
+            (DepInfoPathType::BuildRootRelative, stripped)
         } else if let Ok(stripped) = canon_file.strip_prefix(&pkg_root) {
             if !allow_package {
                 return None;
@@ -362,7 +362,7 @@ pub fn translate_dep_info(
             // It's definitely not target root relative, but this is an absolute path (since it was
             // joined to rustc_cwd) and as such re-joining it later to the target root will have no
             // effect.
-            (DepInfoPathType::TargetRootRelative, &*abs_file)
+            (DepInfoPathType::BuildRootRelative, &*abs_file)
         };
         Some((ty, path.to_owned()))
     };
@@ -472,7 +472,7 @@ pub fn parse_rustc_dep_info(rustc_dep_info: &Path) -> CargoResult<RustcDepInfo>
 /// indicates that the crate should likely be rebuilt.
 pub fn parse_dep_info(
     pkg_root: &Path,
-    target_root: &Path,
+    build_root: &Path,
     dep_info: &Path,
 ) -> CargoResult<Option<RustcDepInfo>> {
     let Ok(data) = paths::read_bytes(dep_info) else {
@@ -487,7 +487,7 @@ pub fn parse_dep_info(
     ret.files
         .extend(info.files.into_iter().map(|(ty, path, checksum_info)| {
             (
-                make_absolute_path(ty, pkg_root, target_root, path),
+                make_absolute_path(ty, pkg_root, build_root, path),
                 checksum_info.and_then(|(file_len, checksum)| {
                     Checksum::from_str(&checksum).ok().map(|c| (file_len, c))
                 }),
@@ -499,13 +499,13 @@ pub fn parse_dep_info(
 fn make_absolute_path(
     ty: DepInfoPathType,
     pkg_root: &Path,
-    target_root: &Path,
+    build_root: &Path,
     path: PathBuf,
 ) -> PathBuf {
     match ty {
         DepInfoPathType::PackageRootRelative => pkg_root.join(path),
         // N.B. path might be absolute here in which case the join will have no effect
-        DepInfoPathType::TargetRootRelative => target_root.join(path),
+        DepInfoPathType::BuildRootRelative => build_root.join(path),
     }
 }
 
@@ -678,7 +678,7 @@ mod encoded_dep_info {
     fn gen_test(checksum: bool) {
         let checksum = checksum.then_some((768, "c01efc669f09508b55eced32d3c88702578a7c3e".into()));
         let lib_rs = (
-            DepInfoPathType::TargetRootRelative,
+            DepInfoPathType::BuildRootRelative,
             PathBuf::from("src/lib.rs"),
             checksum.clone(),
         );
@@ -691,7 +691,7 @@ mod encoded_dep_info {
         assert_eq!(EncodedDepInfo::parse(&data).unwrap(), depinfo);
 
         let mod_rs = (
-            DepInfoPathType::TargetRootRelative,
+            DepInfoPathType::BuildRootRelative,
             PathBuf::from("src/mod.rs"),
             checksum.clone(),
         );

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

@@ -839,7 +839,7 @@ impl LocalFingerprint {
         mtime_cache: &mut HashMap<PathBuf, FileTime>,
         checksum_cache: &mut HashMap<PathBuf, Checksum>,
         pkg: &Package,
-        target_root: &Path,
+        build_root: &Path,
         cargo_exe: &Path,
         gctx: &GlobalContext,
     ) -> CargoResult<Option<StaleItem>> {
@@ -852,8 +852,8 @@ impl LocalFingerprint {
             // the `dep_info` file itself whose mtime represents the start of
             // rustc.
             LocalFingerprint::CheckDepInfo { dep_info, checksum } => {
-                let dep_info = target_root.join(dep_info);
-                let Some(info) = parse_dep_info(pkg_root, target_root, &dep_info)? else {
+                let dep_info = build_root.join(dep_info);
+                let Some(info) = parse_dep_info(pkg_root, build_root, &dep_info)? else {
                     return Ok(Some(StaleItem::MissingFile(dep_info)));
                 };
                 for (key, previous) in info.env.iter() {
@@ -910,7 +910,7 @@ impl LocalFingerprint {
             LocalFingerprint::RerunIfChanged { output, paths } => Ok(find_stale_file(
                 mtime_cache,
                 checksum_cache,
-                &target_root.join(output),
+                &build_root.join(output),
                 paths.iter().map(|p| (pkg_root.join(p), None)),
                 false,
             )),
@@ -1153,7 +1153,7 @@ impl Fingerprint {
         mtime_cache: &mut HashMap<PathBuf, FileTime>,
         checksum_cache: &mut HashMap<PathBuf, Checksum>,
         pkg: &Package,
-        target_root: &Path,
+        build_root: &Path,
         cargo_exe: &Path,
         gctx: &GlobalContext,
     ) -> CargoResult<()> {
@@ -1261,7 +1261,7 @@ impl Fingerprint {
                 mtime_cache,
                 checksum_cache,
                 pkg,
-                target_root,
+                build_root,
                 cargo_exe,
                 gctx,
             )? {
@@ -1449,13 +1449,13 @@ fn calculate(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResult
 
     // After we built the initial `Fingerprint` be sure to update the
     // `fs_status` field of it.
-    let target_root = target_root(build_runner);
+    let build_root = build_root(build_runner);
     let cargo_exe = build_runner.bcx.gctx.cargo_exe()?;
     fingerprint.check_filesystem(
         &mut build_runner.mtime_cache,
         &mut build_runner.checksum_cache,
         &unit.pkg,
-        &target_root,
+        &build_root,
         cargo_exe,
         build_runner.bcx.gctx,
     )?;
@@ -1493,7 +1493,7 @@ fn calculate_normal(
     };
 
     // Afterwards calculate our own fingerprint information.
-    let target_root = target_root(build_runner);
+    let build_root = build_root(build_runner);
     let local = if unit.mode.is_doc() || unit.mode.is_doc_scrape() {
         // rustdoc does not have dep-info files.
         let fingerprint = pkg_fingerprint(build_runner.bcx, &unit.pkg).with_context(|| {
@@ -1505,7 +1505,7 @@ fn calculate_normal(
         vec![LocalFingerprint::Precalculated(fingerprint)]
     } else {
         let dep_info = dep_info_loc(build_runner, unit);
-        let dep_info = dep_info.strip_prefix(&target_root).unwrap().to_path_buf();
+        let dep_info = dep_info.strip_prefix(&build_root).unwrap().to_path_buf();
         vec![LocalFingerprint::CheckDepInfo {
             dep_info,
             checksum: build_runner.bcx.gctx.cli_unstable().checksum_freshness,
@@ -1714,7 +1714,7 @@ fn build_script_local_fingerprints(
     // longstanding bug, in Cargo. Recent refactorings just made it painfully
     // obvious.
     let pkg_root = unit.pkg.root().to_path_buf();
-    let target_dir = target_root(build_runner);
+    let build_dir = build_root(build_runner);
     let env_config = Arc::clone(build_runner.bcx.gctx.env_config()?);
     let calculate =
         move |deps: &BuildDeps, pkg_fingerprint: Option<&dyn Fn() -> CargoResult<String>>| {
@@ -1747,7 +1747,7 @@ fn build_script_local_fingerprints(
             // them all here.
             Ok(Some(local_fingerprints_deps(
                 deps,
-                &target_dir,
+                &build_dir,
                 &pkg_root,
                 &env_config,
             )))
@@ -1783,7 +1783,7 @@ fn build_script_override_fingerprint(
 /// [`RunCustomBuild`]: crate::core::compiler::CompileMode::RunCustomBuild
 fn local_fingerprints_deps(
     deps: &BuildDeps,
-    target_root: &Path,
+    build_root: &Path,
     pkg_root: &Path,
     env_config: &Arc<HashMap<String, OsString>>,
 ) -> Vec<LocalFingerprint> {
@@ -1796,7 +1796,7 @@ fn local_fingerprints_deps(
         // absolute prefixes from them.
         let output = deps
             .build_script_output
-            .strip_prefix(target_root)
+            .strip_prefix(build_root)
             .unwrap()
             .to_path_buf();
         let paths = deps
@@ -1854,10 +1854,10 @@ pub fn dep_info_loc(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> Path
     build_runner.files().fingerprint_file_path(unit, "dep-")
 }
 
-/// Returns an absolute path that target directory.
+/// Returns an absolute path that build directory.
 /// All paths are rewritten to be relative to this.
-fn target_root(build_runner: &BuildRunner<'_, '_>) -> PathBuf {
-    build_runner.bcx.ws.target_dir().into_path_unlocked()
+fn build_root(build_runner: &BuildRunner<'_, '_>) -> PathBuf {
+    build_runner.bcx.ws.build_dir().into_path_unlocked()
 }
 
 /// Reads the value from the old fingerprint hash file and compare.

src/cargo/core/compiler/future_incompat.rs

@@ -91,7 +91,7 @@ pub struct Diagnostic {
     pub level: String,
 }
 
-/// The filename in the top-level `target` directory where we store
+/// The filename in the top-level `build-dir` directory where we store
 /// the report
 const FUTURE_INCOMPAT_FILE: &str = ".future-incompat-report.json";
 /// Max number of reports to save on disk.
@@ -166,7 +166,7 @@ impl OnDiskReports {
         }
         let on_disk = serde_json::to_vec(&self).unwrap();
         if let Err(e) = ws
-            .target_dir()
+            .build_dir()
             .open_rw_exclusive_create(
                 FUTURE_INCOMPAT_FILE,
                 ws.gctx(),
@@ -191,7 +191,7 @@ impl OnDiskReports {
 
     /// Loads the on-disk reports.
     pub fn load(ws: &Workspace<'_>) -> CargoResult<OnDiskReports> {
-        let report_file = match ws.target_dir().open_ro_shared(
+        let report_file = match ws.build_dir().open_ro_shared(
             FUTURE_INCOMPAT_FILE,
             ws.gctx(),
             "Future incompatible report",