src/doc/src/guide/build-cache.md

   1 ## Build cache
   2
   3 Cargo stores the output of a build into the "target" directory. By default,
   4 this is the directory named `target` in the root of your workspace. To change
   5 the location, you can set the `CARGO_TARGET_DIR` [environment variable], the
   6 [`build.target-dir`] config value, or the `--target-dir` command-line flag.
   7
   8 The directory layout depends on whether or not you are cross-compiling for a
   9 different platform with the `--target` flag. When not cross-compiling, the
  10 output goes into the root of the target directory, separated based on whether
  11 or not it is a release build:
  12
  13 Directory | Description
  14 ----------|------------
  15 <code style="white-space: nowrap">target/debug/</code> | Contains debug build output.
  16 <code style="white-space: nowrap">target/release/</code> | Contains release build output (with `--release` flag).
  17
  18 When building for another target, the output is placed in a directory with the
  19 name of the target:
  20
  21 Directory | Example
  22 ----------|--------
  23 <code style="white-space: nowrap">target/&lt;triple&gt;/debug/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/debug/</code>
  24 <code style="white-space: nowrap">target/&lt;triple&gt;/release/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/release/</code>
  25
  26 Within the profile directory (`debug` or `release`), artifacts are placed into
  27 the following directories:
  28
  29 Directory | Description
  30 ----------|------------
  31 <code style="white-space: nowrap">target/debug/</code> | Contains the output of the package being built (the `[[bin]]` executables and `[lib]` library targets).
  32 <code style="white-space: nowrap">target/debug/examples/</code> | Contains examples (`[[example]]` targets).
  33
  34 Some commands place their output in dedicated directories in the top level of
  35 the `target` directory:
  36
  37 Directory | Description
  38 ----------|------------
  39 <code style="white-space: nowrap">target/doc/</code> | Contains rustdoc documentation ([`cargo doc`]).
  40 <code style="white-space: nowrap">target/package/</code> | Contains the output of the [`cargo package`] and [`cargo publish`] commands.
  41
  42 Cargo also creates several other directories and files needed for the build
  43 process. Their layout is considered internal to Cargo, and is subject to
  44 change. Some of these directories are:
  45
  46 Directory | Description
  47 ----------|------------
  48 <code style="white-space: nowrap">target/debug/deps/</code> |  Dependencies and other artifacts.
  49 <code style="white-space: nowrap">target/debug/incremental/</code> |  `rustc` [incremental output], a cache used to speed up subsequent builds.
  50 <code style="white-space: nowrap">target/debug/build/</code> |  Output from [build scripts].
  51
  52 ### Shared cache
  53
  54 A third party tool, [sccache], can be used to share built dependencies across
  55 different workspaces.
  56
  57 To setup `sccache`, install it with `cargo install sccache` and set
  58 `RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If
  59 you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to
  60 `.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo
  61 configuration][config]. Refer to sccache documentation for more details.
  62
  63 [`build.target-dir`]: ../reference/config.md#buildtarget-dir
  64 [`cargo doc`]: ../commands/cargo-doc.md
  65 [`cargo package`]: ../commands/cargo-package.md
  66 [`cargo publish`]: ../commands/cargo-publish.md
  67 [build scripts]: ../reference/build-scripts.md
  68 [config]: ../reference/config.md
  69 [environment variable]: ../reference/environment-variables.md
  70 [incremental output]: ../reference/profiles.md#incremental
  71 [sccache]: https://github.com/mozilla/sccache