]>
Commit | Line | Data |
---|---|---|
05043ab7 PM |
1 | ## Build cache |
2 | ||
64f605bf EH |
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. | |
05043ab7 | 7 | |
64f605bf EH |
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: | |
05043ab7 | 12 | |
64f605bf EH |
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/<triple>/debug/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/debug/</code> | |
24 | <code style="white-space: nowrap">target/<triple>/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 | ||
765c80da EH |
52 | ### Dep-info files |
53 | ||
54 | Next to each compiled artifact is a file called a "dep info" file with a `.d` | |
55 | suffix. This file is a Makefile-like syntax that indicates all of the file | |
56 | dependencies required to rebuild the artifact. These are intended to be used | |
57 | with external build systems so that they can detect if Cargo needs to be | |
58 | re-executed. The paths in the file are absolute by default. See the | |
59 | [`build.dep-info-basedir`] config option to use relative paths. | |
60 | ||
61 | ```Makefile | |
62 | # Example dep-info file found in target/debug/foo.d | |
63 | /path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs | |
64 | ``` | |
65 | ||
64f605bf EH |
66 | ### Shared cache |
67 | ||
68 | A third party tool, [sccache], can be used to share built dependencies across | |
69 | different workspaces. | |
70 | ||
71 | To setup `sccache`, install it with `cargo install sccache` and set | |
72 | `RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If | |
73 | you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to | |
74 | `.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo | |
75 | configuration][config]. Refer to sccache documentation for more details. | |
76 | ||
765c80da | 77 | [`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir |
64f605bf EH |
78 | [`build.target-dir`]: ../reference/config.md#buildtarget-dir |
79 | [`cargo doc`]: ../commands/cargo-doc.md | |
80 | [`cargo package`]: ../commands/cargo-package.md | |
81 | [`cargo publish`]: ../commands/cargo-publish.md | |
82 | [build scripts]: ../reference/build-scripts.md | |
674241b2 | 83 | [config]: ../reference/config.md |
64f605bf EH |
84 | [environment variable]: ../reference/environment-variables.md |
85 | [incremental output]: ../reference/profiles.md#incremental | |
86 | [sccache]: https://github.com/mozilla/sccache |