Skip to content

docs(build-script): clarify OUT_DIR is not cleaned between builds #16437

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
weihanglo merged 2 commits into from
Jan 4, 2026
Merged

docs(build-script): clarify OUT_DIR is not cleaned between builds #16437

weihanglo merged 2 commits into from
Jan 4, 2026

Conversation

@dhruv-38
Copy link
Contributor

@dhruv-38 dhruv-38 commented Dec 26, 2025

What does this PR try to resolve?

This PR documents the behavior of the OUT_DIR environment variable, clarifying that Cargo does not clean or reset it between
builds. The contents of OUT_DIR may persist across rebuilds, which can surprise build scripts that assume a clean directory.

This behavior is intentional to support incremental builds (such as native code compilation), but was not clearly stated in the
documentation.

Fixes #16332

How to test and review this PR?

Documentation-only change.
Review the updated notes in the Build Scripts and Environment Variables sections.

@rustbot rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Dec 26, 2025
@rustbot
Copy link
Collaborator

rustbot commented Dec 26, 2025

r? @ehuss

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

weihanglo
weihanglo reviewed Dec 28, 2025
View reviewed changes
Copy link
Member

@weihanglo weihanglo left a comment •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks generally good.

View changes since this review

src/doc/src/reference/build-scripts.md
> Build scripts should not assume that `OUT_DIR` is empty. If a script requires
> a clean directory, it is responsible for removing or managing any files or
> subdirectories it creates.
Copy link
Member

@weihanglo weihanglo Dec 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like the statement here is a little bit too strong. Maybe we should link to a tracking issue for this:

thought we had an issue for a build script temp dir that is independent of -Cextra-filename but not finding it.

So that we can have feedback of the potential extension?

Copy link
Member

@weihanglo weihanglo Dec 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related issues:

@dhruv-38 dhruv-38 force-pushed the docs-out-dir-persistence branch from 5bb7983 to 53f4780 Compare December 29, 2025 04:11
@rustbot
Copy link
Collaborator

rustbot commented Dec 29, 2025

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.

@dhruv-38
Copy link
Contributor Author

dhruv-38 commented Dec 31, 2025

just check i have added the links and changed some wordings

@dhruv-38
Copy link
Contributor Author

dhruv-38 commented Jan 4, 2026

@weihanglo do i need to do something else also?

weihanglo
weihanglo approved these changes Jan 4, 2026
View reviewed changes
Copy link
Member

@weihanglo weihanglo left a comment •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update!

View changes since this review

@weihanglo weihanglo added this pull request to the merge queue Jan 4, 2026
Merged via the queue into rust-lang:master with commit b8ba7ae Jan 4, 2026
29 checks passed
@rustbot rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 4, 2026
@weihanglo weihanglo mentioned this pull request Jan 6, 2026
Merged
rust-bors bot added a commit to rust-lang/rust that referenced this pull request Jan 7, 2026
@rust-bors
Auto merge of #150739 - weihanglo:update-cargo, r=weihanglo
709282b 
Update cargo submodule

