Ything-RepoMirrors/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2026-01-25 04:16:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
### 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._
This commit is contained in:
Weihang Lo
2026-01-04 14:55:30 +00:00
committed by GitHub
parent f47d62e87a cdc10ac2c6
commit b8ba7ae88d
2 changed files with 18 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
src/doc/src/reference/build-scripts.md
View File

@@ -73,6 +73,18 @@ Build scripts may save any output files or intermediate artifacts in the
directory specified in the [`OUT_DIR` environment variable][build-env]. Scripts
should not modify any files outside of that directory.
> **Note:** Cargo does not clean or reset `OUT_DIR` between builds. The contents
> of this directory may persist across rebuilds, even if the build script is
> re-run. This behavior is intentional to support incremental builds, such as
> native code compilation.
>
>Build scripts should not rely on `OUT_DIR` being empty, as its contents may
>persist across rebuilds. If a script requires a clean directory, it is currently
>responsible for managing or cleaning up any files or subdirectories it creates.
>Future improvements in this area are being discussed (see
>[#16427](https://github.com/rust-lang/cargo/issues/16427) and
>[#9661](https://github.com/rust-lang/cargo/issues/9661)).
Build scripts communicate with Cargo by printing to stdout. Cargo will
interpret each line that starts with `cargo::` as an instruction that will
influence compilation of the package. All other lines are ignored.

8
src/doc/src/reference/environment-variables.md
View File

@@ -255,7 +255,8 @@ corresponding environment variable is set to the empty string, `""`.
file extension, such as `.exe`.
* `OUT_DIR` --- If the package has a build script, this is set to the folder
where the build script should place its output. See below for more information.
(Only set during compilation.)
(Only set during compilation.) Cargo does not guarantee that this directory
is empty, and it is not cleaned between builds.
* `CARGO_BIN_EXE_<name>` --- The absolute path to a binary target's executable.
This is only set when building an [integration test] or benchmark. This may
be used with the [`env` macro] to find the executable to run for testing
@@ -366,7 +367,10 @@ let out_dir = env::var("OUT_DIR").unwrap();
> Some cfg values like `test` are not available.
* `OUT_DIR` --- the folder in which all output and intermediate artifacts should
be placed. This folder is inside the build directory for the package being built,
and it is unique for the package in question.
and it is unique for the package in question. Cargo does not clean or reset this
directory between builds, and its contents may persist across rebuilds. Build
scripts should not assume that `OUT_DIR` is empty, and are responsible for
managing or cleaning up any files they create.
* `TARGET` --- the target triple that is being compiled for. Native code should be
compiled for this triple. See the [Target Triple] description for more information.
* `HOST` --- the host triple of the Rust compiler.