Setting build-dir prevent using cargo in build.rs

[vldm]

Problem

Setting build-dir in .cargo/config.toml prevent using cargo command in build.rs

>  cargo build
   Compiling cargo-build-generated v0.1.0 (/Users/__/work/cargo-build-generated)
    Building [========>                    ] 1/3: cargo-build-generated(build)

And it's halt in deadlock.

-vv shows:

[cargo-build-generated 0.1.0]     Blocking waiting for file lock on build directory (/Users/__/work/cargo-build-generated/./target2/build/debug/.cargo-build-lock)

Removing .cargo/config.toml with build.build-dir - fixes the problem.

Steps

1. create crate with build.rs that generate rust source and uses cargo to build
2. use OUT_DIR to save source
3. set build-dir in .cargo/config.toml
4. run cargo build

Possible Solution(s)

No response

Notes

MRE: https://github.com/vldm/cargo-build-generated

Workaround

(from comments)
One can set CARGO_BUILD_BUILD_DIR:

Command::new(&cargo)
        .arg("build")
        .env("CARGO_BUILD_BUILD_DIR", &generated)

Or put custom .cargo/config.toml (with build-dir set to $OUT_DIR/..)

Version

cargo 1.96.0 (30a34c682 2026-05-25)
release: 1.96.0
commit-hash: 30a34c6821b57de0aaec83a901aca39f88f6778c
commit-date: 2026-05-25
host: aarch64-apple-darwin
libgit2: 1.9.2 (sys:0.20.4 vendored)
libcurl: 8.7.1 (sys:0.4.87+curl-8.19.0 system ssl:(SecureTransport) LibreSSL/3.3.6)
ssl: OpenSSL 3.5.4 30 Sep 2025
os: Mac OS 26.5.0 [64-bit]

(but 1.94.0 was affected as well)

[hanna-kruppe]

I think the build script can fix this by overriding the build-dir for the nested cargo process via the environment variable CARGO_BUILD_DIR. Even without the deadlock, that would be a good idea to preserve the behavior of all build artifacts being stored under OUT_DIR.

[ranger-ross]

I took a look and what appears to be happening is:

When running without the config.toml the build-dirfor child cargo process is nested in the OUT_DIR like:

target/debug/build/<pkg>/<hash>/
    out/
        target/debug/....

Since the target directories are separate, the builds run completely in parallel.

When config.toml sets the build -dir, the child cargo process finds that file as it walks up the directory tree looking configs.
That causes both the child and parent Cargo's to share the same build-dir and thus deadlock.

From my perspective, Cargo is doing the expected behavior here. Like @hanna-kruppe mentioned, I think you should be able to work around this by overriding the build-dir in a config.toml in your template or via an env var in the build script.

[vldm]

Thanks for responses!

