Reorganize build unit directory layout for new build-dir layout #16542

ranger-ross · 2026-01-22T14:48:29Z

What does this PR try to resolve?

This PR makes more changes to the new build-dir layout as discussed in #16502 (comment).

The goal here is to have more general (and thus reusable) directories in the build unit structure.

Layout changes

Rename {build-unit-dir}/deps to {build-unit-dir}/out
Moved build-script OUT_DIR from {build-unit-dir}/build-script/out to {build-unit-dir}/out
Renamed {build-unit-dir}/build-script to {build-unit-dir}/run
- This makes the dir more general to any build unit that can execute an external process. (but currently only build-scripts use it)

The resulting structure looks like

build-dir/debug/build/<pkgname>/<HASH>
    fingerprint/
    out/
    run/
    .lock

Part of #15010

How to test and review this PR?

See the test updates included in each commit

rustbot · 2026-01-22T14:48:35Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

ranger-ross · 2026-01-22T14:54:55Z

tests/testsuite/build_dir.rs

-[ROOT]/foo/build-dir/debug/build/foo/[HASH]/deps/foo[..][EXE]
-[ROOT]/foo/build-dir/debug/build/foo/[HASH]/deps/foo[..].d
+[ROOT]/foo/build-dir/debug/build/foo/[HASH]/out/foo.txt
+[ROOT]/foo/build-dir/debug/build/foo/[HASH]/out/build_script_build[..].d
+[ROOT]/foo/build-dir/debug/build/foo/[HASH]/out/build_script_build[..][EXE]
+[ROOT]/foo/build-dir/debug/build/foo/[HASH]/out/build-script-build[EXE]
+[ROOT]/foo/build-dir/debug/build/foo/[HASH]/out/foo[..][EXE]
+[ROOT]/foo/build-dir/debug/build/foo/[HASH]/out/foo[..].d


note on the diffs here: Now that both the build-script and build units use the same directory we run into the issue of

foo/[HASH]/out/foo[..][EXE]

matching foo.txt that is output from the build-script.

To solve this I moved the foo.txt before the foo[..][EXE] line so it would be matched earlier.
But after doing that I felt the order of the files was mislead as it makes it look like foo.txt and foo.txt are in the same directory which they are not. (HASH is different)
So I also moved the other build script files in hopes that it might be a bit more clear.

weihanglo · 2026-01-22T15:06:08Z

   error: unsupported rustdoc format v57 for file: /home/runner/work/cargo/cargo/target/semver-checks/local-build_rs-0_3_3-default-01666ec060466c14/target/doc/build_rs.json
  (supported formats are v53, v55, v56)

cargo-semver-checks already supported rustdoc JSON v57 but not yet released

But the check-version-bump job is not blocking. The issue is the other docs job failure.

epage · 2026-01-22T19:08:32Z

src/cargo/core/compiler/layout.rs

    /// New features should consider using this so we can avoid their migrations.
