Stabilize -Ztimings as --timings

The `-Ztimings` option has existed for years, and many people use it to
profile and optimize their builds. It's one of the common reasons people
use nightly cargo.

The machine-readable JSON output may warrant further careful inspection
before we commit to a stable format. However, for the human-readable
output we don't need to make any commitment about the exact output.

Add a `--timings` option, as the stable equivalent to `-Ztimings`.
Stabilize the `html` output format, and require `-Zunstable-options` for
the `json` output format.

Document the new option, and update the testsuite.
This commit is contained in:
Josh Triplett 2022-01-01 18:47:04 -08:00
parent 86bb4a0c2b
commit c06691897a
59 changed files with 651 additions and 56 deletions

View File

@ -47,6 +47,7 @@ pub fn cli() -> App {
"Run all benchmarks regardless of failure",
))
.arg_unit_graph()
.arg_timings()
.after_help("Run `cargo help bench` for more detailed information.\n")
}

View File

@ -44,6 +44,7 @@ pub fn cli() -> App {
.arg_build_plan()
.arg_unit_graph()
.arg_future_incompat_report()
.arg_timings()
.after_help("Run `cargo help build` for more detailed information.\n")
}

View File

@ -36,6 +36,7 @@ pub fn cli() -> App {
.arg_message_format()
.arg_unit_graph()
.arg_future_incompat_report()
.arg_timings()
.after_help("Run `cargo help check` for more detailed information.\n")
}

View File

@ -36,6 +36,7 @@ pub fn cli() -> App {
.arg_message_format()
.arg_ignore_rust_version()
.arg_unit_graph()
.arg_timings()
.after_help("Run `cargo help doc` for more detailed information.\n")
}

View File

@ -62,6 +62,7 @@ pub fn cli() -> App {
.help("Fix code even if the working directory has staged changes"),
)
.arg_ignore_rust_version()
.arg_timings()
.after_help("Run `cargo help fix` for more detailed information.\n")
}

View File

@ -78,6 +78,7 @@ pub fn cli() -> App {
.conflicts_with_all(&["git", "path", "index"]),
)
.arg_message_format()
.arg_timings()
.after_help("Run `cargo help install` for more detailed information.\n")
}

View File

@ -31,6 +31,7 @@ pub fn cli() -> App {
.arg_message_format()
.arg_unit_graph()
.arg_ignore_rust_version()
.arg_timings()
.after_help("Run `cargo help run` for more detailed information.\n")
}

View File

@ -47,6 +47,7 @@ pub fn cli() -> App {
.arg_unit_graph()
.arg_ignore_rust_version()
.arg_future_incompat_report()
.arg_timings()
.after_help("Run `cargo help rustc` for more detailed information.\n")
}

View File

@ -35,6 +35,7 @@ pub fn cli() -> App {
.arg_message_format()
.arg_unit_graph()
.arg_ignore_rust_version()
.arg_timings()
.after_help("Run `cargo help rustdoc` for more detailed information.\n")
}

View File

@ -56,6 +56,7 @@ pub fn cli() -> App {
.arg_message_format()
.arg_unit_graph()
.arg_future_incompat_report()
.arg_timings()
.after_help(
"Run `cargo help test` for more detailed information.\n\
Run `cargo test -- --help` for test binary options.\n",

View File

@ -39,6 +39,8 @@ pub struct BuildConfig {
pub export_dir: Option<PathBuf>,
/// `true` to output a future incompatibility report at the end of the build
pub future_incompat_report: bool,
/// Which kinds of build timings to output (empty if none).
pub timing_outputs: Vec<TimingOutput>,
}
impl BuildConfig {
@ -86,6 +88,7 @@ impl BuildConfig {
rustfix_diagnostic_server: RefCell::new(None),
export_dir: None,
future_incompat_report: false,
timing_outputs: Vec::new(),
})
}
@ -231,3 +234,12 @@ impl CompileMode {
)
}
}
/// Kinds of build timings we can output.
#[derive(Clone, Copy, PartialEq, Debug, Eq, Hash, PartialOrd, Ord)]
pub enum TimingOutput {
/// Human-readable HTML report
Html,
/// Machine-readable JSON (unstable)
Json,
}

