Redefine CARGO_TARGET_DIR to be only an artifacts directory

[kornelski]

For design, see #14125 (comment)

For tracking the artifact-dir side of this, see #6790

Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-dir

Testing instructions: #14125 (comment)

Implementation

• unstable build-dir support (Implemented build.build-dir config option #15104)
• build-dir templating (Added build.build_dir templating support #15236)
  • fix(build-dir): Renamed workspace-manifest-path-hash to workspace-path-hash #15334
• cargo metadata support (Added build_directory field to cargo metadata output #15377)
• Document build_directory cargo metadata field (docs(metadata): Added build_directory to cargo metadata documentation #15410)
• workspace-path-hash should have symlinks resolved (Added symlink resolution for workspace-path-hash #15400)
• error on unmatched {, } (Added validation for unmatched brackets in build-dir template #15414)
• append closest_msg to unknown variable error (and maybe list all variables if no match is found?) (Improved error message when build-dir template var is invalid #15418)
• call for testing
• stabilize build-dir

Stabilizing this would also resolve

• Remap target dir #11156

Known issues:

• build_from_source makes assumptions on internal Cargo details, breaking cargo-miri with new build-dir features RalfJung/rustc-build-sysroot#25

Decisions

• cargo clean will clean both target-dir and build-dir
• Skipping including a CARGO_BUILD_DIR shortcut for CARGO_BUILD_BUILD_DIR (like CARGO_TARGET_DIR is a shortcut for CARGO_BUILD_TARGET_DIR)

artifact-dir files:

• build
  • binary executable for bin crates
  • binary executable for examples
  • depinfo files (.d files) for third party build-system integrations (see https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint/mod.rs#L194)
  • Cargo's --timings HTML report
• cargo package's generated .crate files
• cargo doc output (html/css/js/etc)

build-dir files (intermediate artifacts, build state, caches):

• build
  • "pre and non uplifted" binary executables. (ie. bins for examples that contain the hash in the name, bins for benches, proc macros, build scripts)
  • other depinfo files (generated by rustc, fingerprint, etc. See https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint/mod.rs#L164)
  • rlibs and debug info from dependencies
  • build script OUT_DIR
  • output from proc macros (previously stored in target/build)
  • incremental build output from rustc
  • fingerprint files used by Cargo for rebuild detection
  • Cache of rustc invocations (.rustc_info.json)
• cargo package's scratchpad used for the verify step
• CARGO_TARGET_TMPDIR files (see rational for this here)
• reports generated from cargo report like future-incompat-report

Open questions

• Are we good with the name build-dir?
  • Yes, discussed on 2025-03-18
• Should we offer CARGO_BUILD_DIR as a shortcut to CARGO_BUILD_BUILD_DIR, like CARGO_TARGET_DIR is for CARGO_BUILD_TARGET_DIR? see Implemented build.build-dir config option #15104 (comment)
  • No, discussed on 2025-03-18
  • End-users are most likely to set this globally in config
  • Env variable is most likely in CI
  • Length and "cleaner name" aren't priorities for the target audience, CI
• Should we stick with the name {workspace-manifest-path-hash} and what should it include? Should we shorten to {workspace-hash} or even just {hash}?
  • We should drop manifest, unsure about dropping either workspace or path. Users may be confused if they don't realize the path is a part of the hash
  • Renamed to workspace-path-hash in fix(build-dir): Renamed workspace-manifest-path-hash to workspace-path-hash #15334
• Should we include the Cargo version in {workspace-manifest-path-hash} so we get unique whole-target directories for easier cleanup (Garbage collect whole target/ #13136) deferred
• Should we resolve symlinks in workspace manifest-path before generating {workspace-manifest-path-hash}? See Added build.build_dir templating support #15236 (comment)
  • The cargo team leans towards doing so right now
  • As the hash is unspecified, we feel this is a two-way door
  • Added symlink resolution for workspace-path-hash #15400
• Should we keep erroring on unknown template variables? Should we start erroring on unmatch {? See Added build.build_dir templating support #15236 (comment)
  • Yes, we should error on unknown template variables. It is the least surprising, even if annoying, and provides better error messages (229489e)
  • Yes, we should error on unmatched {. This includes {{; escaping has been deferred (Added validation for unmatched brackets in build-dir template #15414)
• Should we take the advantage to self-ignore build.build-dir? Make target dir self-ignoring #15061
• Include in cargo metadata? What about that people need to match cargo metadata version against cargo to get it?
  • Yes, it should be included in cargo metadata but only the current one. Changing the hash on every cargo version has been deferred to reduce the need to provide build-dir for all cargo versions
  • Added build_directory field to cargo metadata output #15377, docs(metadata): Added build_directory to cargo metadata documentation #15410
• Should we offer CARGO_BUILD_TMPDIR, deprecating CARGO_TARGET_TMPDIR?
• should we offer the workspace base name either as a prefix to the hash or as its own variable for making it easier for humans to find delete specific build dirs

Deferred

• {workspace-manifest-hash} also hashes the cargo version
  • Excludes release channel information, including which nightly
  • Allows easier cleanup on rustup update (Garbage collect whole target/ #13136)
  • Makes very clear that the hash's meaning is unstable
  • Blocked on Garbage collect whole target/ #13136 (maybe more?) to reduce the need for third-party clean up tools which will need to know the path to every build-dir for a workspace
• In templates, {{ is an escaped {
  • With us erroring on {, we have the room to allow escaping in the future
  • We'd like escaping support to be based on use cases and not speculatively developed as { in paths is rare and this isn't a general path

Original Issue:

---

Problem

There are a couple of issues with the CARGO_TARGET_DIR that are seemingly in conflict with each other:

1. Multiple locations of target dirs complicate excluding them from backups and full-disk search, cleanup of the temp files, moving temp files to dedicated partitions, out of slow network drives or container mounts, etc. Users don't like that the target dir is huge, and multiple instances of it add up to lot of disk space. Users would prefer a central location to ease management of the temp files, and also to dedupe/reuse dependencies across many projects.

2. People (and tools) are relying on a relative ./target directory being present to copy or run built files out of there. Additionally, users may not want to configure a shared CARGO_TARGET_DIR due to risk of file name conflicts between projects.

However, the dilemma between 1 and 2 exists only because Cargo uses CARGO_TARGET_DIR for two different roles:

1. A cache for all intermediate build products (a place where crates.io crates are built, where compiler-private temp files are) which aren't project-specific, and/or files that users don't need to access directly.
2. A location for user-facing final build products (artifacts) that users expect to be there and need to access.

Proposed Solution

So to satisfy both uses, I suggest to change the thinking about what the role of CARGO_TARGET_DIR should be. Instead of thinking where to put the same huge all-purpose mixed CARGO_TARGET_DIR, think how to deduplicate and slim CARGO_TARGET_DIR, and move everything non-user-facing out of it.

Instead of merging or sharding the CARGO_TARGET_DIR as-is with all of its current content, and adding --artifact-dir as a separate place where final products are being copied to — make CARGO_TARGET_DIR to be the artifact dir (without copying).

As long as the CARGO_TARGET_DIR dir is the place for all of the build files, of all crates including all the crates.io and local builds, with all the caches, all the temp junk, then this is going to be a problematic large directory that needs to be managed. But if the purpose of the ./target dir was changed to be only for user-facing files (files that users can name, and would access via ./target path themselves), then this directory would be relatively small, with a good reason to stay workspace-relative.

What isn't an intermediate build product? (and should stay in ./target)

• linked (and stripped) binaries of the current workspace, including binaries for the examples,
• libraries of the current workspace as .a/.so, where lib.crate-type calls for them. Possibly .rlib/.rmeta in the future if there's a stable ABI.
• linked binaries for tests and benches of the current workspace (to make it easy to launch them under a debugger/profiler, and so they can use relative file paths to read workspace assets).
• debug symbols for all of the above.
• .d files for all of the above (so that IDEs and other build systems know when to rebuild the artifacts).
• if Cargo adds some "staging" directory (a non-private OUT_DIR for build.rs, see Allow build scripts to stage final artifacts #13663), then for build scripts belonging to the current workspace it would be inside ./target as well.

So generally files that users build intentionally, and may want to access directly (run themselves, or package up for distribution) and files that users may need configure their IDE and debugger to find inside the project.

Crates in [patch.crates-io] with a path are a gray area, an might also have their artifacts included in the ./target dir (but in some way that avoids clobbering workspaces' files).

What isn't a final build product, and doesn't belong to ./target:

• anything related to building crates from crates.io, or any other registry (packages with source = "registry+…")
• all .fingerprint and incremental dir content of all crates. These are implementation details of the compiler, and nobody should be accessing these directly via ./target/….
• .o files. Users are not supposed to use them directly either (Rust has static libs for this).
• proc macro libs. They're not useful without rustc present.

All of these should be built in some other shared build cache dir (one that is not inside CARGO_TARGET_DIR), configurable by a new option/env var.

Registry dependencies would get unique paths derived from rustc version + package IDs + enabled features (so that different crates using different features don't invalidate each others' caches all the time). This would enable sharing built crates.io dependencies across all projects for the same local user, without also causing local workspaces to clobber each others' CARGO_TARGET_DIR/profile/product paths. Temp directories for local projects would need some hashed paths in the shared build/temp dir too.

Advantages

• Such split removes about 90% of the weight from ./target dirs (for cargo itself, it makes ./target/debug with binaries and tests take 415MB, instead of 4.2GB). This makes cleanup of all the scattered target dirs less of a pressing problem.
• The ./target keeps relatively few files, and removes high-frequency-churning files out of it, which makes it less of a problem for real-time disk indexing (like search and backups on macOS).
• I/O latency of ./target stops being critical for build speeds, unlike I/O of the incremental cache and rewrites of thousands of .o files. It becomes feasible to have project directory on a network drive without overriding CARGO_TARGET_DIR (network filesystems are used by non-Linux systems where tools like Vagrant and Docker have to run full-fat VMs, and can't cheaply share the file system).
• It makes ./target contain only workspace-unique files, which makes it justified for every workspace to have one.
• It enables moving registry deps to a shared build directory, without side effect of local projects overwriting each others' files. Sharing of dependencies matches users' expectation that the same dependencies shouldn't be redundantly rebuilt for each local project.
• It's almost entirely backwards compatible. Users can get the benefits without breaking their existing workflows, post-build scripts, and integrations. It doesn't invalidate documentation/books/tutorials that refer to target/release/exe etc.
• It could be the default behavior, so it could benefit all users without friction of adding --artifact-dir or .cargo/config.

Notes

No response

[kornelski]

In terms of incompatibilities, only a few come to my mind:

• Hacks that recursively search ./target looking for a file built by some build script in its OUT_DIR. Ideally this should be solved by adding proper support for building arbitrary assets in Cargo, but for the sake of keeping compatibility with CARGO_TARGET_DIR, this could be made to work by keeping OUT_DIRs as subdirectories or symlinks in ./target.

• Binaries trying to link to .so/.dylib of their Rust dependencies, where the deps are built by Cargo, and are not installed on the system. This is currently basically unsupported in Cargo, because there's no way to set rpath to anything that works (absolute path is too build-specific, and relative doesn't work for tests and examples that are in a different dir than bins). But if users are hacking around it with custom post-build steps, they may expect to find the 3rd party shared libs in ./target. This again would be better solved by having Rust/Cargo aware of dylib dependencies, and copy/hardlink dylibs as needed and set rpath accordingly. Not many deps have crate-type = "cdylib", so these also could be kept/symlinked in ./target for back-compat.

• Build containers could have very strict read-only filesystems with only CARGO_TARGET_DIR and CARGO_HOME subdirs being writeable. This could be made backwards-compatible by reverting back to the current everything-in-one-place behavior when CARGO_TARGET_DIR is set, and picking other env vars for configuring locations of the trimmed ./target and the intermediate products cache dir.

[epage]

@poliorcetics from rust-lang/rfcs#3664 (comment)

Yes, the issue should be moved to cargo I think.

I'm not convinced at all this won't break backwards compatibility in some way.

It makes ./target contain only workspace-unique files, which makes it justified for every workspace to have one.

And I don't want one in any cargo project while still keeping isolation, which is entirely different from what you are proposing.

It enables moving registry deps to a shared build directory, without side effect of local projects overwriting each others' files. Sharing of dependencies matches users' expectation that the same dependencies shouldn't be redundantly rebuilt for each local project.

Once again, the RFC I wrote and original issue I inspired myself from do not ask for that, it asks for the opposite: myself and many others want separate targets dirs for every project.

There are probably as many reasons as there are users for it but common ones are different sets of features amongst projects, sharing of build caches for specific projects, CI builds wanting to separate projects for security, or one project pinning 1.2.3 in a dep B of a dep A and the other project pinning 1.2.4: A can have the same version for both but it's dependencies won't and cargo is not made to handle the case at the moment.

You are fundamentally solving a different issue, one that the RFC I posted is not trying to solve.

[epage]

Overall, I see this as a solution alternative to #6790 and had recommended we have that conversation there (or on internals).

What isn't an intermediate build product? (and should stay in ./target)

This is likely going to be the most difficult topic to work through and we'll need to make sure we get wide input on this from #6790 users and others.

Registry dependencies would get unique paths derived from rustc version + package IDs + enabled features (so that different crates using different features don't invalidate each others' caches all the time). This would enable sharing built crates.io dependencies across all projects for the same local user, without also causing local workspaces to clobber each others' CARGO_TARGET_DIR/profile/product paths. Temp directories for local projects would need some hashed paths in the shared build/temp dir too.

imo this is out of scope for this proposal (see #5931) and we should keep this focused so as not to get distracted.

[epage]

I see this as a re-framing of the problem, addressing #6790 and rust-lang/rfcs#3371

Instead of us defining a new artifact-dir, we say target-dir is the artifact directory and move everything else out into a "working directory".

• The move can be gradual as these files are considered implementation details.
• We avoid "yet another flag" problem of --artifact-dir because controlling of the location of the "working directory" is too low level for the CLI and should be reserved for config
• A big downside compared to --artfact-dir is that target-dir is not the final directory files are put under but the parent directory. This is especially annoying for cargo build vs cargo build --target, dealing with profile names, etc

Potential names

• working-dir (arbitrarily chose this one to refer to the concept moving forward)
• build-dir

Cargo script would default its target-dir as its working-dir

This would need input from

• artifact-dir users
• cache / cache clean up users
• random other systems that dig into the target dir

[epage]

This would need an audit of ways we publicly treat the target dir as a working dir, like exposing CARGO_TARGET_TMPDIR

[ensc]

Sharing sources over NFS adds another incompatibility when the ability to move ./target out of the sources is eliminated.

Every modern buildsystem allows to keep sources and build results separated (and users and tools do not have problems with it). I do not think that cargo should go the way back and enforce a fixed ./target directory.

[kornelski]

I'm not suggesting to force it to always be ./target. The CARGO_TARGET_DIR can continue to move this directory elsewhere.
The main point is to reduce severity of problems that the current high-churn high-volume content of this dir causes.

[epage]

We talked about this in today's Cargo team meeting.

Our care abouts include

• Moving intermediate artifacts away
  • Having a transition plan for tool authors
• Providing a profile-agnostic location for final artifacts
• Resolving the "elide target when host" within the final artifact path
• Having a coherent story for users, for example
  • Users today mostly interact with target-dir for dealing with final artifacts, so we likely want to preserve that
  • If we create a new directory for intermediate artifacts, we might not want to templatize target-dir as that will push people down one path moving intermediate artifacts and then we completely change it on the user what path they should go, rather than having a stable story for how to handle this

While we acknowledged the potential for user confusion with CARGO_TARGET_TMPDIR, we were fine with it not being associated with target-dir

The general shape of what we proposed in the meeting is...

Shiny future

target-build-dir: Home of intermediate artifacts

• Goals:
  • Move intermediate artifacts out of source
  • Don't force a transition for what term/variable people reach out to to access final artifacts
• name is a placeholder
• No CLI flag for target-build-dir
• Precedence (note the lack of target-dir)
  • target-build-dir config
  • target-build-dir default ("{cargo-cache}/target/{workspace-manifest-path-hash}")

target-artifact-dir: Home of final artifacts

• Goals:
  • Provide profile-agnostic path
  • Provide a way for users to opt-out of the target-platform from being elided when building for the host-platform
• name is a placeholder (e.g. do we want the target prefix)
• --artifact-dir CLI flag is added
• will error if {platform} or {legacy-platform} is not present with multi-target builds
• Precedence
  • target-artifact-dir config / cli
  • target-dir config / cli
  • target-artifact-dir default ("{workspace-root}/target/{legacy-platform}/{profile}")

Legacy target-dir

• --target-dir is hidden on CLI. Maybe shows up in man pages
• No templating supported

Other

• CARGO_TARGET_TMPDIR points within target-build-dir

Path to Shiny Future

target-build-dir

In theory, we could trivially do this by

• locking target-build-dir and target-dir (if different)
• doing all work in target-build-dir and only when we do the "hardlink or cp" do we reference target-dir

Initial default is "{workspace-root}/target"

Template supports

• {workspace-root}
• {cargo-cache} (pointing to CARGO_HOME for now)
• {workspace-manifest-path-hash}

Steps

1. Implement
2. Call for testing
3. Stabilize with opt-in to new location
4. Call for testing
5. Switch to opt-out

Notes:

• Throughout those steps, we would work closely with tool authors to make sure they had a smooth transiti
• The opt-in/opt-out could either be
  • .cargo/config.toml target-build-dir field
  • A one-off environment variable if we don't want to stabilize the above yet

target-artifact-dir

Assumption: target-build-dir takes some pressure off of target-artifact-dir

Defaulted to final location ("{workspace-root}/target/{legacy-platform}/{profile}")

Template supports

• {workspace-root}
• {cargo-cache} (pointing to CARGO_HOME for now)
• {workspace-manifest-path-hash}
• {platform}
• {legacy-platform} (elides host-target)

Needs all of the details in the tracking issue to be finalized.

Contingencies

If target-build-dir takes more than N time (1 year?) to stabilize, then we re-evaluate approving rust-lang/rfcs#3371. This is to try to balance the needs of the people who want something like rust-lang/rfcs#3371 now vs (1) the long-term inapplicability of that RFC and (2) the lack of stable "blessed" workflow for users (telling users to use solution X for several months and then telling them that is no longer "right" and they need to use solution Y).

Alternatives

• Maintain target-dir as the "artifact base dir" and provide a query command (like buck2 analyze) to ask what the "artifact dir" is
• Don't expose target-artifact-dir in CLI, leaving it for more advanced uses
• Have only target-dir and target-artifact-dir
  • Downside: harder end-user transition as they reach out to target-dir for final artifacts. While we eventually de-emphasize target-dir, those workflows will work just fine
• Have only target-dir and target-build-dir
  • Downside: access to final artifacts is still annoying
  • Only append final directories ({platform}/{profile}) if no templates are available
    • Downside: this would be confusing
    • We do this for {dl} but that is a more limited / off in the weeds use case rather than front and center for users
• Change the meaning of target-dir if target-build-dir or target-artifact-dir is present
  • This gets confusing

[epage]

Something we overlooked in the above analysis is other "artifacts". In particular, I'm thinking of cargo package which places files in $CARGO_TARGET_DIR/packages. I'm assuming at least the .crates location is part our stable API. We'd need to decide about the files laid out on disk next to it.

Ways of solving this

• Like examples going to examples/, we could make the profile and target template dirs blank and always put this under packages/
• We could have a high level {default} variable that is artifact-specific.

[clarfonthey]

Just commenting here as I'm dealing with my own issues regarding the target dir, but personally, while it's nice for target to contain final build products only by default, I still will want all of these build products out of the target directory for the sake of excluding them from backups and snapshotting.

For some context, I use ZFS snapshots as a form of fast local backups; not long-term backups in case of hardware or extreme software failure, but decent short-term backups in case I accidentally delete a file or mess up an update. However, I explicitly go out of my way to exclude as many things as possible from auto-snapshotting that qualify as "cache" because they can very quickly clog up my disk if I'm not careful.

(Also: since snapshotting is a filesystem-level feature, I can't just say "don't save files of this type in snapshots" since snapshotting works by instantly freezing the state of the FS into a snapshot, and doesn't copy files over like a long-term backup would.)

For example, today I just deleted 200 GiB of snapshots of target directories. Not the current target directories, but past versions of them from previous snapshots. Snapshots are good for incremental stuff like code because they're copy-on-write, but the contents of a binary are effectively random to any snapshotting tool and they'll end up being fully duplicated every time they're snapshotted, and that means you can end up with several times that amount of data in snapshots until everything eventually gets old enough to be deleted. The "effectively random" part also applies especially to the final products, since while crates that don't change won't change in their compiled artifacts, the final linked products definitely will.

So, as far as I'm concerned, moving the final build products back into the workspace without also having the option to keep them out effectively un-solves the problem that moving the target directory was meant to solve. After all, the final build products, modulo LTO (which isn't really going to happen for debug builds) will effectively be the same size as all the intermediate products, so, that means that about half the disk usage will not be saved. (I'm extremely approximating here; the point is that it's a considerable amount of the disk usage, even if it's not half. Even 10% of the size is still a lot when you consider that these are being multiplied across several snapshots.)

And note that yes, other languages like Node and Python also have this exact same problem, but I don't think that other languages' inability to solve this problem forgives Rust not solving it. Also, even though node_modules can be massive, hundreds of GiB of binary artifacts is pretty hard to beat.

I love the idea of keeping intermediate products deduplicated and in one place. I just don't want that to obscure the goal of having the final products also somewhere else too.

[kornelski]

After all, the final build products, modulo LTO (which isn't really going to happen for debug builds) will effectively be the same size as all the intermediate products

No, the intermediate products are usually many many times larger. Not just double, they can be 1000× larger! On the project I'm currently working, a clean debug build of a 20MB executable creates 2300MB of junk in target/. After working on it for a while, it grows to 13GB of temp data for a 20MB result.

There are often many duplicate copies of libstd and other dependencies in each .rlib file. There is a lot of duplication across code units. There's plenty of completely unused objects included in the dependencies, and stripped even without LTO (rust relies on --as-needed flag). There are also often separate copies for build dependencies, builds with cfg(test), and incremental build cache.

[epage]

@clarfonthey the plan calls for both target-work-dir and target-artifact-dir to be templated so you can move their content out. It does not call out templating of target-dir as it calls for phasing that out. If we wanted to templatize it as a convenience way of setting both of the above, we'd likely want to wait for the above so we set the precedence for what people are generally expected to work with, rather than shifting expectations around on the user.

[mathstuf]

I still will want all of these build products out of the target directory for the sake of excluding them from backups and snapshotting.

FWIW, I've had decent results with target being a symlink to somewhere that is not subject to backups/snapshotting. cargo clean will remove the symlink, but everything else I've used is largely fine. Note that this puts intermediate and final artifacts into the same bucket.

[nazar-pc]

I'm in the same boat as @clarfonthey, but with BTRFS snapshots, which I create every 15 minutes and then stream to longer-term storage. My debug builds are easily 2.5G and I clean up target that is 300-700G basically every week.

I created ~/.cache/cargo/{git,registry,target} for this reason, where ~/.cache is in a separate subvolume that is not subject for snapshotting/backups. ~/.cargo/{git,registry} are symlinks now (still hoping cargo starts respecting XDG one day) because they also grow to substantial sizes (currently 1.08M files and 24.1G together).

Proposed separation (especially templating for both new options) should work nicely for such use case, CARGO_TARGET_DIR in .profile has major consequences for build times when jumping between projects.

Excited!

[Nemo157]

Personally I also don't care about having the artifacts copied anywhere, I access them via cargo run etc. directly from the work-dir anyway. It'd be nice if we could do something like target-artifact-dir = false to just disable it.

[ranger-ross]

Personally I also don't care about having the artifacts copied anywhere, I access them via cargo run etc. directly from the work-dir anyway. It'd be nice if we could do something like target-artifact-dir = false to just disable it.

My understanding is the the target-artifact-dir will default to {workspace-root}/target/{legacy-platform}/{profile} so it will still be contained in the target directory by default. If you are only running your project via cargo run I don't think you need to worry about the exact location of the binary in the target dir?

One question I have is about the handling of building for the host platform.
Running cargo build & cargo build --release will build artifacts to target/debug/ and target/release/ dirs respectively.
Changing this would be a fairly big user facing change and will result in a lot of churn in the ecosystem.
If I am reading this correctly, I am assuming that this default behavior will stay the same unless the user explicitly opts to use target-artifact-dir to change it.
The new target-artifact-dir default would apply if a --target is passed to the cargo build.

Is this correct?

[Nemo157]

If you are only running your project via cargo run I don't think you need to worry about the exact location of the binary in the target dir?

One thing I do care about the artifact locations is that they are not in a sub-dir of the repository. Having large temporary artifacts mixed in with the source code complicates backups and filesystem snapshots. This is why I would prefer to disable the target-artifact-dir and just leave all intermediate and final artifacts somewhere in ~/.cache/cargo.

[epage]

Call for testing

build-dir is now available in nightly and we're looking for feedback to see if this can be stabilized!

This allows users to move intermediate build artifacts into a location separate from final artifacts. Use cases include

• Moving build artifacts to a location with faster IO
• Making it easier to periodically find and delete all of the large build caches (see also Garbage collect whole target/ #13136)
• Avoid being picked up by filesystem snapshotting

This can be set in user config (e.g. ~/.cargo/config.toml) without workspaces conflicting with each other due to the support for templating

e.g. ~/.cargo/config.toml

[build]
build-dir = "{cargo-cache-home}/build/{workspace-path-hash}"

Future possibilities

• Change the default build-dir location (e.g. to the value above)
• Change the layout of files within build-dir (Re-organize build-dir by package + hash, rather than artifact type #15010)

Special thanks to @ranger-ross for implementing this!

Basic steps:

Requirements:

• 1.88.0-nightly (092a284ba 2025-04-13) or newer

See the unstable docs for what is supported

Please test your workflows with -Zbuild-dir, including:

• With and without setting build.build-dir / CARGO_BUILD_BUILD_DIR
• Explicit and default build.target-dir
• Various commands that write different kinds of data/locations within target-dir (cargo check, cargo build, cargo package, cargo doc, etc)
• Tests (including after a cargo clean)
• Tools and processes that may touch target-dir (e.g. CI caching, cargo-cache, cargo-sweep, coverage collection)

When testing, please consider

• Does the division of files between build-dir and target-dir make sense?

Notes:

• {manifest-path-hash}s hash is not guaranteed to be stable between releases and, in fact, we may go as far as also hashing the Cargo version as that blends well with Garbage collect whole target/ #13136.
• {cargo-cache-home evaluates to CARGO_HOME for now but is named as such to be prepared for Use OS-native config, cache home directories #1734

Known issues:

• snapbox, asserrt_cmd binary-under-test lookup functions will fail with a custom build-dir (the macro should still work)
• Cargo build-dir support holmgr/cargo-sweep#140
• Cargo build-dir support matthiaskrgr/cargo-cache#143
• Cargo build-dir support taiki-e/cargo-llvm-cov#432
• Cargo build-dir support xd009642/tarpaulin#1721

Please leave testing reports on this issue; feel free to open dedicated issues for bugs

[asomers]

Test report

I tested this feature with the mdconfig, libnv-rs, and fsx crates on FreeBSD 15 amd64, as well as with a complicated unpublished crate. It's a big step forward!

What worked:

• Using either .cargo/config.toml or $HOME/.cargo/config.toml
• Using either the CARGO_BUILD_BUILD_DIR variable or an entry in .cargo/config.toml
• Using the {cargo-cache-home}, {workspace-path-hash}, or {workspace-root} templating variables for build-dir
• Omitting -Zbuild-std restores legacy behavior
• Executing tests with a non-default build-dir.
• cargo doc could build the tests, though it didn't put the html files in build-dir.
• Running cargo +nightly -Zbuild-dir test in a workspace with a rust-toolchain.toml file, as long as I explicitly specified +nightly.
• Building crates with build scripts.

What did not work

• The assert_cmd crate did not work, as noted by @epage .
• Using templating variables for target-dir. For my workflow, that's important. I share the same source directory (over NFS) between VMs running different operating systems, so I really do want to move finished binaries to alternate locations. Moving html files generated by cargo-doc would be good too.

Another feature request
While {workspace-path-hash} works well for automated tools, it's not so great for human use. It would be convenient for me, though not strictly necessary, to have a template variable that would expand to the base name of the workspace root. That would make it easier for me to clean up my temporary files when my HDD fills up and I have two dozen crates with builds lying around.

[epage]

Thanks for giving it a spin!

cargo doc could build the tests, though it didn't put the html files in build-dir.

the html files were considered a "final artifact" so we kept them in target-dir. This is a problem of use cases

• cargo doc --no-deps is important for publishing documentation (final artifact)
• cargo doc is important for development

Using templating variables for target-dir. For my workflow, that's important. I share the same source directory (over NFS) between VMs running different operating systems, so I really do want to move finished binaries to alternate locations. 

We plan to add an artifact-dir which would be templated and phase out target-dir. Technically templating would be a breaking change for target-dir though it is unlikely to affect anyone. The question would be if templating for target-dir until we have artifact-dir would be worth the effort, including the compatibility analysis.

While {workspace-path-hash} works well for automated tools, it's not so great for human use. It would be convenient for me, though not strictly necessary, to have a template variable that would expand to the base name of the workspace root. That would make it easier for me to clean up my temporary files when my HDD fills up and I have two dozen crates with builds lying around.

While you can look it up with cargo metadata, I agree that prefixing the hash with the basename (or offering a variable for the base name) would make this a lot more convenient for humans.

[asomers]

Thanks for giving it a spin!

We plan to add an artifact-dir which would be templated and phase out target-dir. Technically templating would be a breaking change for target-dir though it is unlikely to affect anyone. The question would be if templating for target-dir until we have artifact-dir would be worth the effort, including the compatibility analysis.

Ahh, that sounds like it would work for me.

While {workspace-path-hash} works well for automated tools, it's not so great for human use. It would be convenient for me, though not strictly necessary, to have a template variable that would expand to the base name of the workspace root. That would make it easier for me to clean up my temporary files when my HDD fills up and I have two dozen crates with builds lying around.

While you can look it up with cargo metadata, I agree that prefixing the hash with the basename (or offering a variable for the base name) would make this a lot more convenient for humans.

Is it possible to use cargo metadata within .cargo/config.toml? Alternatively, prefixing the hash with the basename would also work for me.

[xd009642]

Test report

I tested this feature by using tarpaulin with build dir on a few projects. Using the llvm and ptrace engine (as both have slightly different requirements in terms of artefacts). It all worked as expected, likely due to tarpaulin mostly relying on cargo_metadata to get paths to artefacts instead of relying on any structure of the target directory.

• Using either .cargo/config.toml
• Using either the CARGO_BUILD_BUILD_DIR variable or an entry in .cargo/config.toml
• Using the {cargo-cache-home}, {workspace-path-hash}, or {workspace-root} templating variables for build-dir
• Omitting -Zbuild-std restores legacy behavior
• Executing test and doc-test coverage with a non-default build-dir.
• I also tried slightly messing up the template vars or making up ones and error messages were as expected (suggesting ones with close string distance, unexpected var with quotes around the name etc.

How I messed up (what didn't work)

• Initially I was lazy and didn't use $HOME but ~, which I should know wouldn't work (but it's early). This resulted in a ~ directory in my project which is understandable. Maybe something that warrants a compiler warning 🤷

[epage]

FYI assert_cmd 2.0.17 is out with cargo::cargo_bin! which should work with build-dir.

Note that snapbox already had cmd::cargo_bin!.

This just leaves the use case when a dependency wants to do the test binary lookup (e.g. like cargo-test-support does for cargo's tests)

[riverar]

I'm having a hard time understanding the new feature. The docs, your comments, etc. use the term intermediate but I can't find what the final state is. Are these intermediate files copied somewhere after the crate is compiled? After the entire build is complete? Other?

Your last comment ("This just leaves the use case...") seems to imply you covered the "I want to deploy files to the target dir" scenario but I don't understand how to use this feature to do so.

Edit: I came from #9661 (comment) and I think I understand now. This feature is orthogonal to the efforts there and you were just providing a heads up of possible impact to workarounds.

[kornelski]

1. The requirement to add -Zbuild-dir makes it harder to test the feature, since it's hard to control all the places that invoke cargo, such as editors that run cargo check or nested build systems and build.rs scripts that invoke Cargo themselves. For experimental rustc features I can set rustflags in ~/.cargo/config.toml, but Cargo doesn't have such thing for itself AFAIK.

2. I was surprised that {workspace-path-hash} is not a single path component, but has a 2-char directory prefix. I assumed it'd be alphanumeric single component, since it's a hash of a path, not a path itself. Hopefully not a big deal, since I won't need to navigate these directories manually, just unexpected.

3. Can this be used as an opportunity to always add the target triple to the path? I've ended up with both ~/Library/Caches/Cargo/{workspace-path-hash}/debug and ~/Library/Caches/Cargo/{workspace-path-hash}/my-host-triple/debug dirs. Since these directories are out of users' view, they could be made predictable instead of short for user convenience. The irregularities with the optional triples and --profile=dev being debug in the path were annoying when building cargo-xcode and cargo-deb.

[epage]

The requirement to add -Zbuild-dir makes it harder to test the feature, since it's hard to control all the places that invoke cargo, such as editors that run cargo check or nested build systems and build.rs scripts that invoke Cargo themselves

‘-Z` flags can be set through the config system, see https://doc.rust-lang.org/cargo/reference/unstable.html

Can this be used as an opportunity to always add the target triple to the path?

Maybe eventually

• We should keep this specific change focused and iterate in steps past it
• It will help if we first make more explicit our current lack of guarantees around the build dir before making further changes. In fact, changing the layout is the reason ranger-ross has been contributing these changes. Their focus is on changing the layout in prep for a shared cache.

[zopsicle]

Test report

This feature appears to work great for my use case detailed here: #6100 (comment)! Using the following commands:

cargo build \
    -Zbuild-dir \
    --config 'build.build-dir = ".build/cargo"' \
    --config 'build.target-dir = ".build/ush"' \
    --package ush

cargo build \
    -Zbuild-dir \
    --config 'build.build-dir = ".build/cargo"' \
    --config 'build.target-dir = ".build/ush-lsp-server"' \
    --package ush-lsp-server

where ush-lsp-server depends on ush with additional features; feature unification is correctly inhibited by building separately; overwriting of artifacts is correctly inhibited by specifying different target-dirs; and repeated compilation of code not affected by the features is correctly avoided by specifying the same build-dir.

cargo test works properly with or without target-dir. It seems to write no artifacts, as expected.

cargo doc works properly: the rustdoc output is written to target-dir.

[Nemo157]

Having {cargo-cache-home} resolve to CARGO_HOME feels like it exposes the possibility of conflicts between cargo's future use of that directory and arbitrary user config, e.g. as an absurd setting build-dir = "{cargo-cache-home}/registry/src/index.crates.io-1949cf8c6b5b557f".

I'm not sure if there's really anything nice that can be done about this, just thought it'd be worthwhile to note as I don't recall it being mentioned before. (I've long wondered what would happen if cargo integrated native audit support and wanted to use CARGO_HOME/audit.toml when cargo-audit has already claimed that as its own).

[teohhanhui]

I'm not sure if there's really anything nice that can be done about this

Don't expose cargo-cache-home but a cargo-build-home maybe?

[epage]

Having {cargo-cache-home} resolve to CARGO_HOME feels like it exposes the possibility of conflicts between cargo's future use of that directory and arbitrary user config, e.g. as an absurd setting build-dir = "{cargo-cache-home}/registry/src/index.crates.io-1949cf8c6b5b557f".

I'm not seeing how this is a new problem. Someone can already construct a path like this without variables. Granted, this makes it easier but I could see offering a {home} which is the minimum for making this easier. We also don't prevent top-level ../ so if we had an alternate location, users could still reach it.

As for future use, I'm not quite sure what you mean but when we make CARGO_CACHE_HOME, registry/ will be a part of it, so this possibility won't change. audit.toml wouldn't be though.

[Nemo157]

I'm not seeing how this is a new problem. Someone can already construct a path like this without variables.

I think it's more obvious that using a path like build-dir = "~/.cargo/builds" is reaching into internal implementation details and might cause issues (though, apparently not for a lot of third-party subcommand authors). Using a variable that seems to be explicitly for this usecase makes it less likely for users to consider it.

As for future use [...]

I mean that a setting for build-dir that is ok now may conflict with new subdirectories/files introduced by cargo in future versions. This is not entirely theoretical, my previous setting of target-dir = "~/.cargo/target" ran into this conflict with -Zscript.

---

The only thought I have to actually doing something about this is either documentation about what cargo expects from subdirectories of CARGO_HOME/CARGO_CACHE_HOME, or having a variable more like $CARGO_HOME/user/ which is explicitly set aside for arbitrary files outside cargo's control.

[ranger-ross]

The discussion above got me thinking about how cargo clean interacts with the build-dir & the templates.

I did some testing and discovered that setting build-dir = "{cargo-cache-home}" causes Cargo to delete the .cargo upon executing cargo clean. It will also delete the current workspace dir if build-dir = "{workspace-root}" is set.

I also checked CARGO_TARGET_DIR and it has the same behavior. (without templating ofc)

This feels like a potential footgun.

Given the name {cargo-cache-home}, I think it might be reasonable for one to set build-dir = "{cargo-cache-home}" if they did not read the documentation.

Having {cargo-cache-home} point to a inner directory like CARGO_HOME/build would mitigate this but it would not help with {workspace-root}.
Alternatively, we could modify cargo clean to abort if build-dir/target-dir == CARGO_HOME/workspace-root,
or perhaps disallow setting build-dir to be {cargo-cache-home}/{workspace-root} with subpaths.

[ensc]

miri (13e8790949 2025-05-04) fails to run with

$ cargo miri clean
$ cargo miri test
Preparing a sysroot for Miri (target: x86_64-unknown-linux-gnu)... fatal error: failed to build sysroot: failed to read cargo out dir

Caused by:
    No such file or directory (os error 2)

when

[build]
build-dir = "{cargo-cache-home}/build/{workspace-path-hash}"

[unstable]
build-dir=true

is set in ~/.cargo/config.toml.

After disabling these lines, miri can create the sysroot and works when these lines are reenabled.

[epage]

I've opened an issue at RalfJung/rustc-build-sysroot#25