19 commits in 94c368ad2b9db0f0da5bdd8421cea13786ce4412..623444427f04292f3a3c7eac560cfa65ba0bb88e
2025-12-26 19:39:15 +0000 to 2026-01-06 21:05:05 +0000
- docs(unstable): expand docs for `-Zbuild-analysis` (rust-lang/cargo#16476)
- test: add `-Zunstable-options` with custom targets (rust-lang/cargo#16467)
- feat(report): add cargo report rebuilds  (rust-lang/cargo#16456)
- feat(test-support): Use test name for dir when running tests (rust-lang/cargo#16121)
- refactor: Migrate some cases to expect/reason (rust-lang/cargo#16461)
- docs(build-script): clarify OUT_DIR is not cleaned between builds (rust-lang/cargo#16437)
- chore: Update dependencies (rust-lang/cargo#16460)
- Update handlebars to 6.4.0 (rust-lang/cargo#16457)
- chore(deps): update alpine docker tag to v3.23 (rust-lang/cargo#16454)
- Any build scripts can now use cargo::metadata=KEY=VALUE (rust-lang/cargo#16436)
- fix(log): add `dependencies` field to `UnitRegistered` (rust-lang/cargo#16448)
- Implement fine grain locking for `build-dir` (rust-lang/cargo#16155)
- feat(resolver): List features when no close match (rust-lang/cargo#16445)
- feat(report): new command `cargo report sessions` (rust-lang/cargo#16428)
- feat (patch): Display where the patch was defined in patch-related error messages (rust-lang/cargo#16407)
- test(build-rs): Reduce from 'build' to 'check' where possible (rust-lang/cargo#16444)
- feat(toml): TOML 1.1 parse support (rust-lang/cargo#16415)
- feat(report): support --manifest-path in `cargo report timings` (rust-lang/cargo#16441)
- fix(vendor): recursively filter git files in subdirectories (rust-lang/cargo#16439)

r? ghost
rust-bors bot added a commit to rust-lang/rust that referenced this pull request Jan 8, 2026
@rust-bors
Auto merge of #150739 - weihanglo:update-cargo, r=weihanglo
21c0a5c 
Update cargo submodule

24 commits in 94c368ad2b9db0f0da5bdd8421cea13786ce4412..fc4c92b64d1e0046b66cbdc747cc1c17af8b35a0
2025-12-26 19:39:15 +0000 to 2026-01-08 06:54:56 +0000
- Fixed incorrect version comparision during build script dependency selection (rust-lang/cargo#16486)
- refactor: new type for unit index (rust-lang/cargo#16485)
- feat(test): Make CARGO_BIN_EXE_ available at runtime  (rust-lang/cargo#16421)
- fix(package): detect dirty files when run from workspace member (rust-lang/cargo#16479)
- fix(timing)!: remove `--timings=<FMT>` optional format values (rust-lang/cargo#16420)
- docs(unstable): expand docs for `-Zbuild-analysis` (rust-lang/cargo#16476)
- test: add `-Zunstable-options` with custom targets (rust-lang/cargo#16467)
- feat(report): add cargo report rebuilds  (rust-lang/cargo#16456)
- feat(test-support): Use test name for dir when running tests (rust-lang/cargo#16121)
- refactor: Migrate some cases to expect/reason (rust-lang/cargo#16461)
- docs(build-script): clarify OUT_DIR is not cleaned between builds (rust-lang/cargo#16437)
- chore: Update dependencies (rust-lang/cargo#16460)
- Update handlebars to 6.4.0 (rust-lang/cargo#16457)
- chore(deps): update alpine docker tag to v3.23 (rust-lang/cargo#16454)
- Any build scripts can now use cargo::metadata=KEY=VALUE (rust-lang/cargo#16436)
- fix(log): add `dependencies` field to `UnitRegistered` (rust-lang/cargo#16448)
- Implement fine grain locking for `build-dir` (rust-lang/cargo#16155)
- feat(resolver): List features when no close match (rust-lang/cargo#16445)
- feat(report): new command `cargo report sessions` (rust-lang/cargo#16428)
- feat (patch): Display where the patch was defined in patch-related error messages (rust-lang/cargo#16407)
- test(build-rs): Reduce from 'build' to 'check' where possible (rust-lang/cargo#16444)
- feat(toml): TOML 1.1 parse support (rust-lang/cargo#16415)
- feat(report): support --manifest-path in `cargo report timings` (rust-lang/cargo#16441)
- fix(vendor): recursively filter git files in subdirectories (rust-lang/cargo#16439)
rust-bors bot added a commit to rust-lang/rust that referenced this pull request Jan 9, 2026
@rust-bors
Auto merge of #150739 - weihanglo:update-cargo, r=weihanglo
a3f2d5a 
Update cargo submodule

27 commits in 94c368ad2b9db0f0da5bdd8421cea13786ce4412..8c133afcd5e0d69932fe11f5907683723f8d361d
2025-12-26 19:39:15 +0000 to 2026-01-09 03:50:15 +0000
- Isolate build script metadata progation between std and non-std crates (rust-lang/cargo#16489)
- Add Clippy like lint groups (rust-lang/cargo#16464)
- feat: in-memory only `Manifest` (rust-lang/cargo#16409)
- Fixed incorrect version comparision during build script dependency selection (rust-lang/cargo#16486)
- refactor: new type for unit index (rust-lang/cargo#16485)
- feat(test): Make CARGO_BIN_EXE_ available at runtime  (rust-lang/cargo#16421)
- fix(package): detect dirty files when run from workspace member (rust-lang/cargo#16479)
- fix(timing)!: remove `--timings=&lt;FMT&gt;` optional format values (rust-lang/cargo#16420)
- docs(unstable): expand docs for `-Zbuild-analysis` (rust-lang/cargo#16476)
- test: add `-Zunstable-options` with custom targets (rust-lang/cargo#16467)
- feat(report): add cargo report rebuilds  (rust-lang/cargo#16456)
- feat(test-support): Use test name for dir when running tests (rust-lang/cargo#16121)
- refactor: Migrate some cases to expect/reason (rust-lang/cargo#16461)
- docs(build-script): clarify OUT_DIR is not cleaned between builds (rust-lang/cargo#16437)
- chore: Update dependencies (rust-lang/cargo#16460)
- Update handlebars to 6.4.0 (rust-lang/cargo#16457)
- chore(deps): update alpine docker tag to v3.23 (rust-lang/cargo#16454)
- Any build scripts can now use cargo::metadata=KEY=VALUE (rust-lang/cargo#16436)
- fix(log): add `dependencies` field to `UnitRegistered` (rust-lang/cargo#16448)
- Implement fine grain locking for `build-dir` (rust-lang/cargo#16155)
- feat(resolver): List features when no close match (rust-lang/cargo#16445)
- feat(report): new command `cargo report sessions` (rust-lang/cargo#16428)
- feat (patch): Display where the patch was defined in patch-related error messages (rust-lang/cargo#16407)
- test(build-rs): Reduce from 'build' to 'check' where possible (rust-lang/cargo#16444)
- feat(toml): TOML 1.1 parse support (rust-lang/cargo#16415)
- feat(report): support --manifest-path in `cargo report timings` (rust-lang/cargo#16441)
- fix(vendor): recursively filter git files in subdirectories (rust-lang/cargo#16439)
@rustbot rustbot added this to the 1.94.0 milestone Jan 9, 2026
github-actions bot pushed a commit to rust-lang/rust-analyzer that referenced this pull request Jan 12, 2026
@rust-bors
Auto merge of #150739 - weihanglo:update-cargo, r=weihanglo
b11dffc 
Update cargo submodule

27 commits in 94c368ad2b9db0f0da5bdd8421cea13786ce4412..8c133afcd5e0d69932fe11f5907683723f8d361d
2025-12-26 19:39:15 +0000 to 2026-01-09 03:50:15 +0000
- Isolate build script metadata progation between std and non-std crates (rust-lang/cargo#16489)
- Add Clippy like lint groups (rust-lang/cargo#16464)
- feat: in-memory only `Manifest` (rust-lang/cargo#16409)
- Fixed incorrect version comparision during build script dependency selection (rust-lang/cargo#16486)
- refactor: new type for unit index (rust-lang/cargo#16485)
- feat(test): Make CARGO_BIN_EXE_ available at runtime  (rust-lang/cargo#16421)
- fix(package): detect dirty files when run from workspace member (rust-lang/cargo#16479)
- fix(timing)!: remove `--timings=&lt;FMT&gt;` optional format values (rust-lang/cargo#16420)
- docs(unstable): expand docs for `-Zbuild-analysis` (rust-lang/cargo#16476)
- test: add `-Zunstable-options` with custom targets (rust-lang/cargo#16467)
- feat(report): add cargo report rebuilds  (rust-lang/cargo#16456)
- feat(test-support): Use test name for dir when running tests (rust-lang/cargo#16121)
- refactor: Migrate some cases to expect/reason (rust-lang/cargo#16461)
- docs(build-script): clarify OUT_DIR is not cleaned between builds (rust-lang/cargo#16437)
- chore: Update dependencies (rust-lang/cargo#16460)
- Update handlebars to 6.4.0 (rust-lang/cargo#16457)
- chore(deps): update alpine docker tag to v3.23 (rust-lang/cargo#16454)
- Any build scripts can now use cargo::metadata=KEY=VALUE (rust-lang/cargo#16436)
- fix(log): add `dependencies` field to `UnitRegistered` (rust-lang/cargo#16448)
- Implement fine grain locking for `build-dir` (rust-lang/cargo#16155)
- feat(resolver): List features when no close match (rust-lang/cargo#16445)
- feat(report): new command `cargo report sessions` (rust-lang/cargo#16428)
- feat (patch): Display where the patch was defined in patch-related error messages (rust-lang/cargo#16407)
- test(build-rs): Reduce from 'build' to 'check' where possible (rust-lang/cargo#16444)
- feat(toml): TOML 1.1 parse support (rust-lang/cargo#16415)
- feat(report): support --manifest-path in `cargo report timings` (rust-lang/cargo#16441)
- fix(vendor): recursively filter git files in subdirectories (rust-lang/cargo#16439)
github-actions bot pushed a commit to rust-lang/rustc-dev-guide that referenced this pull request Jan 12, 2026
@rust-bors
Auto merge of #150739 - weihanglo:update-cargo, r=weihanglo
f8ed257 
Update cargo submodule

27 commits in 94c368ad2b9db0f0da5bdd8421cea13786ce4412..8c133afcd5e0d69932fe11f5907683723f8d361d
2025-12-26 19:39:15 +0000 to 2026-01-09 03:50:15 +0000
- Isolate build script metadata progation between std and non-std crates (rust-lang/cargo#16489)
- Add Clippy like lint groups (rust-lang/cargo#16464)
- feat: in-memory only `Manifest` (rust-lang/cargo#16409)
- Fixed incorrect version comparision during build script dependency selection (rust-lang/cargo#16486)
- refactor: new type for unit index (rust-lang/cargo#16485)
- feat(test): Make CARGO_BIN_EXE_ available at runtime  (rust-lang/cargo#16421)
- fix(package): detect dirty files when run from workspace member (rust-lang/cargo#16479)
- fix(timing)!: remove `--timings=&lt;FMT&gt;` optional format values (rust-lang/cargo#16420)
- docs(unstable): expand docs for `-Zbuild-analysis` (rust-lang/cargo#16476)
- test: add `-Zunstable-options` with custom targets (rust-lang/cargo#16467)
- feat(report): add cargo report rebuilds  (rust-lang/cargo#16456)
- feat(test-support): Use test name for dir when running tests (rust-lang/cargo#16121)
- refactor: Migrate some cases to expect/reason (rust-lang/cargo#16461)
- docs(build-script): clarify OUT_DIR is not cleaned between builds (rust-lang/cargo#16437)
- chore: Update dependencies (rust-lang/cargo#16460)
- Update handlebars to 6.4.0 (rust-lang/cargo#16457)
- chore(deps): update alpine docker tag to v3.23 (rust-lang/cargo#16454)
- Any build scripts can now use cargo::metadata=KEY=VALUE (rust-lang/cargo#16436)
- fix(log): add `dependencies` field to `UnitRegistered` (rust-lang/cargo#16448)
- Implement fine grain locking for `build-dir` (rust-lang/cargo#16155)
- feat(resolver): List features when no close match (rust-lang/cargo#16445)
- feat(report): new command `cargo report sessions` (rust-lang/cargo#16428)
- feat (patch): Display where the patch was defined in patch-related error messages (rust-lang/cargo#16407)
- test(build-rs): Reduce from 'build' to 'check' where possible (rust-lang/cargo#16444)
- feat(toml): TOML 1.1 parse support (rust-lang/cargo#16415)
- feat(report): support --manifest-path in `cargo report timings` (rust-lang/cargo#16441)
- fix(vendor): recursively filter git files in subdirectories (rust-lang/cargo#16439)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@weihanglo weihanglo weihanglo approved these changes

Assignees

@ehuss ehuss

Labels

A-documenting-cargo-itself Area: Cargo's documentation

Projects

None yet

Milestone

1.94.0

Development

Successfully merging this pull request may close these issues.

OUT_DIR is not cleaned

4 participants

@dhruv-38 @rustbot @weihanglo @ehuss