From a3eaa4b92b24e048987f8344b461aa0f2675335a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 30 Sep 2024 16:04:37 -0500 Subject: [PATCH 1/3] docs: Move publishing from ref to guide --- src/doc/src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index e726318844a..35a40525c0e 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -15,6 +15,7 @@ * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.md) * [Tests](guide/tests.md) * [Continuous Integration](guide/continuous-integration.md) + * [Publishing on crates.io](reference/publishing.md) * [Cargo Home](guide/cargo-home.md) * [Build Cache](guide/build-cache.md) @@ -31,7 +32,6 @@ * [Environment Variables](reference/environment-variables.md) * [Build Scripts](reference/build-scripts.md) * [Build Script Examples](reference/build-script-examples.md) - * [Publishing on crates.io](reference/publishing.md) * [Package ID Specifications](reference/pkgid-spec.md) * [Source Replacement](reference/source-replacement.md) * [External Tools](reference/external-tools.md) From 1dde0715488860070a46e11d03bc9f8be4b04b4b Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 30 Sep 2024 16:08:40 -0500 Subject: [PATCH 2/3] docs: Move Cache topic from Guide to Reference It doesn't "guide" people through a topic but explains in a more top-down fashion what caches exist and is not particularly a common topic people need to know. --- src/doc/book.toml | 3 + src/doc/man/generated_txt/cargo-bench.txt | 2 +- src/doc/man/generated_txt/cargo-build.txt | 2 +- src/doc/man/generated_txt/cargo-check.txt | 2 +- src/doc/man/generated_txt/cargo-clean.txt | 2 +- src/doc/man/generated_txt/cargo-doc.txt | 2 +- src/doc/man/generated_txt/cargo-fetch.txt | 2 +- src/doc/man/generated_txt/cargo-fix.txt | 2 +- src/doc/man/generated_txt/cargo-install.txt | 2 +- src/doc/man/generated_txt/cargo-package.txt | 2 +- src/doc/man/generated_txt/cargo-publish.txt | 2 +- src/doc/man/generated_txt/cargo-run.txt | 2 +- src/doc/man/generated_txt/cargo-rustc.txt | 2 +- src/doc/man/generated_txt/cargo-rustdoc.txt | 2 +- src/doc/man/generated_txt/cargo-test.txt | 2 +- src/doc/man/includes/options-target-triple.md | 2 +- src/doc/src/SUMMARY.md | 2 +- src/doc/src/commands/cargo-bench.md | 2 +- src/doc/src/commands/cargo-build.md | 2 +- src/doc/src/commands/cargo-check.md | 2 +- src/doc/src/commands/cargo-clean.md | 2 +- src/doc/src/commands/cargo-doc.md | 2 +- src/doc/src/commands/cargo-fetch.md | 2 +- src/doc/src/commands/cargo-fix.md | 2 +- src/doc/src/commands/cargo-install.md | 2 +- src/doc/src/commands/cargo-package.md | 2 +- src/doc/src/commands/cargo-publish.md | 2 +- src/doc/src/commands/cargo-run.md | 2 +- src/doc/src/commands/cargo-rustc.md | 2 +- src/doc/src/commands/cargo-rustdoc.md | 2 +- src/doc/src/commands/cargo-test.md | 2 +- src/doc/src/guide/build-cache.md | 109 +----------------- src/doc/src/reference/build-cache.md | 108 +++++++++++++++++ src/doc/src/reference/cargo-targets.md | 2 +- src/doc/src/reference/config.md | 2 +- src/doc/src/reference/profiles.md | 2 +- src/doc/src/reference/workspaces.md | 2 +- src/etc/man/cargo-bench.1 | 2 +- src/etc/man/cargo-build.1 | 2 +- src/etc/man/cargo-check.1 | 2 +- src/etc/man/cargo-clean.1 | 2 +- src/etc/man/cargo-doc.1 | 2 +- src/etc/man/cargo-fetch.1 | 2 +- src/etc/man/cargo-fix.1 | 2 +- src/etc/man/cargo-install.1 | 2 +- src/etc/man/cargo-package.1 | 2 +- src/etc/man/cargo-publish.1 | 2 +- src/etc/man/cargo-run.1 | 2 +- src/etc/man/cargo-rustc.1 | 2 +- src/etc/man/cargo-rustdoc.1 | 2 +- src/etc/man/cargo-test.1 | 2 +- 51 files changed, 160 insertions(+), 156 deletions(-) create mode 100644 src/doc/src/reference/build-cache.md diff --git a/src/doc/book.toml b/src/doc/book.toml index 1315212eee7..ecc9a4b81b0 100644 --- a/src/doc/book.toml +++ b/src/doc/book.toml @@ -7,3 +7,6 @@ smart-punctuation = true # Enable smart-punctuation feature for more than quotes git-repository-url = "https://github.com/rust-lang/cargo/tree/master/src/doc/src" edit-url-template = "https://github.com/rust-lang/cargo/edit/master/src/doc/{path}" search.use-boolean-and = true + +[output.html.redirect] +"/guide/build-cache.html" = "../reference/build-cache.html" diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index 3987981d0e5..c05d527ad31 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -232,7 +232,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. --profile name diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index 25044640f89..201f70bd0df 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -149,7 +149,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt index 23d0c9f99c5..9cd11da02d1 100644 --- a/src/doc/man/generated_txt/cargo-check.txt +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -146,7 +146,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/generated_txt/cargo-clean.txt b/src/doc/man/generated_txt/cargo-clean.txt index 9e9c70dcd6f..2325c090c14 100644 --- a/src/doc/man/generated_txt/cargo-clean.txt +++ b/src/doc/man/generated_txt/cargo-clean.txt @@ -57,7 +57,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. Display Options diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt index 434fd5cd83d..071663129c5 100644 --- a/src/doc/man/generated_txt/cargo-doc.txt +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -124,7 +124,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/generated_txt/cargo-fetch.txt b/src/doc/man/generated_txt/cargo-fetch.txt index 09272cb9dcc..939821dcbeb 100644 --- a/src/doc/man/generated_txt/cargo-fetch.txt +++ b/src/doc/man/generated_txt/cargo-fetch.txt @@ -37,7 +37,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. Display Options diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt index e33d4bbd7fe..53aa3a3a698 100644 --- a/src/doc/man/generated_txt/cargo-fix.txt +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -219,7 +219,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt index a9deef68143..7575948a38a 100644 --- a/src/doc/man/generated_txt/cargo-install.txt +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -197,7 +197,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. --target-dir directory diff --git a/src/doc/man/generated_txt/cargo-package.txt b/src/doc/man/generated_txt/cargo-package.txt index faa0a6dc22e..f25e55b52bb 100644 --- a/src/doc/man/generated_txt/cargo-package.txt +++ b/src/doc/man/generated_txt/cargo-package.txt @@ -144,7 +144,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. --target-dir directory diff --git a/src/doc/man/generated_txt/cargo-publish.txt b/src/doc/man/generated_txt/cargo-publish.txt index 08c0c123615..6920f8dabb2 100644 --- a/src/doc/man/generated_txt/cargo-publish.txt +++ b/src/doc/man/generated_txt/cargo-publish.txt @@ -92,7 +92,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. --target-dir directory diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt index 5716b934692..dd9e8123c0d 100644 --- a/src/doc/man/generated_txt/cargo-run.txt +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -72,7 +72,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt index 031b5be83dd..3d993494059 100644 --- a/src/doc/man/generated_txt/cargo-rustc.txt +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -140,7 +140,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt index 3d0397faec6..968195e7486 100644 --- a/src/doc/man/generated_txt/cargo-rustdoc.txt +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -140,7 +140,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index 272340842fc..20d2de576f3 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -254,7 +254,7 @@ OPTIONS Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the build cache - + documentation for more details. -r, --release diff --git a/src/doc/man/includes/options-target-triple.md b/src/doc/man/includes/options-target-triple.md index bb180f53d7a..60c52a15868 100644 --- a/src/doc/man/includes/options-target-triple.md +++ b/src/doc/man/includes/options-target-triple.md @@ -12,5 +12,5 @@ This may also be specified with the `build.target` Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -[build cache](../guide/build-cache.html) documentation for more details. +[build cache](../reference/build-cache.html) documentation for more details. {{/option}} diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index 35a40525c0e..5e058bd0a9e 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -17,7 +17,6 @@ * [Continuous Integration](guide/continuous-integration.md) * [Publishing on crates.io](reference/publishing.md) * [Cargo Home](guide/cargo-home.md) - * [Build Cache](guide/build-cache.md) * [Cargo Reference](reference/index.md) * [Specifying Dependencies](reference/specifying-dependencies.md) @@ -32,6 +31,7 @@ * [Environment Variables](reference/environment-variables.md) * [Build Scripts](reference/build-scripts.md) * [Build Script Examples](reference/build-script-examples.md) + * [Build Cache](reference/build-cache.md) * [Package ID Specifications](reference/pkgid-spec.md) * [Source Replacement](reference/source-replacement.md) * [External Tools](reference/external-tools.md) diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index 85488b6c0d6..f0a7ef0356c 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -263,7 +263,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

