mirror of
https://github.com/rust-lang/cargo
synced 2024-10-02 14:04:23 +00:00
Move detailed --timings
documentation from unstable docs to reference docs
This commit is contained in:
parent
086e71da00
commit
85589e1a8c
|
@ -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)
|
||||
|
|
|
@ -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)
|
||||
|
|
51
src/doc/src/reference/timings.md
Normal file
51
src/doc/src/reference/timings.md
Normal file
|
@ -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.
|
|
@ -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)
|
||||
|
||||
|
|
Loading…
Reference in a new issue