Yes, this workaround should work. (i'll test and update original Notes later)
And yes, technically cargo is working as expected. But i thought that this "lock" is suppose to save from parallel processes, not nested ones.
And I think that this might be unexpected behaviour for one who set build-dir.

Also this variable (build-dir and CARGO_BUILD_BUILD_DIR) is relatively new (so some old build script might be broken as well)

So, maybe cargo can do better:

1. provide a way to prevent nested cargo looking for external .config files? Either automatically, by setting some ENV variable for build scripts, or manually. This might improve forward compatibility of build-scripts. (e.g. if cargo adds some new global lock/state)
2. Give api to ask "parent" cargo to run some task. This will improve build-cache reusage.

[hanna-kruppe]

The lock serves to protect the build dir. If you have nested Cargo processes trying to use the same build dir, that has always been a deadlock. Your use case has previously side-stepped the problem since creating a manifest under OUT_DIR also implied that the build happened in $OUT_DIR/target. But nested cargo invocation that builds something from the source tree without copying it into OUT_DIR already had to pass --target-dir explicitly to work at all. So I expect the impact to be less widespread than "all nested cargo builds" (which doesn't necessarily mean it's not worth mitigating).

[weihanglo]

provide a way to prevent nested cargo looking for external .config files? Either automatically, by setting some ENV variable for build scripts, or manually. This might improve forward compatibility of build-scripts. (e.g. if cargo adds some new global lock/state)

If we did it automatically it may break other existing nested calls wanting to get those configs applied. If not, you can always override those via env vars. For general config discovery issue, see #7887 and linked issues in it.

Give api to ask "parent" cargo to run some task.

Would be great if you can share details about "some tasks", since our plan is to reduce usage of build.rs as possible as we could.

[ranger-ross]

#4282 may help mitigate this, though it won't guarantee no deadlocks for nested Cargo processes spawned from build.rs.

[vldm]

@hanna-kruppe

But nested cargo invocation that builds something from the source tree without copying it into OUT_DIR already had to pass --target-dir explicitly to work at all. So I expect the impact to be less widespread than

I have double checked MRE, and it looks like setting --target-dir in build-script doesn't help mitigate the issue.

@weihanglo

If we did it automatically it may break other existing nested calls wanting to get those configs applied. If not, you can always override those via env vars.

I'm not familiar with the scale of the problem, you definitely know better. But for me making default behaviour "prevent" reusing of config is better in context of forward compatibility. As i said before build-scripts that was written before introducing build-dir - now may breaks. (I encountered a similar problem when setting the default target for a project - like wasm32-unknown-unknown.)

I thought about some environment variable like CARGO_SKIP_CONFIG_LOADING that will be set by cargo for all build-script processes (and might be unset manually, rather that setting new env var for every param, when new option apear in cargo).
But CARGO_CONFIG_PATH var like proposed in #7887 might work as well (but not automatically)

Would be great if you can share details about "some tasks",

Ideally any cargo subcommand, but atleast build/check/doc?

Again, i am not familiar with cargo architecture, i thought about some kind of client-server interaction, e.g. when cargo is runned under other cargo, it tries to send IPC message instead of executing command.

[epage]

Wanting to check for understanding. This problem is not unique to build-dir but would also be an issue if a .cargo/config.toml set target-dir, right?

This would also not be a problem if build-dir included either {workspace-root} or {workspace-path-hash}, right? If so, what was your use case for setting build-dir without those variables? I'm looking to better understand users needs and workflows.

Would be great if you can share details about "some tasks",

Ideally any cargo subcommand, but atleast build/check/doc?

Again, i am not familiar with cargo architecture, i thought about some kind of client-server interaction, e.g. when cargo is runned under other cargo, it tries to send IPC message instead of executing command.

I think the question is more about the broader use case for nested invocations.

Nested invocations are a form of parallel invocation and trying to get them to interact intelligibly would be a lot of work, brittle, and possibly use case dependent for something (build.rs) that we are instead preferring people find alternative solutions to (#14948) which is why seeking to understand use cases is important.

[vldm]

@epage

This problem is not unique to build-dir but would also be an issue if a .cargo/config.toml set target-dir, right?
This would also not be a problem if build-dir included either {workspace-root} or {workspace-path-hash}, right?

Yes

If so, what was your use case for setting build-dir without those variables?

Initially - i wanted to reproduce wdanilo/crabtime#8, after adding OUT_DIR usage.

I haven't opened issue with proc-macro crate, since MRE would be bigger, and using OUT_DIR in proc-macro might be considered a hack?

If so, what was your use case for setting build-dir without those variables?

Firstly - i didn't know that this templating exist (and i am totally missed that last comment in issue already includes your quote with this workaround, sorry)
Secondly - i am not using build-dir by myself, but some folks recommended to use it (and previously target-dir) as replacement to sccache to speedup builds.

[epage]

Note the end-user using the template variables runs counter to the shared build-dir workflow. While we try to support it, it isn't a workflow we outright endorse.