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

### 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 rust-lang#16332

### How to test and review this PR?

_Documentation-only change._
_Review the updated notes in the Build Scripts and Environment Variables
sections._

Author: weihanglo

src/doc/src/reference/build-scripts.md

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

src/doc/src/reference/environment-variables.md

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