docs(layout): Updated layout module docs to document new layout by ranger-ross · Pull Request #16502 · rust-lang/cargo

ranger-ross · 2026-01-13T12:00:24Z

What does this PR try to resolve?

This PR updates the layout module docs to reflect the update layout structure changes made as part of #15010

How to test and review this PR?

no response

Follow up needed

Add a note in the tracking issue to updating these docs in the stabilization PR

rustbot · 2026-01-13T12:00:30Z

r? @weihanglo

rustbot has assigned @weihanglo.
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

epage · 2026-01-13T13:35:07Z

src/cargo/core/compiler/layout.rs

+//!
+//! As of early 2026, Cargo is restructuring the layout and supports 2 layouts.
+//! * the original layout organizing files by type
+//! * the new "build unit" based layout
+//!
+//! For more info the layout transition see: [#15010](https://github.com/rust-lang/cargo/issues/15010)


How do we track removal of this on stabilization?

it could be a bullet point to remove in the tracking issue to remove this in the stabilization PR?

That is fine. Be sure to call that out in this PR description.

src/cargo/core/compiler/layout.rs

epage · 2026-01-13T13:36:49Z

src/cargo/core/compiler/layout.rs

+//!     # Note that named profiles will soon be included as separate directories
+//!     # here. They have a restricted format, similar to Rust identifiers, so


What do you mean about named profiles will be separate directories?

Oh, this was copied over. Probably should be removed from the other section in a separate commit

src/cargo/core/compiler/layout.rs

epage · 2026-01-13T13:42:02Z

src/cargo/core/compiler/layout.rs

+//!                     # This is the directory for the rustc artifacts of this unit except build
+//!                     # scripts, examples, and test and bench executables.


These exceptions are removed, right?

For build-scripts its still applicable, as they are compiled into $pkgname/$META/build-script.
Though, that could probably be merged into $pkgname/$META/deps. (also thinking about it that would allow us to rename build-script-execution to build-script for shorter paths on windows)

For tests and benches I believe you are correct.

Oh looks like you beat me to that idea in this comment https://github.com/rust-lang/cargo/pull/16502/files#r2686490751 😄

Like I mentioned at #16515 (review), I'm tempted to generalize the layout. My ideas are:

change build-script-executed to run as it just contains information general to running an external process

change deps to out and move build-script-executed to out as well, so out represents the writeable directory for a build unit to write output to.

I like that idea!

My only thought is maybe we use output instead of out to avoid having 2 types of our-dir's which could be a bit confusing.

something like

build-dir/debug/build/<pkgname>/<hash> fingerprint/ output/ run/

My only thought is maybe we use output instead of out to avoid having 2 types of our-dir's which could be a bit confusing.

Which two types?

For build scripts, it is literally called OUT_DIR so calling it out makes sense.

Part of my intention with renaming deps to out is to make each type of build unit less special. This is the directory that the build unit has access to to write its output.

Ahhh, I see. So your proposing move out from build-unit-execution and merging it with deps?

So for

compile units out contains rlib/rmeta/bins/libs/ect

Build script (build) units out contains the build script bin

Build script (run) units out is the OUT_DIR. run contains the stdout/err output

Thinking about this a bit more, I think it makes a lot of sense :)

epage · 2026-01-13T13:43:16Z

src/cargo/core/compiler/layout.rs

+//!                     # If the unit is a build script compilation, the build script
+//!                     # binary will be stored here.
+//!                     build-script/


Do we still need these to be different than deps?

I don't think so, we can probably merge them together as mentioned in https://github.com/rust-lang/cargo/pull/16502/files#r2694115028

src/cargo/core/compiler/layout.rs

@epage

### What does this PR try to resolve? While documenting the `build-dir` layout changes in #16502 I noticed that we are still creating the `<build-dir>/<profile>/examples` directory when `-Zbuild-dir-new-layout` is passed even though its no longer used. This PR fixes it cc tracking issue: #15010 ### How to test and review this PR? Updating the existing examples test to catch this particular case r? @epage

