`OUT_DIR` is not cleaned

[usamoi]

Problem

OUT_DIR is not cleaned before build scripts run, which is surprising.

Steps

build.rs:

use std::env::var_os;
use std::path::PathBuf;

fn main() {
    let out_dir = PathBuf::from(var_os("OUT_DIR").unwrap());
    {
        let r = std::fs::read_dir(&out_dir).unwrap();
        for x in r {
            dbg!(x.unwrap().file_name());
        }
    }
    std::fs::create_dir(out_dir.join("bits")).unwrap();
}

src/main.rs:

fn main() {}

1. cargo run
2. edit src/main.rs
3. cargo run

Then cargo prints

error: failed to run custom build command for `hh v0.1.0 (/usamoi/playground/hh)`

Caused by:
  process didn't exit successfully: `/usamoi/playground/hh/target/debug/build/hh-6d5c061eda957f22/build-script-build` (exit status: 101)
  --- stderr
  [build.rs:9:13] x.unwrap().file_name() = "bits"

  thread 'main' (257176) panicked at build.rs:12:47:
  called `Result::unwrap()` on an `Err` value: Os { code: 17, kind: AlreadyExists, message: "File exists" }
  note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This means that Cargo will not clean OUT_DIR before running build scripts, which is surprising! I cannot find any document about this behavior.

Possible Solution(s)

OUT_DIR should be cleaned before build scripts run.

Notes

No response

Version

cargo 1.91.1 (ea2d97820 2025-10-10)
release: 1.91.1
commit-hash: ea2d97820c16195b0ca3fadb4319fe512c199a43
commit-date: 2025-10-10
host: x86_64-unknown-linux-gnu
libgit2: 1.9.1 (sys:0.20.2 vendored)
libcurl: 8.15.0-DEV (sys:0.4.83+curl-8.15.0 vendored ssl:OpenSSL/3.5.2)
ssl: OpenSSL 3.5.2 5 Aug 2025
os: Arch Linux [64-bit]

[epage]

Hmm, we don't specify OUT_DIR in too much detail

From https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script

Build scripts may save any output files or intermediate artifacts in the directory specified in the OUT_DIR environment variable. Scripts should not modify any files outside of that directory.

From https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-build-scripts

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.

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

[epage]

The code in question

cargo/src/cargo/core/compiler/custom_build.rs

Lines 496 to 526 in bd97934

	paths::create_dir_all(&script_dir)?;
	paths::create_dir_all(&script_out_dir)?;
	let nightly_features_allowed = build_runner.bcx.gctx.nightly_features_allowed;
	let targets: Vec<Target> = unit.pkg.targets().to_vec();
	let msrv = unit.pkg.rust_version().cloned();
	// Need a separate copy for the fresh closure.
	let targets_fresh = targets.clone();
	let msrv_fresh = msrv.clone();
	let env_profile_name = unit.profile.name.to_uppercase();
	let built_with_debuginfo = build_runner
	.bcx
	.unit_graph
	.get(unit)
	.and_then(|deps| deps.iter().find(|dep| dep.unit.target == unit.target))
	.map(|dep| dep.unit.profile.debuginfo.is_turned_on())
	.unwrap_or(false);
	// Prepare the unit of "dirty work" which will actually run the custom build
	// command.
	//
	// Note that this has to do some extra work just before running the command
	// to determine extra environment variables and such.
	let dirty = Work::new(move |state| {
	// Make sure that OUT_DIR exists.
	//
	// If we have an old build directory, then just move it into place,
	// otherwise create it!
	paths::create_dir_all(&script_out_dir)
	.context("failed to create script output directory for build command")?;

yup, we create but not seeing any place we clear it.

What would "clear" it is if an input changes that affects -Cextra-filename

One advantage of the current approach is that it allows for the incremental building of C code. I thought we had an issue for a build script temp dir that is independent of -Cextra-filename but not finding it.

We should at least improve the documentation, including providing guidance around cleaning up.