|
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 |
5 | | -[*workspace*][def-workspace]. To change the location, you can set the |
6 | | -`CARGO_TARGET_DIR` [environment variable], the [`build.target-dir`] config |
7 | | -value, or the `--target-dir` command-line flag. |
8 | | - |
9 | | -The directory layout depends on whether or not you are using the `--target` |
10 | | -flag to build for a specific platform. If `--target` is not specified, Cargo |
11 | | -runs in a mode where it builds for the host architecture. The output goes into |
12 | | -the root of the target directory, with each [profile] stored in a separate |
13 | | -subdirectory: |
14 | | - |
15 | | -Directory | Description |
16 | | -----------|------------ |
17 | | -<code style="white-space: nowrap">target/debug/</code> | Contains output for the `dev` profile. |
18 | | -<code style="white-space: nowrap">target/release/</code> | Contains output for the `release` profile (with the `--release` option). |
19 | | -<code style="white-space: nowrap">target/foo/</code> | Contains build output for the `foo` profile (with the `--profile=foo` option). |
20 | | - |
21 | | -For historical reasons, the `dev` and `test` profiles are stored in the |
22 | | -`debug` directory, and the `release` and `bench` profiles are stored in the |
23 | | -`release` directory. User-defined profiles are stored in a directory with the |
24 | | -same name as the profile. |
25 | | - |
26 | | -When building for another target with `--target`, the output is placed in a |
27 | | -directory with the name of the [target]: |
28 | | - |
29 | | -Directory | Example |
30 | | -----------|-------- |
31 | | -<code style="white-space: nowrap">target/<triple>/debug/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/debug/</code> |
32 | | -<code style="white-space: nowrap">target/<triple>/release/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/release/</code> |
33 | | - |
34 | | -> **Note**: When not using `--target`, this has a consequence that Cargo will |
35 | | -> share your dependencies with build scripts and proc macros. [`RUSTFLAGS`] |
36 | | -> will be shared with every `rustc` invocation. With the `--target` flag, |
37 | | -> build scripts and proc macros are built separately (for the host |
38 | | -> architecture), and do not share `RUSTFLAGS`. |
39 | | -
|
40 | | -Within the profile directory (such as `debug` or `release`), artifacts are |
41 | | -placed into the following directories: |
42 | | - |
43 | | -Directory | Description |
44 | | -----------|------------ |
45 | | -<code style="white-space: nowrap">target/debug/</code> | Contains the output of the package being built (the [binary executables] and [library targets]). |
46 | | -<code style="white-space: nowrap">target/debug/examples/</code> | Contains [example targets]. |
47 | | - |
48 | | -Some commands place their output in dedicated directories in the top level of |
49 | | -the `target` directory: |
50 | | - |
51 | | -Directory | Description |
52 | | -----------|------------ |
53 | | -<code style="white-space: nowrap">target/doc/</code> | Contains rustdoc documentation ([`cargo doc`]). |
54 | | -<code style="white-space: nowrap">target/package/</code> | Contains the output of the [`cargo package`] and [`cargo publish`] commands. |
55 | | - |
56 | | -Cargo also creates several other directories and files needed for the build |
57 | | -process. Their layout is considered internal to Cargo, and is subject to |
58 | | -change. Some of these directories are: |
59 | | - |
60 | | -Directory | Description |
61 | | -----------|------------ |
62 | | -<code style="white-space: nowrap">target/debug/deps/</code> | Dependencies and other artifacts. |
63 | | -<code style="white-space: nowrap">target/debug/incremental/</code> | `rustc` [incremental output], a cache used to speed up subsequent builds. |
64 | | -<code style="white-space: nowrap">target/debug/build/</code> | Output from [build scripts]. |
65 | | - |
66 | | -## Dep-info files |
67 | | - |
68 | | -Next to each compiled artifact is a file called a "dep info" file with a `.d` |
69 | | -suffix. This file is a Makefile-like syntax that indicates all of the file |
70 | | -dependencies required to rebuild the artifact. These are intended to be used |
71 | | -with external build systems so that they can detect if Cargo needs to be |
72 | | -re-executed. The paths in the file are absolute by default. See the |
73 | | -[`build.dep-info-basedir`] config option to use relative paths. |
74 | | - |
75 | | -```Makefile |
76 | | -# Example dep-info file found in target/debug/foo.d |
77 | | -/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs |
78 | | -``` |
79 | | - |
80 | | -## Shared cache |
81 | | - |
82 | | -A third party tool, [sccache], can be used to share built dependencies across |
83 | | -different workspaces. |
84 | | - |
85 | | -To setup `sccache`, install it with `cargo install sccache` and set |
86 | | -`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If |
87 | | -you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to |
88 | | -`.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo |
89 | | -configuration][config]. Refer to sccache documentation for more details. |
90 | | - |
91 | | -[`RUSTFLAGS`]: ../reference/config.md#buildrustflags |
92 | | -[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir |
93 | | -[`build.rustc-wrapper`]: ../reference/config.md#buildrustc-wrapper |
94 | | -[`build.target-dir`]: ../reference/config.md#buildtarget-dir |
95 | | -[`cargo doc`]: ../commands/cargo-doc.md |
96 | | -[`cargo package`]: ../commands/cargo-package.md |
97 | | -[`cargo publish`]: ../commands/cargo-publish.md |
98 | | -[build scripts]: ../reference/build-scripts.md |
99 | | -[config]: ../reference/config.md |
100 | | -[def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)' |
101 | | -[target]: ../appendix/glossary.md#target '"target" (glossary entry)' |
102 | | -[environment variable]: ../reference/environment-variables.md |
103 | | -[incremental output]: ../reference/profiles.md#incremental |
104 | | -[sccache]: https://github.com/mozilla/sccache |
105 | | -[profile]: ../reference/profiles.md |
106 | | -[binary executables]: ../reference/cargo-targets.md#binaries |
107 | | -[library targets]: ../reference/cargo-targets.md#library |
108 | | -[example targets]: ../reference/cargo-targets.md#examples |
| 1 | +# Build Cache |
0 commit comments