--profile name
diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 00efadc7c86..bb9acce1ad7 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -178,7 +178,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index 664fa19f13d..0dcbe6f142e 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -174,7 +174,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/commands/cargo-clean.md b/src/doc/src/commands/cargo-clean.md index e4df7f8d38e..e18a35a5d9a 100644 --- a/src/doc/src/commands/cargo-clean.md +++ b/src/doc/src/commands/cargo-clean.md @@ -66,7 +66,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details. diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index dc1a41a7b41..3b97a336692 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -153,7 +153,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/commands/cargo-fetch.md b/src/doc/src/commands/cargo-fetch.md index 20dfcdb8e54..8cdf5cc1311 100644 --- a/src/doc/src/commands/cargo-fetch.md +++ b/src/doc/src/commands/cargo-fetch.md @@ -36,7 +36,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details. diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index c84d33abd13..b7e64dda70d 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -254,7 +254,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 64693b50c7d..daa90fb25e6 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -219,7 +219,7 @@ list of supported targets.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

--target-dir directory
diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md index 57eb7a47313..38fc7f80b4e 100644 --- a/src/doc/src/commands/cargo-package.md +++ b/src/doc/src/commands/cargo-package.md @@ -155,7 +155,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

--target-dir directory
diff --git a/src/doc/src/commands/cargo-publish.md b/src/doc/src/commands/cargo-publish.md index 12df38da133..d34ac72a622 100644 --- a/src/doc/src/commands/cargo-publish.md +++ b/src/doc/src/commands/cargo-publish.md @@ -102,7 +102,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

