Reorganize build unit directory layout for new build-dir layout by ranger-ross · Pull Request #16542 · rust-lang/cargo

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

I'm still seeing some output_dirs present

I think that is expected.

Note that there are 2 functions in CompilationFiles relevant in this PR:

fn output_dir() -- (was previously out_dir) that gets the output path over many different types of units.

I renamed this in the first commit to 1) avoid confusion as it does NOT always point to the out dir in both the new and old layouts and 2) I wanted to use out_dir as the fn name for the path that does lead to the out dir.

I am up for renaming this fn to something else to make it even less confusing. I couldn't come up with anything more descriptive than "output" since its quiet general.

fn out_dir() -- (previous fn deps_dir) points to target/<profile>/build/<build-unit>/out in the new layout and /target/<profile>/deps

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

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 🤦‍♂️

ranger-ross · 2026-02-05T11:24:13Z

@epage gentle reminder this PR is waiting on review
Would appreciate if you could take a look when convenient.
Thanks

epage · 2026-02-06T16:03:27Z

Still working through everything from when my family was sick.

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-02-11T12:36:10Z

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.

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

Update cargo submodule 8 commits in 0c9e687d237ff04b53ccb67b4ce63e9483789e88..ce69df6f72a3b6a2b5c722ba68ddef255344b31c 2026-02-11 05:58:30 +0000 to 2026-02-12 12:39:45 +0000 - fix: apply `host.runner` only when `host-config` enabled (rust-lang/cargo#16631) - fix(cli): Improve bad manifest error (rust-lang/cargo#16630) - fix: Adjust casing of error message (rust-lang/cargo#16625) - Enable triagebot new `[view-all-comments-link]` feature (rust-lang/cargo#16629) - test(help): snapshot cargo help tests (rust-lang/cargo#16626) - Suggest a `workspace.members` entry even from outside the workspace root (rust-lang/cargo#16616) - Reorganize build unit directory layout for new build-dir layout (rust-lang/cargo#16542) - Make the error messaging for `cargo install` aware of `build.build-dir` (rust-lang/cargo#16623)

rustbot assigned epage Jan 22, 2026

ranger-ross commented Jan 22, 2026

View reviewed changes

epage reviewed Jan 22, 2026

View reviewed changes

src/cargo/core/compiler/build_runner/compilation_files.rs Outdated Show resolved Hide resolved

epage reviewed Jan 22, 2026

View reviewed changes

src/cargo/core/compiler/build_runner/compilation_files.rs Outdated Show resolved Hide resolved

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 force-pushed the layout-rename-dirs branch from 49abc7e to 5716af9 Compare January 25, 2026 06:08

This comment has been minimized.

Sign in to view

ranger-ross added 5 commits February 11, 2026 21:14

refactor: Rename CompilationFiles::out_dir to output_dir

2503102

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

feat: Renamed deps to out in new layout

1689526

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

94c4e87

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

b6df8c3

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 5716af9 to e4327a5 Compare February 11, 2026 12:36

epage reviewed Feb 11, 2026

View reviewed changes

src/cargo/core/compiler/build_runner/compilation_files.rs Show resolved Hide resolved

epage approved these changes Feb 11, 2026

View reviewed changes

epage added this pull request to the merge queue Feb 11, 2026

Merged via the queue into rust-lang:master with commit b79b1d4 Feb 11, 2026
29 checks passed

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 11, 2026

weihanglo mentioned this pull request Feb 12, 2026

Update cargo submodule rust-lang/rust#152538

Merged

ranger-ross mentioned this pull request Feb 12, 2026

docs(layout): Updated layout module docs to document new layout #16502

Open

1 task

rustbot added this to the 1.95.0 milestone Feb 12, 2026

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 Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

ranger-ross Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

This comment has been minimized.

ranger-ross commented Feb 5, 2026

Uh oh!

epage commented Feb 6, 2026

Uh oh!

rustbot commented Feb 11, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

weihanglo commented Jan 22, 2026 •

edited

Loading