Rework Cargo Build Dir Layout

[nikomatsakis]

Metadata
Point of contact	@ranger-ross
Team(s)	cargo
Goal document	2025h2/cargo-build-dir-layout

Summary

Rework the Cargo build directory layout to have smaller self contained "units"

Tasks and status

• Standard reviews (cargo )
• Implementation (@ranger-ross)

[nikomatsakis]

This issue is intended for status updates only.

For general questions or comments, please contact the owner(s) directly.

[ranger-ross]

Status update October 6, 2025

The build-dir was split out of target-dir as part of rust-lang/cargo#14125 and scheduled for stabilization in Rust 1.91.0. 🎉

Before re-organizing the build-dir layout we wanted to improve the existing layout tests to make sure we do not make any unexpected changes. This testing harness improvement was merged in rust-lang/cargo#15874.

The initial build-dir layout reorganization PR has been posted rust-lang/cargo#15947 and discussion/reviews are under way.

[ranger-ross]

Status update November 21, 2025

October was largely spent working out design details of the build cache and locking design.

rust-lang/cargo#16155 was opened with an initial implementation for fine grain locking for Cargo's build-dir however it needs to be reworked after the design clarifications mentioned above.

In November I had a change of employer so I my focus was largely on that. However, we did make some progress towards locking in rust-lang/cargo#16230 which no longer lock the artifact-dir for cargo check. This is expected to land in 1.93.0.

I'm hoping to push fine grain locking forward later this month and in December.

[ranger-ross]

Status update December 23, 2025

The majority of December was spent iterating on rust-lang/cargo#16155 .
As mentioned in the previous update, the original locking design was not correct and we have been working through other solutions.

As locking is tricky to get right and there are many scenarios Cargo needs to support, we are trying to descope the initial implementation to an MVP, even if that means we lose some of the concurrency.
Once we have an MVP on nightly, we can start gathering feedback on the scenarios that need improvement and iterate.

I'm hopeful that we get an unstable -Zfine-grain-locking on nightly in January for folks to try out in their workflows.

---

Also we are considering adding an opt-in for the new build-dir layout using an env var (CARGO_BUILD_DIR_LAYOUT_V2=true) to allow tool authors to begin migrating to the new layout. rust-lang/cargo#16336

Before stabilizing this, we are doing crater run to test the impact of the changes and proactively reaching out to projects to minimize breakage as much as possible. rust-lang/rust#149852

[ranger-ross]

Status update January 15, 2026

Fine grain locking for build-dir was merged in rust-lang/cargo#16155 and now available on nightly via -Zfine-grain-locking unstable flag. 🎉

There are some known issues we'd like to address before doing a formal call for testing. Notably, improving blocking messages, fixing potential thread starvation in Cargo's job queue when locks block, and investigate increasing rlimits to reduce risk of hitting max file descriptors for large projects.

I am hopeful that these issues will be resolved over the coming month and we can do a call for testing to start gathering feedback from the community on whether the new locking strategy improves workflows.

[ranger-ross]

Status update March 9, 2026

After the initial PR from the last update was merged, we shifted our focus to resolving some of the known issues.
Notably, locking blocks the Cargo job queue slowly causing thread starvation if many build units are held by another Cargo instance.

We investigated adding the ability for Cargo to "suspend" a job internally while waiting for a lock, but we felt this change was a bit invasive and did not fit well with how the job queue was designed.
Instead we plan to change our design to acquire all build unit locks prior to running the job queue. (see rust-lang/cargo#16657)

At the same time, we have continued to refine the new build-dir to prepare it for a call for testing and eventual stabilization. (rust-lang/cargo#16542, rust-lang/cargo#16502, rust-lang/cargo#16515, rust-lang/cargo#16514)

Finally we decided to split .cargo-lock into 2 locks to allow cargo check and cargo build to run in parallel when artifact-dir == build-dir (and -Zfine-grain-locking is enabled)

I suspect this may be the last update on this goal, as the 2026 slate of goals is coming up.
While I did not renew this goal for 2026, I do plan to continue work on this and eventually stabilize this within this year.