From 85589e1a8c121ef4febfdc5713484ba6516a16d4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sun, 30 Jan 2022 19:25:53 -0800 Subject: [PATCH] Move detailed `--timings` documentation from unstable docs to reference docs --- src/doc/src/SUMMARY.md | 1 + src/doc/src/reference/index.md | 1 + src/doc/src/reference/timings.md | 51 +++++++++++++++++++++++++++++++ src/doc/src/reference/unstable.md | 40 ------------------------ 4 files changed, 53 insertions(+), 40 deletions(-) create mode 100644 src/doc/src/reference/timings.md diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index e5c58442256..198567c3223 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -39,6 +39,7 @@ * [Dependency Resolution](reference/resolver.md) * [SemVer Compatibility](reference/semver.md) * [Future incompat report](reference/future-incompat-report.md) + * [Reporting build timings](reference/timings.md) * [Unstable Features](reference/unstable.md) * [Cargo Commands](commands/index.md) diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md index 298647a57a3..b931306c206 100644 --- a/src/doc/src/reference/index.md +++ b/src/doc/src/reference/index.md @@ -22,4 +22,5 @@ The reference covers the details of various areas of Cargo. * [Dependency Resolution](resolver.md) * [SemVer Compatibility](semver.md) * [Future incompat report](future-incompat-report.md) +* [Reporting build timings](timings.md) * [Unstable Features](unstable.md) diff --git a/src/doc/src/reference/timings.md b/src/doc/src/reference/timings.md new file mode 100644 index 00000000000..310babd04c3 --- /dev/null +++ b/src/doc/src/reference/timings.md @@ -0,0 +1,51 @@ +# Reporting build timings +The `--timings` option gives some information about how long each compilation +takes, and tracks concurrency information over time. + +```sh +cargo build --timings +``` + +This writes an HTML report in `target/cargo-timings/cargo-timings.html`. This +also writes a copy of the report to the same directory with a timestamp in the +filename, if you want to look at older runs. + +#### Reading the graphs + +There are two graphs in the output. The "unit" graph shows the duration of +each unit over time. A "unit" is a single compiler invocation. There are lines +that show which additional units are "unlocked" when a unit finishes. That is, +it shows the new units that are now allowed to run because their dependencies +are all finished. Hover the mouse over a unit to highlight the lines. This can +help visualize the critical path of dependencies. This may change between runs +because the units may finish in different orders. + +The "codegen" times are highlighted in a lavender color. In some cases, build +pipelining allows units to start when their dependencies are performing code +generation. This information is not always displayed (for example, binary +units do not show when code generation starts). + +The "custom build" units are `build.rs` scripts, which when run are +highlighted in orange. + +The second graph shows Cargo's concurrency over time. The background +indicates CPU usage. The three lines are: +- "Waiting" (red) — This is the number of units waiting for a CPU slot to + open. +- "Inactive" (blue) — This is the number of units that are waiting for their + dependencies to finish. +- "Active" (green) — This is the number of units currently running. + +Note: This does not show the concurrency in the compiler itself. `rustc` +coordinates with Cargo via the "job server" to stay within the concurrency +limit. This currently mostly applies to the code generation phase. + +Tips for addressing compile times: +- Look for slow dependencies. + - Check if they have features that you may wish to consider disabling. + - Consider trying to remove the dependency completely. +- Look for a crate being built multiple times with different versions. Try to + remove the older versions from the dependency graph. +- Split large crates into smaller pieces. +- If there are a large number of crates bottlenecked on a single crate, focus + your attention on improving that one crate to improve parallelism. diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index efecbc75633..7ca9d7b9f6b 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -401,46 +401,6 @@ library. The default enabled features, at this time, are `backtrace` and `panic_unwind`. This flag expects a comma-separated list and, if provided, will override the default list of features enabled. -#### Reading the graphs - -There are two graphs in the output. The "unit" graph shows the duration of -each unit over time. A "unit" is a single compiler invocation. There are lines -that show which additional units are "unlocked" when a unit finishes. That is, -it shows the new units that are now allowed to run because their dependencies -are all finished. Hover the mouse over a unit to highlight the lines. This can -help visualize the critical path of dependencies. This may change between runs -because the units may finish in different orders. - -The "codegen" times are highlighted in a lavender color. In some cases, build -pipelining allows units to start when their dependencies are performing code -generation. This information is not always displayed (for example, binary -units do not show when code generation starts). - -The "custom build" units are `build.rs` scripts, which when run are -highlighted in orange. - -The second graph shows Cargo's concurrency over time. The background -indicates CPU usage. The three lines are: -- "Waiting" (red) — This is the number of units waiting for a CPU slot to - open. -- "Inactive" (blue) — This is the number of units that are waiting for their - dependencies to finish. -- "Active" (green) — This is the number of units currently running. - -Note: This does not show the concurrency in the compiler itself. `rustc` -coordinates with Cargo via the "job server" to stay within the concurrency -limit. This currently mostly applies to the code generation phase. - -Tips for addressing compile times: -- Look for slow dependencies. - - Check if they have features that you may wish to consider disabling. - - Consider trying to remove the dependency completely. -- Look for a crate being built multiple times with different versions. Try to - remove the older versions from the dependency graph. -- Split large crates into smaller pieces. -- If there are a large number of crates bottlenecked on a single crate, focus - your attention on improving that one crate to improve parallelism. - ### binary-dep-depinfo * Tracking rustc issue: [#63012](https://github.com/rust-lang/rust/issues/63012)