Stabilize `build-dir` layout v2 by ranger-ross · Pull Request #16807 · rust-lang/cargo

ranger-ross · 2026-03-30T15:08:26Z

What does this PR try to resolve?

This PR stabilizes the build-dir reorg tracked in #15010

We have completed a crater runs (rust-lang/rust#149852) as well a call for testing (https://blog.rust-lang.org/2026/03/13/call-for-testing-build-dir-layout-v2/) with no issues reported.

At a recent Cargo meeting, we discussed the path towards stabilization:

Stabilize build-dir layout v2, and merge into nightly shortly after the 1.96 beta branch
Allow a full nightly cycle for nightly users to report issues.
Pending no major blockers, allow the stabilization to be included in the Rust 1.97 beta (otherwise revert before beta branching)

This stabilization does NOT remove the code for the legacy build-dir layout and enables -Zbuild-dir-new-layout by default. We also provide a temporary __CARGO_TEMPORARY_BUILD_DIR_NEW_LAYOUT_OPT_OUT env var that users can use to opt out. Note that this flag is temporary and only meant to mitigate the transition. It will be removed in the next release along with the legacy layout code.

The rational for this approach is that we may need to rollback the changes before the next stabilization and removing the feature flag would be a lot of changes that could result in a conflict. Keeping the feature flag minimizes the code changes needed to stabilize and makes it less risky if we need to revert.
The opt out flag is to provide a short term way for users opt if. This is primarily intended for users that absolutely must use nightly and rely on tools that expect the old layout.

closes #15010

Pending tasks

Finish update tests (there are still about 220 failing currently)
Update Cargo docs

How to test and review this PR?

There are a LOT of changes and I did my best to separate them into isolated commits.
However the stabilization commit has a lot of path updates in many tests.

epage · 2026-03-30T15:27:45Z

This stabilization does NOT remove the code for the legacy build-dir layout

Please update the PR description to include motivations for decisions.

epage · 2026-03-30T15:29:39Z

tests/testsuite/build_dir_fine_grain_locking.rs

@@ -0,0 +1,1358 @@
+//! Tests for `build.build-dir` config property.


Forgot to update on copy/paste?

Or is this a transient copy of buil_dir.rs?

Sorry, maybe should have made my intention for this more clear. Currently we have build_dir.rs and build_dir_legacy.rs for tests. build_dir.rs has both -Zbuild-dir-new-layout and -Zfine-grain-locking in its tests. If we are going to stabilize the new build-dir we probably want to have a copy of the tests without any unstable flags.

My thought here was to copy the tests so we have fine-grain-locking in its own file and remove -Zfine-grain-locking from build-dir.rs , then in the stabilization commit remove -Zbuild-die-new-layout leaving build-dir.rs with no unstable flags

So the following files are meant to be feature-variants of each other and kept in sync

build_dir.rs

build_dir_legacy.rs

build_dir_fine_grain_locking.rs

Should we make that clear somehow?

Correct, I can probably add a doc comment at the top of the file. Do you think that is sufficient?

For each file, yes

epage · 2026-03-30T15:33:21Z

tests/testsuite/bench.rs

 [COMPILING] foo v0.5.0 ([ROOT]/foo)
 [FINISHED] `bench` profile [optimized] target(s) in [ELAPSED]s
-[RUNNING] unittests src/main.rs (target/release/deps/foo-[HASH][EXE])
+[RUNNING] unittests src/main.rs (target/release/build/foo/[HASH]/out/foo-[HASH][EXE])


Is there a reason we kept the hash in test filenames?

Tbh, do think so. Maybe it's worth revisiting?

That also reminds me that build scripts have an unnesscary hardlink within build-unit/out dir.

out build_script_build build_script_build-[HASH] build_script_build.d

I raised #16812 to remove the hash from build script bins.
Looking at the PR (#16351) the removed the hash from regular bins there is no mention of tests.
Perhaps this was just missed? I can't think of any reason for them to be different.

As you mentioned, maybe we just leave the test bins with the hash to avoid breaking projects that have already updated to use the new build-dir layout.

weihanglo · 2026-03-30T15:57:41Z

src/cargo/core/features.rs

Is there any documentation we want to update when stabilizing this? I guess at least unstable.md?

Also https://doc.rust-lang.org/cargo/reference/build-cache.html has some details about the build-dir internals.

@epage

### What does this PR try to resolve? This PR spawned out of a [comment](#16807 (comment)) from @epage raising that we didn't remove the hashes for some bins. However we did remove the hashes from "regular" bins in #16351 This PR * Removes the use of `-Cextra-filename` for build scripts when `-Zbuild-dir-new-layout` is enabled. * Does not uplift build-scripts in the `build-dir` internally. (its not really uplifting, its more of a rename via hardlink) Previously, we had a directory like ``` build/<pkg>/<hash>/out/ build_script_build-[HASH].d build_script_build-[HASH][EXE] build-script-build[EXE] ``` After this change ``` build/<pkg>/<hash>/out/ build_script_build.d build_script_build[EXE] ``` Part of: #15010 ### How to test and review this PR? See the test updates in each commit. I could split into 2 PRs if needed but I felt the changes were related and small enough to go together.

This commit adds a test for a new env variable that will opt the user out of the new layout.

… of new layout This commit adds a non-stable env var that can be used to opt out of the new layout. This is meant to be temporary to make the transition less painful for users, especially on nightly.

ranger-ross · 2026-04-01T15:46:03Z

addressed the comments thus far and fixed more tests and down to about ~180 failing tests remaining.
Ran out of time today but will continue migrating the rest tomorrow

rustbot added the A-unstable Area: nightly unstable support label Mar 30, 2026

epage reviewed Mar 30, 2026

View reviewed changes

weihanglo reviewed Mar 30, 2026

View reviewed changes

ranger-ross mentioned this pull request Mar 31, 2026

Simplified build script bin names in new layout #16812

Merged

ranger-ross added 4 commits April 1, 2026 22:55

test: Added test for __CARGO_TEMPORARY_BUILD_DIR_NEW_LAYOUT_OPT_OUT

f0ff854

This commit adds a test for a new env variable that will opt the user out of the new layout.

feat: Added __CARGO_TEMPORARY_BUILD_DIR_NEW_LAYOUT_OPT_OUT to opt out…

84257b9

… of new layout This commit adds a non-stable env var that can be used to opt out of the new layout. This is meant to be temporary to make the transition less painful for users, especially on nightly.

doc: Updated build_dir test documentation

1a5e47b

test: Split fine-grain-locking tests into dedicated file

c49bf8b

ranger-ross force-pushed the stablize-build-dir-new-layout branch from 7b5186b to 0a0c24e Compare April 1, 2026 15:44

feat: Stablize build-dir layout v2

2b5af6e

ranger-ross force-pushed the stablize-build-dir-new-layout branch from 0a0c24e to 2b5af6e Compare April 2, 2026 16:42

		@@ -0,0 +1,1358 @@
		//! Tests for `build.build-dir` config property.

Conversation

ranger-ross commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR try to resolve?

Pending tasks

How to test and review this PR?

Uh oh!

epage commented Mar 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ranger-ross commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ranger-ross commented Mar 30, 2026 •

edited

Loading