@epage

### What does this PR try to resolve? In #16502 (comment) there was a discussion about merging the `build-script` and `deps` dirs in the `build-dir`. Currently: ``` build-dir/<profile>/build/<pkgname>/<hash>/ deps/ # rustc output build-script/ # build script binary build-script-execution/ # the output of running a build script ``` Note: For build-scripts `deps` is empty. This PR: 1. moves the build script binaries from `build-script` to `deps` to simplify the layout 2. renames `build-script-execution` to `build-script` to simplify the dir naming and shorten the path length for windows ``` build-dir/<profile>/build/<pkgname>/<hash>/ deps/ # rustc output including build-script bins build-script/ # the output of running a build script ``` cc tracking issue: #15010 ### How to test and review this PR? see the test changes r? @epage

@epage

### What does this PR try to resolve? This spawned out of #16502 (comment) when I noticed artifact dependencies are not using the new build-dir layout. This PR moves them from `<build-dir>/<profile>/deps/artifact/$pkgname-$META` (old layout) to `<build-dir>/<profile>/build/$pkgname/$META/deps/artifact/<kind>` when `-Zbuild-dir-new-layout` is enabled. cc tracking issue: #15010 ### How to test and review this PR? Added new test specifically for artifact deps r? @epage

### 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 1. Rename `{build-unit-dir}/deps` to `{build-unit-dir}/out` 2. Moved build-script `OUT_DIR` from `{build-unit-dir}/build-script/out` to `{build-unit-dir}/out` 3. 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

ranger-ross · 2026-02-12T16:09:09Z

Okay I am finally coming back to this PR now that #16515, #16519, and #16542 are merged.

I've updated the documentation to reflect the changes added in those PRs.

ranger-ross · 2026-02-12T16:10:48Z

src/cargo/core/compiler/layout.rs

+//!                     run/
+//!                         # Timestamp of last execution.
+//!                         invoked.timestamp
+//!                         # Stdout output from the process.
+//!                         output
+//!                         # Stderr output from the process.
+//!                         stderr


I'd be in favor to also rename output to stdout to match stderr.

Thoughts?

If it fits within this to do so, I think that makes sense.

I raised #16644 for this.

Will update this PR once that is merged :)

epage · 2026-02-12T16:30:16Z

src/cargo/core/compiler/layout.rs

+//! The new build unit based layout has separate structures for `artifact-dir` and `build-dir`.
+//! By default both of these point to `target` in the workspace root.
+//!


Isn't the artifact dir layout independent of all of the layouts?

Pulling out the artifact-dir layout from build-dir layout within the old layout seems like something we should do as a separate commit or even separate PR. This would then just focus on the changes for build-dir.

Yes, after re-reading this, it is misleading as artifact-dir is not build unit based.

Pulling out the artifact-dir layout from build-dir layout within the old layout seems like something we should do as a separate commit or even separate PR. This would then just focus on the changes for build-dir.

Sure I'll de-scope this PR to just document the new build-dir layout

I was assuming the artifact-dir part would remain.

I expect from this the following commits

