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

### 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.

epage · 2026-02-16T14:54:00Z

+//!         # Root directory for all compiled examples.
+//!         examples/


Shouldn't this be removed from build-dir?

Actually its still present in the old layout.
It contains the pre-uplifted bins

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

Lines 229 to 230 in 2200079

} else if unit.target.is_example() && !self.ws.gctx().cli_unstable().build_dir_new_layout {

self.layout(unit.kind).build_dir().examples().to_path_buf()

In the new layout, the examples will use the <build-unit>/out dir just like regular compilation build units

epage · 2026-02-16T14:55:42Z

+//!                         # Set of source filenames for this package.
+//!                         dep-lib-$targetname
+//!                         # Timestamp when this package was last built.
+//!                         invoked.timestamp
+//!                         # The fingerprint hash.
+//!                         lib-$targetname
+//!                         # Detailed information used for logging the reason why
+//!                         # something is being recompiled.
+//!                         lib-$targetname.json
+//!                         # The console output from the compiler. This is cached
+//!                         # so that warnings can be redisplayed for "fresh" units.
+//!                         output-lib-$targetname
+//!


Side note: I feel like we could design the entire fingerprint/ directory.

ranger-ross · 2026-02-17T07:23:47Z

hmmm, seems github actions died? We can probably rerun.

Update cargo submodule 10 commits in ce69df6f72a3b6a2b5c722ba68ddef255344b31c..8cc0cb136772b8f54eafe0d163fcb7226a06af0c 2026-02-12 12:39:45 +0000 to 2026-02-17 12:16:26 +0000 - docs(layout): Updated layout module docs to document new layout (rust-lang/cargo#16502) - fix(host-config): host.linker should not apply to non host unit (rust-lang/cargo#16641) - init: improve error message and add tests (rust-lang/cargo#16643) - Corrected doc comment for build script root_output path (rust-lang/cargo#16645) - Changed build script run `output` dir to `stdout` in new build-dir layout (rust-lang/cargo#16644) - test: add test case for verify-project with invalid TOML (rust-lang/cargo#16640) - test(script): Show remaining workspace behavors (rust-lang/cargo#16633) - fix(host-config): `host.runner` should not apply to `cargo run` (rust-lang/cargo#16638) - refactor(help): simplify code structure (rust-lang/cargo#16627) - test: Remove unused docker ip_address (rust-lang/cargo#16636)

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

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Jan 13, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

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

Comment thread src/cargo/core/compiler/layout.rs

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

Comment thread src/cargo/core/compiler/layout.rs

epage reviewed Feb 12, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

epage reviewed Feb 12, 2026

View reviewed changes

Comment thread src/cargo/core/compiler/layout.rs Outdated

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

doc: Updated outdated profile layout documentation

129cdf1

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

epage reviewed Feb 16, 2026

View reviewed changes

ranger-ross force-pushed the layout-docs branch from 53e09a7 to 68c08ae Compare February 17, 2026 00:53

ranger-ross added 2 commits February 17, 2026 09:57

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

df38999

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

6339e32

ranger-ross force-pushed the layout-docs branch from 68c08ae to 6339e32 Compare February 17, 2026 00:57

epage approved these changes Feb 17, 2026

View reviewed changes

epage enabled auto-merge February 17, 2026 01:01

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

github-merge-queue Bot removed this pull request from the merge queue due to no response for status checks Feb 17, 2026

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

Merged via the queue into rust-lang:master with commit 8cc0cb1 Feb 17, 2026
29 checks passed

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

ranger-ross deleted the layout-docs branch February 18, 2026 15:47

weihanglo mentioned this pull request Feb 20, 2026

Update cargo submodule rust-lang/rust#152896

Merged

rustbot added this to the 1.95.0 milestone Feb 21, 2026

This was referenced Mar 2, 2026

Re-organize build-dir by package + hash, rather than artifact type #15010

Open

Rework Cargo Build Dir Layout rust-lang/rust-project-goals#401

Closed

		//! # Root directory for all compiled examples.
		//! examples/

	} else if unit.target.is_example() && !self.ws.gctx().cli_unstable().build_dir_new_layout {
	self.layout(unit.kind).build_dir().examples().to_path_buf()

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

ranger-ross commented Feb 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

epage Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

ranger-ross Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

epage Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ranger-ross commented Feb 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ranger-ross commented Jan 13, 2026 •

edited

Loading