--target-dir directory
diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 237d23e6bc0..29d4264f4ef 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -95,7 +95,7 @@ list of supported targets.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index 7d4943e85ed..a2c5d622880 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -167,7 +167,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index 5ff822877a0..8ebe96ecae0 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -173,7 +173,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 205985f4d08..a2c93c9c4a1 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -285,7 +285,7 @@ list of supported targets. This flag may be specified multiple times.

config value.

Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -build cache documentation for more details. +build cache documentation for more details.

-r
diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md index d351fc15893..a24e5af7f3f 100644 --- a/src/doc/src/guide/build-cache.md +++ b/src/doc/src/guide/build-cache.md @@ -1,108 +1 @@ -# 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*][def-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 every `rustc` invocation. With the `--target` flag, -> build scripts and proc macros are built separately (for the host -> architecture), and do not share `RUSTFLAGS`. - -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. - -```Makefile -# 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][config]. Refer to sccache documentation for more details. - -[`RUSTFLAGS`]: ../reference/config.md#buildrustflags -[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir -[`build.rustc-wrapper`]: ../reference/config.md#buildrustc-wrapper -[`build.target-dir`]: ../reference/config.md#buildtarget-dir -[`cargo doc`]: ../commands/cargo-doc.md -[`cargo package`]: ../commands/cargo-package.md -[`cargo publish`]: ../commands/cargo-publish.md -[build scripts]: ../reference/build-scripts.md -[config]: ../reference/config.md -[def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)' -[target]: ../appendix/glossary.md#target '"target" (glossary entry)' -[environment variable]: ../reference/environment-variables.md -[incremental output]: ../reference/profiles.md#incremental -[sccache]: https://github.com/mozilla/sccache -[profile]: ../reference/profiles.md -[binary executables]: ../reference/cargo-targets.md#binaries -[library targets]: ../reference/cargo-targets.md#library -[example targets]: ../reference/cargo-targets.md#examples +# Build Cache diff --git a/src/doc/src/reference/build-cache.md b/src/doc/src/reference/build-cache.md new file mode 100644 index 00000000000..d351fc15893 --- /dev/null +++ b/src/doc/src/reference/build-cache.md @@ -0,0 +1,108 @@ +# 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*][def-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 every `rustc` invocation. With the `--target` flag, +> build scripts and proc macros are built separately (for the host +> architecture), and do not share `RUSTFLAGS`. + +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. + +```Makefile +# 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][config]. Refer to sccache documentation for more details. + +[`RUSTFLAGS`]: ../reference/config.md#buildrustflags +[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir +[`build.rustc-wrapper`]: ../reference/config.md#buildrustc-wrapper +[`build.target-dir`]: ../reference/config.md#buildtarget-dir +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo package`]: ../commands/cargo-package.md +[`cargo publish`]: ../commands/cargo-publish.md +[build scripts]: ../reference/build-scripts.md +[config]: ../reference/config.md +[def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)' +[target]: ../appendix/glossary.md#target '"target" (glossary entry)' +[environment variable]: ../reference/environment-variables.md +[incremental output]: ../reference/profiles.md#incremental +[sccache]: https://github.com/mozilla/sccache +[profile]: ../reference/profiles.md +[binary executables]: ../reference/cargo-targets.md#binaries +[library targets]: ../reference/cargo-targets.md#library +[example targets]: ../reference/cargo-targets.md#examples diff --git a/src/doc/src/reference/cargo-targets.md b/src/doc/src/reference/cargo-targets.md index 410df80a207..8a4ed59e54b 100644 --- a/src/doc/src/reference/cargo-targets.md +++ b/src/doc/src/reference/cargo-targets.md @@ -368,7 +368,7 @@ autobins = false > **MSRV:** Respected as of 1.83 for `autolib` -[Build cache]: ../guide/build-cache.md +[Build cache]: build-cache.md [Rust Edition]: ../../edition-guide/index.html [`--test` flag]: ../../rustc/command-line-arguments.html#option-test [`cargo bench`]: ../commands/cargo-bench.md diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 9360c3a5344..be8bbd24e66 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -554,7 +554,7 @@ overrides the config setting. * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR` Strips the given path prefix from [dep -info](../guide/build-cache.md#dep-info-files) file paths. This config setting +info](../reference/build-cache.md#dep-info-files) file paths. This config setting is intended to convert absolute paths to relative paths for tools that require relative paths. diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md index 8fd58ca22fa..448543a5cee 100644 --- a/src/doc/src/reference/profiles.md +++ b/src/doc/src/reference/profiles.md @@ -371,7 +371,7 @@ The output for each profile will be placed in a directory of the same name as the profile in the [`target` directory]. As in the example above, the output would go into the `target/release-lto` directory. -[`target` directory]: ../guide/build-cache.md +[`target` directory]: build-cache.md ## Profile selection diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 22bb9cbe7d7..4cbf212952d 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -290,7 +290,7 @@ if that makes sense for the tool in question. [`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md [package-metadata]: manifest.md#the-metadata-table [package-edition]: manifest.md#the-edition-field -[output directory]: ../guide/build-cache.md +[output directory]: build-cache.md [patch]: overriding-dependencies.md#the-patch-section [replace]: overriding-dependencies.md#the-replace-section [profiles]: profiles.md diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index c74751013d3..0f726a6116f 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -276,7 +276,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-\-profile\fR \fIname\fR diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index d210f44698a..ac59549c302 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -175,7 +175,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index 30bc3909870..8597b23199e 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -171,7 +171,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, diff --git a/src/etc/man/cargo-clean.1 b/src/etc/man/cargo-clean.1 index 113af4a9874..b5a28c66cd3 100644 --- a/src/etc/man/cargo-clean.1 +++ b/src/etc/man/cargo-clean.1 @@ -66,7 +66,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 0834b250a61..72edd83caa6 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -144,7 +144,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, diff --git a/src/etc/man/cargo-fetch.1 b/src/etc/man/cargo-fetch.1 index 4caa4e36d02..1813d584b85 100644 --- a/src/etc/man/cargo-fetch.1 +++ b/src/etc/man/cargo-fetch.1 @@ -34,7 +34,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index 4bb1ef4e103..12267f6343b 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -266,7 +266,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 8bf4ded8bc1..af706d6dd56 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -251,7 +251,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-\-target\-dir\fR \fIdirectory\fR diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index fc0e70aade5..691ebc7b633 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -179,7 +179,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-\-target\-dir\fR \fIdirectory\fR diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index 3a865dce065..c73dc28e8d5 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -111,7 +111,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-\-target\-dir\fR \fIdirectory\fR diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 68ddbe8b01b..59feafa6e73 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -81,7 +81,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index e301d13e4e6..a13526f44b7 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -161,7 +161,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 0908e8ecbeb..3bb81033acc 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -163,7 +163,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 61fd967c956..c450d8537de 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -296,7 +296,7 @@ This may also be specified with the \fBbuild.target\fR .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -\fIbuild cache\fR documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp \fB\-r\fR, From 3a0236fb9051f38ac2d4c179962f421e3acb3e46 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 30 Sep 2024 16:12:07 -0500 Subject: [PATCH 3/3] docs: Group dep related references --- src/doc/src/SUMMARY.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index 5e058bd0a9e..36a32d0fb64 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -19,11 +19,13 @@ * [Cargo Home](guide/cargo-home.md) * [Cargo Reference](reference/index.md) - * [Specifying Dependencies](reference/specifying-dependencies.md) - * [Overriding Dependencies](reference/overriding-dependencies.md) * [The Manifest Format](reference/manifest.md) * [Cargo Targets](reference/cargo-targets.md) * [Workspaces](reference/workspaces.md) + * [Specifying Dependencies](reference/specifying-dependencies.md) + * [Overriding Dependencies](reference/overriding-dependencies.md) + * [Source Replacement](reference/source-replacement.md) + * [Dependency Resolution](reference/resolver.md) * [Features](reference/features.md) * [Features Examples](reference/features-examples.md) * [Profiles](reference/profiles.md) @@ -33,7 +35,6 @@ * [Build Script Examples](reference/build-script-examples.md) * [Build Cache](reference/build-cache.md) * [Package ID Specifications](reference/pkgid-spec.md) - * [Source Replacement](reference/source-replacement.md) * [External Tools](reference/external-tools.md) * [Registries](reference/registries.md) * [Registry Authentication](reference/registry-authentication.md) @@ -41,7 +42,6 @@ * [Running a Registry](reference/running-a-registry.md) * [Registry Index](reference/registry-index.md) * [Registry Web API](reference/registry-web-api.md) - * [Dependency Resolution](reference/resolver.md) * [SemVer Compatibility](reference/semver.md) * [Future incompat report](reference/future-incompat-report.md) * [Reporting build timings](reference/timings.md)