Cleanup of the profile text (docs(layout): Updated layout module docs to document new layout #16502 (comment))

Separate artifact-dir from build-dir

Adding of the new layout, more highlighting the unstable feature name (which will show up in searches for removing) rather than the year (thats a historical question left to git history and PRs)

epage · 2026-02-12T16:32:32Z

src/cargo/core/compiler/layout.rs

+//!     # Output from rustdoc
+//!     doc/


This isn't part of the build-dir layout, right?

err, yeah sorry. Added by mistake. Will remove

@epage

…yout (#16644) ### What does this PR try to resolve? Another `build-dir` layout change that was spawned out of discussion in this comment thread #16502 (comment) This PR changes `<build-dir>/<profile>/build/<pkgname>/[HASH]/run/output` to `<build-dir>/<profile>/build/<pkgname>/[HASH]/run/stdout` for the new `build-dir` layout. The motivation here is to change is to: 1. Better communicate what this file is used for. (it only contains `stdout` of a build script run) * Reduce the overloading of "output" as a term. 2. Match the corresponding `stderr` file cc: #15010 ### How to test and review this PR? See the test changes r? @epage

rustbot · 2026-02-15T12:09:18Z

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 weihanglo Jan 13, 2026

rustbot added A-layout Area: target output directory layout, naming, and organization S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 13, 2026

epage reviewed Jan 13, 2026

View reviewed changes

src/cargo/core/compiler/layout.rs Outdated Show resolved Hide resolved

epage reviewed Jan 13, 2026

View reviewed changes

src/cargo/core/compiler/layout.rs Outdated Show resolved Hide resolved

epage reviewed Jan 13, 2026

View reviewed changes

src/cargo/core/compiler/layout.rs Outdated Show resolved Hide resolved

epage reviewed Jan 13, 2026

View reviewed changes

src/cargo/core/compiler/layout.rs Outdated Show resolved Hide resolved

epage reviewed Jan 13, 2026

View reviewed changes

src/cargo/core/compiler/layout.rs Outdated Show resolved Hide resolved

epage reviewed Jan 13, 2026

View reviewed changes

ranger-ross force-pushed the layout-docs branch from ca93c71 to 080e303 Compare January 15, 2026 12:28

ranger-ross commented Jan 15, 2026

View reviewed changes

src/cargo/core/compiler/layout.rs Show resolved Hide resolved

ranger-ross mentioned this pull request Jan 15, 2026

Do not create examples dir in build dir with new layout #16514

Merged

ranger-ross mentioned this pull request Jan 15, 2026

Moved build-script bins to deps directory #16515

Merged

ranger-ross mentioned this pull request Jan 16, 2026

Store artifact deps in build unit dir #16519

Merged

This was referenced Jan 19, 2026

Implictly enable -Zbuild-dir-new-layout when -Zrustdoc-mergeable-info #16527

Closed

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

Merged

ranger-ross force-pushed the layout-docs branch from 080e303 to f0ea77f Compare February 12, 2026 16:06

This comment has been minimized.

Sign in to view

ranger-ross commented Feb 12, 2026

View reviewed changes

epage reviewed Feb 12, 2026

View reviewed changes

ranger-ross mentioned this pull request Feb 14, 2026

Changed build script run output dir to stdout in new build-dir layout #16644

Merged

ranger-ross force-pushed the layout-docs branch from f0ea77f to 0f0be3c Compare February 14, 2026 12:21

This comment has been minimized.

Sign in to view

ranger-ross force-pushed the layout-docs branch from 0f0be3c to 65d9ec3 Compare February 15, 2026 12:09

ranger-ross force-pushed the layout-docs branch from 65d9ec3 to 0e0fb09 Compare February 15, 2026 12:16

ranger-ross added 2 commits February 15, 2026 21:19

doc: Updated outdated profile layout documentation

129cdf1

doc: Split layout into build/artifact dir in module doc

ccf5dbc

ranger-ross force-pushed the layout-docs branch from 0e0fb09 to 20862b4 Compare February 15, 2026 12:20

doc: Added new build-dir layout to layout module doc

53e09a7

ranger-ross force-pushed the layout-docs branch from 20862b4 to 53e09a7 Compare February 15, 2026 12:20

		//! # Note that named profiles will soon be included as separate directories
		//! # here. They have a restricted format, similar to Rust identifiers, so

		//! # This is the directory for the rustc artifacts of this unit except build
		//! # scripts, examples, and test and bench executables.

Conversation

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

Uh oh!

What does this PR try to resolve?

How to test and review this PR?

Follow up needed

Uh oh!

rustbot commented Jan 13, 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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Uh oh!

This comment has been minimized.

ranger-ross commented Feb 12, 2026

Uh oh!

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

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!

This comment has been minimized.

rustbot commented Feb 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ranger-ross commented Jan 13, 2026 •

edited

Loading

ranger-ross Feb 12, 2026 •

edited

Loading