-    pub fn deps_new_layout(&self, pkg_dir: &str) -> PathBuf {
-        self.build_unit(pkg_dir).join("deps")
+    pub fn output(&self, pkg_dir: &str) -> PathBuf {


Why is this output and not out?

Sorry, I had original named them output but then changed the named to out and forgot to update this one.
Will change to out

epage · 2026-01-22T19:10:10Z

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

+    pub fn out_dir(&self, unit: &Unit) -> PathBuf {
        let dir = self.pkg_dir(unit);
        self.layout(unit.kind).build_dir().deps(&dir)


I feel like this is going to get confusing with us sometimes calling deps out_dir or deps

err yeah, self.layout(...).build_dir().deps(...) should really be self.layout(...).build_dir().out(...).

This issue it that we already have an BuildDirLayout::out() that only supports the new layout.
I'll rename the current out() to out_force_new_layout() and deps() to out() that way everything is consistent

epage · 2026-01-22T19:13:57Z

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

+    pub fn build_script_out_dir(&self, unit: &Unit, is_new_layout: bool) -> PathBuf {
+        if is_new_layout {
+            self.out_dir(unit)
+        } else {
+            self.build_script_run_dir(unit).join("out")
+        }
    }


When implementing unstable features, I'd recommend considering the process for removal on stabilization. Here, we will delete this function and update all callers to call out_dir, removing the parameter as w do so. Instead, if we put the conditional in the caller, then it is just a matter of deleting 4 lines in each call site, with it being obvious what to do.

I feel like I'd just put this conditional in the caller so it becomes straighforward to identify that we need to delete one branch and exclusively call one function.

sure, that works for me. I'll pull the feature flag out of this fn to the callsite.

weihanglo · 2026-01-25T05:56:27Z

See cd39acf in commit history. Rebase got messed up?

ranger-ross · 2026-01-25T06:03:15Z

ahhh yeah, I think I did an --amend when I shouldn't have 🤦‍♂️

Rename `fn out_dir` to `fn output_dir` to avoid naming collisions in future layout changes.

Previously `deps` was only the compiler output. This commit renames it to `out` to make it more general to any kind of build output. The build script OUT_DIR will eventually be merged into this directory.

This was previously indirectly created by `OUT_DIR`, however in the future `OUT_DIR` will not be nested in the build-script run dir so we always want to create it.

This commit moves the build-script OUT_DIR location from `{build-unit-dir}/build-script-execution/out` to `{build-unit-dir}/out` dir (that was previously `{build-unit-dir}/deps`)

This commit changes the build script execution dir from `{build-unit-dir}/build-script` to `{build-unit-dir}/run`. The motivation behind this is to have a general directory for units that execute some binary/external process and output to stdout/err. Currently this is only used by build-scripts but could be expanded in the future.

rustbot · 2026-01-25T06:08:16Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

rustbot assigned epage Jan 22, 2026

ranger-ross commented Jan 22, 2026

View reviewed changes

epage reviewed Jan 22, 2026

View reviewed changes

ranger-ross force-pushed the layout-rename-dirs branch from d7c6ce1 to 494c2f1 Compare January 24, 2026 09:59

This comment has been minimized.

Sign in to view

ranger-ross force-pushed the layout-rename-dirs branch from 494c2f1 to 2decb74 Compare January 24, 2026 10:13

This comment has been minimized.

Sign in to view

ranger-ross force-pushed the layout-rename-dirs branch from 2decb74 to 49abc7e Compare January 25, 2026 03:42

This comment has been minimized.

Sign in to view

ranger-ross added 5 commits January 25, 2026 15:06

refactor: Rename CompilationFiles::out_dir to output_dir

30c2d8b

Rename `fn out_dir` to `fn output_dir` to avoid naming collisions in future layout changes.

feat: Renamed deps to out in new layout

78a8c97

Previously `deps` was only the compiler output. This commit renames it to `out` to make it more general to any kind of build output. The build script OUT_DIR will eventually be merged into this directory.

fix: Always create build-script run dir

e96c434

This was previously indirectly created by `OUT_DIR`, however in the future `OUT_DIR` will not be nested in the build-script run dir so we always want to create it.

feat: Moved build-script OUT_DIR to out dir in new layout

b836d96

This commit moves the build-script OUT_DIR location from `{build-unit-dir}/build-script-execution/out` to `{build-unit-dir}/out` dir (that was previously `{build-unit-dir}/deps`)

ranger-ross force-pushed the layout-rename-dirs branch from 49abc7e to 5716af9 Compare January 25, 2026 06:08

Reorganize build unit directory layout for new build-dir layout #16542

Are you sure you want to change the base?

Reorganize build unit directory layout for new build-dir layout #16542

Conversation

ranger-ross commented Jan 22, 2026

What does this PR try to resolve?

Layout changes

How to test and review this PR?

Uh oh!

rustbot commented Jan 22, 2026

Uh oh!

ranger-ross Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

epage Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

ranger-ross Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

epage Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

ranger-ross Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

epage Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

ranger-ross Jan 24, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

weihanglo commented Jan 25, 2026

Uh oh!

ranger-ross commented Jan 25, 2026

Uh oh!

rustbot commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

weihanglo commented Jan 22, 2026 •

edited

Loading