View File

@ -906,7 +906,7 @@ impl<'cfg> DrainState<'cfg> {
// this as often as we spin on the events receiver (at least every 500ms or
// so).
fn tick_progress(&mut self) {
// Record some timing information if `-Ztimings` is enabled, and
// Record some timing information if `--timings` is enabled, and
// this'll end up being a noop if we're not recording this
// information.
self.timings.mark_concurrency(

View File

@ -33,7 +33,7 @@ use anyhow::{Context as _, Error};
use lazycell::LazyCell;
use log::{debug, trace};
pub use self::build_config::{BuildConfig, CompileMode, MessageFormat};
pub use self::build_config::{BuildConfig, CompileMode, MessageFormat, TimingOutput};
pub use self::build_context::{
BuildContext, FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
};

View File

@ -4,7 +4,7 @@
//! long it takes for different units to compile.
use super::{CompileMode, Unit};
use crate::core::compiler::job_queue::JobId;
use crate::core::compiler::BuildContext;
use crate::core::compiler::{BuildContext, TimingOutput};
use crate::core::PackageId;
use crate::util::cpu::State;
use crate::util::machine_message::{self, Message};
@ -92,15 +92,9 @@ struct Concurrency {
impl<'cfg> Timings<'cfg> {
pub fn new(bcx: &BuildContext<'_, 'cfg>, root_units: &[Unit]) -> Timings<'cfg> {
let has_report = |what| {
bcx.config
.cli_unstable()
.timings
.as_ref()
.map_or(false, |t| t.iter().any(|opt| opt == what))
};
let report_html = has_report("html");
let report_json = has_report("json");
let has_report = |what| bcx.build_config.timing_outputs.contains(&what);
let report_html = has_report(TimingOutput::Html);
let report_json = has_report(TimingOutput::Json);
let enabled = report_html | report_json;
let mut root_map: HashMap<PackageId, Vec<String>> = HashMap::new();

View File

@ -652,7 +652,6 @@ unstable_cli_options!(
rustdoc_map: bool = ("Allow passing external documentation mappings to rustdoc"),
separate_nightlies: bool = (HIDDEN),
terminal_width: Option<Option<usize>> = ("Provide a terminal width to rustc for error truncation"),
timings: Option<Vec<String>> = ("Display concurrency information"),
unstable_options: bool = ("Allow the usage of unstable options"),
// TODO(wcrichto): move scrape example configuration into Cargo.toml before stabilization
// See: https://github.com/rust-lang/cargo/pull/9525#discussion_r728470927
@ -712,6 +711,8 @@ const STABILIZED_WEAK_DEP_FEATURES: &str = "Weak dependency features are now alw
const STABILISED_NAMESPACED_FEATURES: &str = "Namespaced features are now always available.";
const STABILIZED_TIMINGS: &str = "The -Ztimings option has been stabilized as --timings.";
fn deserialize_build_std<'de, D>(deserializer: D) -> Result<Option<Vec<String>>, D::Error>
where
D: serde::Deserializer<'de>,
@ -768,13 +769,6 @@ impl CliUnstable {
}
}
fn parse_timings(value: Option<&str>) -> Vec<String> {
match value {
None => vec!["html".to_string()],
Some(v) => v.split(',').map(|s| s.to_string()).collect(),
}
}
fn parse_features(value: Option<&str>) -> Vec<String> {
match value {
None => Vec::new(),
@ -849,7 +843,6 @@ impl CliUnstable {
self.build_std = Some(crate::core::compiler::standard_lib::parse_unstable_flag(v))
}
"build-std-features" => self.build_std_features = Some(parse_features(v)),
"timings" => self.timings = Some(parse_timings(v)),
"doctest-xcompile" => self.doctest_xcompile = parse_empty(k, v)?,
"doctest-in-workspace" => self.doctest_in_workspace = parse_empty(k, v)?,
"panic-abort-tests" => self.panic_abort_tests = parse_empty(k, v)?,
@ -904,6 +897,7 @@ impl CliUnstable {
"future-incompat-report" => {
stabilized_warn(k, "1.59.0", STABILIZED_FUTURE_INCOMPAT_REPORT)
}
"timings" => stabilized_warn(k, "1.60", STABILIZED_TIMINGS),
_ => bail!("unknown `-Z` flag specified: {}", k),
}

View File

@ -1,4 +1,4 @@
use crate::core::compiler::{BuildConfig, MessageFormat};
use crate::core::compiler::{BuildConfig, MessageFormat, TimingOutput};
use crate::core::resolver::CliFeatures;
use crate::core::{Edition, Workspace};
use crate::ops::{CompileFilter, CompileOptions, NewOptions, Packages, VersionControl};
@ -234,6 +234,14 @@ pub trait AppExt: Sized {
fn arg_quiet(self) -> Self {
self._arg(opt("quiet", "Do not print cargo log messages").short('q'))
}
fn arg_timings(self) -> Self {
self._arg(optional_multi_opt(
"timings",
"FMTS",
"Timing output formats (comma separated): html, json (unstable)",
))
}
}
impl AppExt for App {
@ -499,6 +507,29 @@ pub trait ArgMatchesExt {
build_config.build_plan = self.is_valid_and_present("build-plan");
build_config.unit_graph = self.is_valid_and_present("unit-graph");
build_config.future_incompat_report = self.is_valid_and_present("future-incompat-report");
if self.is_valid_and_present("timings") {
for timing_output in self._values_of("timings") {
for timing_output in timing_output.split(',') {
let timing_output = timing_output.to_ascii_lowercase();
let timing_output = match timing_output.as_str() {
"html" => TimingOutput::Html,
"json" => {
config
.cli_unstable()
.fail_if_stable_opt("--timings=json", 7405)?;
TimingOutput::Json
}
s => bail!("invalid timings output specifier: `{}`", s),
};
build_config.timing_outputs.push(timing_output);
}
}
if build_config.timing_outputs.is_empty() {
build_config.timing_outputs.push(TimingOutput::Html);
}
}
if build_config.build_plan {
config
.cli_unstable()

View File

@ -95,6 +95,8 @@ target.
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -39,6 +39,8 @@ they have `required-features` that are missing.
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -44,6 +44,8 @@ they have `required-features` that are missing.
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -78,6 +78,8 @@ and supports common Unix glob patterns.
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -124,6 +124,8 @@ When no target selection options are given, `cargo fix` will fix all targets
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -167,6 +167,8 @@ See also the `--profile` option for choosing a specific profile by name.
{{> options-profile }}
{{> options-timings }}
{{/options}}
### Manifest Options

View File

@ -54,6 +54,8 @@ Run the specified example.
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -66,6 +66,8 @@ See the [the reference](../reference/profiles.html) for more details on profiles
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -66,6 +66,8 @@ if its name is the same as the lib target. Binaries are skipped if they have
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -106,6 +106,8 @@ target options.
{{> options-ignore-rust-version }}
{{> options-timings }}
{{/options}}
### Output Options

View File

@ -219,6 +219,21 @@ OPTIONS
than the required Rust version as configured in the project's
rust-version field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -156,6 +156,21 @@ OPTIONS
the required Rust version as configured in the project's
rust-version field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -169,6 +169,21 @@ OPTIONS
the required Rust version as configured in the project's
rust-version field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -140,6 +140,21 @@ OPTIONS
the required Rust version as configured in the project's
rust-version field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -242,6 +242,21 @@ OPTIONS
required Rust version as configured in the project's rust-version
field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -205,6 +205,21 @@ OPTIONS
<https://doc.rust-lang.org/cargo/reference/profiles.html> for more
details on profiles.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Manifest Options
--frozen, --locked
Either of these flags requires that the Cargo.lock file is

View File

@ -85,6 +85,21 @@ OPTIONS
required Rust version as configured in the project's rust-version
field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -164,6 +164,21 @@ OPTIONS
the required Rust version as configured in the project's
rust-version field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -156,6 +156,21 @@ OPTIONS
the required Rust version as configured in the project's
rust-version field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -233,6 +233,21 @@ OPTIONS
required Rust version as configured in the project's rust-version
field.
--timings fmts
Output information how long each compilation takes, and track
concurrency information over time. Accepts an optional
comma-separated list of output formats; --timing without an argument
will default to --timing=html. Valid output formats:
o html: Write a human-readable file cargo-timing.html to the
current directory with a report of the compilation. Also write a
report with a timestamp in the filename if you want to look at
older runs. HTML output is suitable for human consumption only,
and does not provide machine-readable timing data.
o json (unstable, requires -Zunstable-options): Emit
machine-readable JSON information about timing information.
Output Options
--target-dir directory
Directory for all generated artifacts and intermediate files. May

View File

@ -0,0 +1,15 @@
{{#option "`--timings` _fmts_"}}
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; `--timing` without an argument will default to `--timing=html`. Valid
output formats:
- `html`: Write a human-readable file `cargo-timing.html` to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.
- `json` (unstable, requires `-Zunstable-options`): Emit machine-readable JSON
information about timing information.
{{/option}}

View File

@ -265,6 +265,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-bench---timings"><a class="option-anchor" href="#option-cargo-bench---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -200,6 +200,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-build---timings"><a class="option-anchor" href="#option-cargo-build---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -209,6 +209,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-check---timings"><a class="option-anchor" href="#option-cargo-check---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -183,6 +183,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-doc---timings"><a class="option-anchor" href="#option-cargo-doc---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -289,6 +289,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-fix---timings"><a class="option-anchor" href="#option-cargo-fix---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -236,6 +236,24 @@ See the <a href="../reference/profiles.html">the reference</a> for more details
<dt class="option-term" id="option-cargo-install---timings"><a class="option-anchor" href="#option-cargo-install---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Manifest Options

View File

@ -118,6 +118,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-run---timings"><a class="option-anchor" href="#option-cargo-run---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -197,6 +197,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-rustc---timings"><a class="option-anchor" href="#option-cargo-rustc---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -202,6 +202,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-rustdoc---timings"><a class="option-anchor" href="#option-cargo-rustdoc---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -281,6 +281,24 @@ required Rust version as configured in the project's <code>rust-version</code> f
<dt class="option-term" id="option-cargo-test---timings"><a class="option-anchor" href="#option-cargo-test---timings"></a><code>--timings</code> <em>fmts</em></dt>
<dd class="option-desc">Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma-separated list of output
formats; <code>--timing</code> without an argument will default to <code>--timing=html</code>. Valid
output formats:</p>
<ul>
<li><code>html</code>: Write a human-readable file <code>cargo-timing.html</code> to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine-readable
timing data.</li>
<li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON
information about timing information.</li>
</ul></dd>
</dl>
### Output Options

View File

@ -35,9 +35,9 @@ how the feature works:
* `-Z` command-line flags are used to enable new functionality that may not
have an interface, or the interface has not yet been designed, or for more
complex features that affect multiple parts of Cargo. For example, the
[timings](#timings) feature can be enabled with:
[mtime-on-use](#mtime-on-use) feature can be enabled with:
```cargo +nightly build -Z timings```
```cargo +nightly build -Z mtime-on-use```
Run `cargo -Z help` to see a list of flags available.
@ -49,7 +49,6 @@ how the feature works:
[unstable]
mtime-on-use = true
multitarget = true
timings = ["html"]
```
Each new feature described below should explain how to use it.
@ -91,7 +90,6 @@ Each new feature described below should explain how to use it.
* [per-package-target](#per-package-target) — Sets the `--target` to use for each individual package.
* Information and metadata
* [Build-plan](#build-plan) — Emits JSON information on which commands will be run.
* [timings](#timings) — Generates a report on how long individual dependencies took to run.
* [unit-graph](#unit-graph) — Emits JSON for Cargo's internal graph structure.
* [`cargo rustc --print`](#rustc---print) — Calls rustc with `--print` to display information from rustc.
* Configuration
@ -403,26 +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.
### timings
* Tracking Issue: [#7405](https://github.com/rust-lang/cargo/issues/7405)
The `timings` feature gives some information about how long each compilation
takes, and tracks concurrency information over time.
```sh
cargo +nightly build -Z timings
```
The `-Ztimings` flag can optionally take a comma-separated list of the
following values:
- `html` — Saves a file called `cargo-timing.html` to the current directory
with a report of the compilation. Files are also saved with a timestamp in
the filename if you want to look at older runs.
- `json` — Emits some JSON information about timing information.
The default if none are specified is `html`.
#### Reading the graphs
There are two graphs in the output. The "unit" graph shows the duration of
@ -1315,3 +1293,9 @@ See the [Features chapter](features.md#optional-dependencies) for more informati
Weak dependency features has been stabilized in the 1.60 release.
See the [Features chapter](features.md#dependency-features) for more information.
### timings
The `-Ztimings` option has been stabilized as `--timings` in the 1.60 release.
(The machine-readable `--timings=json` output remains unstable and requires
`-Zunstable-options`.)

View File

@ -268,6 +268,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Benchmark the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -187,6 +187,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Build the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -198,6 +198,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Check the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -165,6 +165,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Document the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -293,6 +293,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Fix the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -266,6 +266,27 @@ See also the \fB\-\-profile\fR option for choosing a specific profile by name.
Install with the given profile.
See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Manifest Options"
.sp
\fB\-\-frozen\fR,

View File

@ -98,6 +98,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Run the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -193,6 +193,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Build the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -184,6 +184,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Document the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -284,6 +284,27 @@ See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles
Test the target even if the selected Rust compiler is older than the
required Rust version as configured in the project's \fBrust\-version\fR field.
.RE
.sp
\fB\-\-timings\fR \fIfmts\fR
.RS 4
Output information how long each compilation takes, and track concurrency
information over time. Accepts an optional comma\-separated list of output
formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. Valid
output formats:
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the current
directory with a report of the compilation. Also write a report with a
timestamp in the filename if you want to look at older runs. HTML output is
suitable for human consumption only, and does not provide machine\-readable
timing data.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON
information about timing information.
.RE
.RE
.SS "Output Options"
.sp
\fB\-\-target\-dir\fR \fIdirectory\fR

View File

@ -1,4 +1,4 @@
//! Tests for -Ztimings.
//! Tests for --timings.
use cargo_test_support::project;
use cargo_test_support::registry::Package;
@ -25,8 +25,7 @@ fn timings_works() {
.file("examples/ex1.rs", "fn main() {}")
.build();
p.cargo("build --all-targets -Ztimings")
.masquerade_as_nightly_cargo()
p.cargo("build --all-targets --timings")
.with_stderr_unordered(
"\
[UPDATING] [..]
@ -42,17 +41,13 @@ fn timings_works() {
p.cargo("clean").run();
p.cargo("test -Ztimings")
.masquerade_as_nightly_cargo()
.run();
p.cargo("test --timings").run();
p.cargo("clean").run();
p.cargo("check -Ztimings")
.masquerade_as_nightly_cargo()
.run();
p.cargo("check --timings").run();
p.cargo("clean").run();
p.cargo("doc -Ztimings").masquerade_as_nightly_cargo().run();
p.cargo("doc --timings").run();
}