Build cache
Cargo stores the output of a build into the “target” directory. By default,
this is the directory named target
in the root of your
workspace. To change the location, you can set the
CARGO_TARGET_DIR
environment variable, the build.target-dir
config
value, or the --target-dir
command-line flag.
The directory layout depends on whether or not you are using the --target
flag to build for a specific platform. If --target
is not specified, Cargo
runs in a mode where it builds for the host architecture. The output goes into
the root of the target directory, with each profile stored in a separate
subdirectory:
Directory | Description |
---|---|
target/debug/ | Contains output for the dev profile. |
target/release/ | Contains output for the release profile (with the --release option). |
target/foo/ | Contains build output for the foo profile (with the --profile=foo option). |
For historical reasons, the dev
and test
profiles are stored in the
debug
directory, and the release
and bench
profiles are stored in the
release
directory. User-defined profiles are stored in a directory with the
same name as the profile.
When building for another target with --target
, the output is placed in a
directory with the name of the target:
Directory | Example |
---|---|
target/<triple>/debug/ | target/thumbv7em-none-eabihf/debug/ |
target/<triple>/release/ | target/thumbv7em-none-eabihf/release/ |
Note: When not using
--target
, this has a consequence that Cargo will share your dependencies with build scripts and proc macros.RUSTFLAGS
will be shared with everyrustc
invocation. With the--target
flag, build scripts and proc macros are built separately (for the host architecture), and do not shareRUSTFLAGS
.
Within the profile directory (such as debug
or release
), artifacts are
placed into the following directories:
Directory | Description |
---|---|
target/debug/ | Contains the output of the package being built (the binary executables and library targets). |
target/debug/examples/ | Contains example targets. |
Some commands place their output in dedicated directories in the top level of
the target
directory:
Directory | Description |
---|---|
target/doc/ | Contains rustdoc documentation (cargo doc ). |
target/package/ | Contains the output of the cargo package and cargo publish commands. |
Cargo also creates several other directories and files needed for the build process. Their layout is considered internal to Cargo, and is subject to change. Some of these directories are:
Directory | Description |
---|---|
target/debug/deps/ | Dependencies and other artifacts. |
target/debug/incremental/ | rustc incremental output, a cache used to speed up subsequent builds. |
target/debug/build/ | Output from build scripts. |
Dep-info files
Next to each compiled artifact is a file called a “dep info” file with a .d
suffix. This file is a Makefile-like syntax that indicates all of the file
dependencies required to rebuild the artifact. These are intended to be used
with external build systems so that they can detect if Cargo needs to be
re-executed. The paths in the file are absolute by default. See the
build.dep-info-basedir
config option to use relative paths.
# Example dep-info file found in target/debug/foo.d
/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs
Shared cache
A third party tool, sccache, can be used to share built dependencies across different workspaces.
To setup sccache
, install it with cargo install sccache
and set
RUSTC_WRAPPER
environmental variable to sccache
before invoking Cargo. If
you use bash, it makes sense to add export RUSTC_WRAPPER=sccache
to
.bashrc
. Alternatively, you can set build.rustc-wrapper
in the Cargo
configuration. Refer to sccache documentation for more details.