From 86bb4a0c2be26d4227fb7dd6d9e45154af646661 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Fri, 14 Jan 2022 14:50:28 -0800 Subject: [PATCH 1/7] Remove `-Ztimings=info` The text-based timing information emits many additional lines, creating quite a bit of verbosity. Remove in favor of the HTML report, as suggested at https://github.com/rust-lang/cargo/pull/10245#issuecomment-1003741052 . If we re-add text-based timing information in the future, it could come in the form of a text-based report, or as a duration printed on the same line as the crate it measures rather than a separate line. --- src/cargo/core/compiler/timings.rs | 18 +----------------- src/cargo/core/features.rs | 2 +- src/doc/src/reference/unstable.md | 4 +--- tests/testsuite/timings.rs | 7 ------- 4 files changed, 3 insertions(+), 28 deletions(-) diff --git a/src/cargo/core/compiler/timings.rs b/src/cargo/core/compiler/timings.rs index 33b46ce1671..3d59bb3cfc3 100644 --- a/src/cargo/core/compiler/timings.rs +++ b/src/cargo/core/compiler/timings.rs @@ -21,8 +21,6 @@ pub struct Timings<'cfg> { enabled: bool, /// If true, saves an HTML report to disk. report_html: bool, - /// If true, reports unit completion to stderr. - report_info: bool, /// If true, emits JSON information with timing information. report_json: bool, /// When Cargo started. @@ -102,9 +100,8 @@ impl<'cfg> Timings<'cfg> { .map_or(false, |t| t.iter().any(|opt| opt == what)) }; let report_html = has_report("html"); - let report_info = has_report("info"); let report_json = has_report("json"); - let enabled = report_html | report_info | report_json; + let enabled = report_html | report_json; let mut root_map: HashMap> = HashMap::new(); for unit in root_units { @@ -139,7 +136,6 @@ impl<'cfg> Timings<'cfg> { config: bcx.config, enabled, report_html, - report_info, report_json, start: bcx.config.creation_time(), start_str, @@ -227,18 +223,6 @@ impl<'cfg> Timings<'cfg> { unit_time .unlocked_units .extend(unlocked.iter().cloned().cloned()); - if self.report_info { - let msg = format!( - "{}{} in {:.1}s", - unit_time.name_ver(), - unit_time.target, - unit_time.duration - ); - let _ = self - .config - .shell() - .status_with_color("Completed", msg, termcolor::Color::Cyan); - } if self.report_json { let msg = machine_message::TimingInfo { package_id: unit_time.unit.pkg.package_id(), diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 61452542a51..d5593e71824 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -770,7 +770,7 @@ impl CliUnstable { fn parse_timings(value: Option<&str>) -> Vec { match value { - None => vec!["html".to_string(), "info".to_string()], + None => vec!["html".to_string()], Some(v) => v.split(',').map(|s| s.to_string()).collect(), } } diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index c23d09773ae..f5849e9ed13 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -419,11 +419,9 @@ 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. -- `info` — Displays a message to stdout after each compilation finishes with - how long it took. - `json` — Emits some JSON information about timing information. -The default if none are specified is `html,info`. +The default if none are specified is `html`. #### Reading the graphs diff --git a/tests/testsuite/timings.rs b/tests/testsuite/timings.rs index cd173dd74c9..1b61f0863b3 100644 --- a/tests/testsuite/timings.rs +++ b/tests/testsuite/timings.rs @@ -34,13 +34,6 @@ fn timings_works() { [DOWNLOADED] dep v0.1.0 [..] [COMPILING] dep v0.1.0 [COMPILING] foo v0.1.0 [..] -[COMPLETED] dep v0.1.0 in [..]s -[COMPLETED] foo v0.1.0 in [..]s -[COMPLETED] foo v0.1.0 bin \"foo\" in [..]s -[COMPLETED] foo v0.1.0 example \"ex1\" in [..]s -[COMPLETED] foo v0.1.0 lib (test) in [..]s -[COMPLETED] foo v0.1.0 bin \"foo\" (test) in [..]s -[COMPLETED] foo v0.1.0 test \"t1\" (test) in [..]s [FINISHED] [..] Timing report saved to [..]/foo/cargo-timing-[..].html ", From c06691897a749f8df425c62106b33813cdf11e3c Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sat, 1 Jan 2022 18:47:04 -0800 Subject: [PATCH 2/7] 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. --- src/bin/cargo/commands/bench.rs | 1 + src/bin/cargo/commands/build.rs | 1 + src/bin/cargo/commands/check.rs | 1 + src/bin/cargo/commands/doc.rs | 1 + src/bin/cargo/commands/fix.rs | 1 + src/bin/cargo/commands/install.rs | 1 + src/bin/cargo/commands/run.rs | 1 + src/bin/cargo/commands/rustc.rs | 1 + src/bin/cargo/commands/rustdoc.rs | 1 + src/bin/cargo/commands/test.rs | 1 + src/cargo/core/compiler/build_config.rs | 12 ++++++++ src/cargo/core/compiler/job_queue.rs | 2 +- src/cargo/core/compiler/mod.rs | 2 +- src/cargo/core/compiler/timings.rs | 14 +++------ src/cargo/core/features.rs | 12 ++------ src/cargo/util/command_prelude.rs | 33 ++++++++++++++++++++- src/doc/man/cargo-bench.md | 2 ++ src/doc/man/cargo-build.md | 2 ++ src/doc/man/cargo-check.md | 2 ++ src/doc/man/cargo-doc.md | 2 ++ src/doc/man/cargo-fix.md | 2 ++ src/doc/man/cargo-install.md | 2 ++ src/doc/man/cargo-run.md | 2 ++ src/doc/man/cargo-rustc.md | 2 ++ src/doc/man/cargo-rustdoc.md | 2 ++ src/doc/man/cargo-test.md | 2 ++ src/doc/man/generated_txt/cargo-bench.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-build.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-check.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-doc.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-fix.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-install.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-run.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-rustc.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-rustdoc.txt | 15 ++++++++++ src/doc/man/generated_txt/cargo-test.txt | 15 ++++++++++ src/doc/man/includes/options-timings.md | 15 ++++++++++ src/doc/src/commands/cargo-bench.md | 18 +++++++++++ src/doc/src/commands/cargo-build.md | 18 +++++++++++ src/doc/src/commands/cargo-check.md | 18 +++++++++++ src/doc/src/commands/cargo-doc.md | 18 +++++++++++ src/doc/src/commands/cargo-fix.md | 18 +++++++++++ src/doc/src/commands/cargo-install.md | 18 +++++++++++ src/doc/src/commands/cargo-run.md | 18 +++++++++++ src/doc/src/commands/cargo-rustc.md | 18 +++++++++++ src/doc/src/commands/cargo-rustdoc.md | 18 +++++++++++ src/doc/src/commands/cargo-test.md | 18 +++++++++++ src/doc/src/reference/unstable.md | 32 +++++--------------- src/etc/man/cargo-bench.1 | 21 +++++++++++++ src/etc/man/cargo-build.1 | 21 +++++++++++++ src/etc/man/cargo-check.1 | 21 +++++++++++++ src/etc/man/cargo-doc.1 | 21 +++++++++++++ src/etc/man/cargo-fix.1 | 21 +++++++++++++ src/etc/man/cargo-install.1 | 21 +++++++++++++ src/etc/man/cargo-run.1 | 21 +++++++++++++ src/etc/man/cargo-rustc.1 | 21 +++++++++++++ src/etc/man/cargo-rustdoc.1 | 21 +++++++++++++ src/etc/man/cargo-test.1 | 21 +++++++++++++ tests/testsuite/timings.rs | 15 ++++------ 59 files changed, 651 insertions(+), 56 deletions(-) create mode 100644 src/doc/man/includes/options-timings.md diff --git a/src/bin/cargo/commands/bench.rs b/src/bin/cargo/commands/bench.rs index 64a89bdb93a..4cd48294c8f 100644 --- a/src/bin/cargo/commands/bench.rs +++ b/src/bin/cargo/commands/bench.rs @@ -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") } diff --git a/src/bin/cargo/commands/build.rs b/src/bin/cargo/commands/build.rs index 367cad83884..9bcf29fe901 100644 --- a/src/bin/cargo/commands/build.rs +++ b/src/bin/cargo/commands/build.rs @@ -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") } diff --git a/src/bin/cargo/commands/check.rs b/src/bin/cargo/commands/check.rs index 07b98be707a..6d6a1446418 100644 --- a/src/bin/cargo/commands/check.rs +++ b/src/bin/cargo/commands/check.rs @@ -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") } diff --git a/src/bin/cargo/commands/doc.rs b/src/bin/cargo/commands/doc.rs index 9833594493a..27d6a5b24be 100644 --- a/src/bin/cargo/commands/doc.rs +++ b/src/bin/cargo/commands/doc.rs @@ -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") } diff --git a/src/bin/cargo/commands/fix.rs b/src/bin/cargo/commands/fix.rs index c8e36c58062..153f5eb03e7 100644 --- a/src/bin/cargo/commands/fix.rs +++ b/src/bin/cargo/commands/fix.rs @@ -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") } diff --git a/src/bin/cargo/commands/install.rs b/src/bin/cargo/commands/install.rs index ac68d1efabd..c5564bfbba5 100644 --- a/src/bin/cargo/commands/install.rs +++ b/src/bin/cargo/commands/install.rs @@ -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") } diff --git a/src/bin/cargo/commands/run.rs b/src/bin/cargo/commands/run.rs index 57b69dbf293..1763decbaad 100644 --- a/src/bin/cargo/commands/run.rs +++ b/src/bin/cargo/commands/run.rs @@ -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") } diff --git a/src/bin/cargo/commands/rustc.rs b/src/bin/cargo/commands/rustc.rs index c9291d4f02e..2580732ff6b 100644 --- a/src/bin/cargo/commands/rustc.rs +++ b/src/bin/cargo/commands/rustc.rs @@ -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") } diff --git a/src/bin/cargo/commands/rustdoc.rs b/src/bin/cargo/commands/rustdoc.rs index 3f5d07d9d2b..cdf6717dde1 100644 --- a/src/bin/cargo/commands/rustdoc.rs +++ b/src/bin/cargo/commands/rustdoc.rs @@ -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") } diff --git a/src/bin/cargo/commands/test.rs b/src/bin/cargo/commands/test.rs index a02bdb57443..23ecee0c351 100644 --- a/src/bin/cargo/commands/test.rs +++ b/src/bin/cargo/commands/test.rs @@ -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", diff --git a/src/cargo/core/compiler/build_config.rs b/src/cargo/core/compiler/build_config.rs index 3770bb68c54..e7964afe72b 100644 --- a/src/cargo/core/compiler/build_config.rs +++ b/src/cargo/core/compiler/build_config.rs @@ -39,6 +39,8 @@ pub struct BuildConfig { pub export_dir: Option, /// `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, } 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, +} diff --git a/src/cargo/core/compiler/job_queue.rs b/src/cargo/core/compiler/job_queue.rs index 86f23ee1c9e..a82e37a6c12 100644 --- a/src/cargo/core/compiler/job_queue.rs +++ b/src/cargo/core/compiler/job_queue.rs @@ -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( diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs index ff535d0c31a..242868e94f1 100644 --- a/src/cargo/core/compiler/mod.rs +++ b/src/cargo/core/compiler/mod.rs @@ -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, }; diff --git a/src/cargo/core/compiler/timings.rs b/src/cargo/core/compiler/timings.rs index 3d59bb3cfc3..f83ca4eab1d 100644 --- a/src/cargo/core/compiler/timings.rs +++ b/src/cargo/core/compiler/timings.rs @@ -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> = HashMap::new(); diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index d5593e71824..41557ef1a93 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -652,7 +652,6 @@ unstable_cli_options!( rustdoc_map: bool = ("Allow passing external documentation mappings to rustdoc"), separate_nightlies: bool = (HIDDEN), terminal_width: Option> = ("Provide a terminal width to rustc for error truncation"), - timings: Option> = ("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>, D::Error> where D: serde::Deserializer<'de>, @@ -768,13 +769,6 @@ impl CliUnstable { } } - fn parse_timings(value: Option<&str>) -> Vec { - match value { - None => vec!["html".to_string()], - Some(v) => v.split(',').map(|s| s.to_string()).collect(), - } - } - fn parse_features(value: Option<&str>) -> Vec { 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), } diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index c2c5a937c11..383ced3030d 100644 --- a/src/cargo/util/command_prelude.rs +++ b/src/cargo/util/command_prelude.rs @@ -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() diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md index ded8e2b361f..51aeccc89c0 100644 --- a/src/doc/man/cargo-bench.md +++ b/src/doc/man/cargo-bench.md @@ -95,6 +95,8 @@ target. {{> options-ignore-rust-version }} +{{> options-timings }} + {{/options}} ### Output Options diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md index 1a06b998343..e4a2bac6d9f 100644 --- a/src/doc/man/cargo-build.md +++ b/src/doc/man/cargo-build.md @@ -39,6 +39,8 @@ they have `required-features` that are missing. {{> options-ignore-rust-version }} +{{> options-timings }} + {{/options}} ### Output Options diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md index e0020f7c41a..109830fc97b 100644 --- a/src/doc/man/cargo-check.md +++ b/src/doc/man/cargo-check.md @@ -44,6 +44,8 @@ they have `required-features` that are missing. {{> options-ignore-rust-version }} +{{> options-timings }} + {{/options}} ### Output Options diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md index 551adfcf951..3b70384cae1 100644 --- a/src/doc/man/cargo-doc.md +++ b/src/doc/man/cargo-doc.md @@ -78,6 +78,8 @@ and supports common Unix glob patterns. {{> options-ignore-rust-version }} +{{> options-timings }} + {{/options}} ### Output Options diff --git a/src/doc/man/cargo-fix.md b/src/doc/man/cargo-fix.md index 2d96efd4217..c37e306389e 100644 --- a/src/doc/man/cargo-fix.md +++ b/src/doc/man/cargo-fix.md @@ -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 diff --git a/src/doc/man/cargo-install.md b/src/doc/man/cargo-install.md index 28d7c6ab16e..0aec46165c9 100644 --- a/src/doc/man/cargo-install.md +++ b/src/doc/man/cargo-install.md @@ -167,6 +167,8 @@ See also the `--profile` option for choosing a specific profile by name. {{> options-profile }} +{{> options-timings }} + {{/options}} ### Manifest Options diff --git a/src/doc/man/cargo-run.md b/src/doc/man/cargo-run.md index b4e1d06695f..c9b661ff791 100644 --- a/src/doc/man/cargo-run.md +++ b/src/doc/man/cargo-run.md @@ -54,6 +54,8 @@ Run the specified example. {{> options-ignore-rust-version }} +{{> options-timings }} + {{/options}} ### Output Options diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md index 53ed339caa8..d1a47d178bb 100644 --- a/src/doc/man/cargo-rustc.md +++ b/src/doc/man/cargo-rustc.md @@ -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 diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md index 278c569646c..cd517248b10 100644 --- a/src/doc/man/cargo-rustdoc.md +++ b/src/doc/man/cargo-rustdoc.md @@ -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 diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md index be12eaa70a1..3b5eb13f4bc 100644 --- a/src/doc/man/cargo-test.md +++ b/src/doc/man/cargo-test.md @@ -106,6 +106,8 @@ target options. {{> options-ignore-rust-version }} +{{> options-timings }} + {{/options}} ### Output Options diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index 4a773e8a313..4af04dcc13b 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index 5fa54ab0e1b..fd3bdfecf47 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt index 2f63b5683cd..0e9a7c846d5 100644 --- a/src/doc/man/generated_txt/cargo-check.txt +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt index 7eaccd30b03..72612538c06 100644 --- a/src/doc/man/generated_txt/cargo-doc.txt +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt index 1e22f364ce8..482741faf9c 100644 --- a/src/doc/man/generated_txt/cargo-fix.txt +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt index 9cb8c1d97f8..5aacdbfdda7 100644 --- a/src/doc/man/generated_txt/cargo-install.txt +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -205,6 +205,21 @@ OPTIONS 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 diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt index 032789dc798..1187c78557c 100644 --- a/src/doc/man/generated_txt/cargo-run.txt +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt index 5ec4c010768..22c9a0499b3 100644 --- a/src/doc/man/generated_txt/cargo-rustc.txt +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt index 618a833e05b..74773483ec2 100644 --- a/src/doc/man/generated_txt/cargo-rustdoc.txt +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -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 diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index a0167413213..92834ae8194 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -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 diff --git a/src/doc/man/includes/options-timings.md b/src/doc/man/includes/options-timings.md new file mode 100644 index 00000000000..b6c19f962d6 --- /dev/null +++ b/src/doc/man/includes/options-timings.md @@ -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}} + diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index 88cbe5d62ed..74307a6bce4 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -265,6 +265,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 22b96acbe10..6e7dd053e06 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -200,6 +200,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index 655775a6dec..2e795823c9d 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -209,6 +209,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index 13eb90b6e8e..e2636b6a9c4 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -183,6 +183,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index d9866051620..42046b7cab9 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -289,6 +289,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 3576d51df1f..687d7a93060 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -236,6 +236,24 @@ See the the reference for more details +
--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.
    • +
+ + + + ### Manifest Options diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 5dbc0663453..2162d4d3e4d 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -118,6 +118,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index 28879dfee12..fbc077f0092 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -197,6 +197,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index 2bc43ed44e2..99741446a42 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -202,6 +202,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 4b28129ecfd..e602060c87e 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -281,6 +281,24 @@ required Rust version as configured in the project's rust-version f +
--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.
    • +
+ + + + ### Output Options diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index f5849e9ed13..bf0260cdca2 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -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`.) diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 105cef5a6b3..4b920f12779 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -268,6 +268,27 @@ See the \fIthe reference\fR 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, diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 5092ece9b0d..55d962b6ba6 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -98,6 +98,27 @@ See the \fIthe reference\fR Date: Fri, 14 Jan 2022 18:08:19 -0800 Subject: [PATCH 3/7] Move timing reports to `target/cargo-timings` This avoids dropping them wherever Cargo happens to run from, and instead places them under the target directory. This has the advantage, and disadvantage, that `cargo clean` will remove them. --- src/cargo/core/compiler/job_queue.rs | 2 +- src/cargo/core/compiler/timings.rs | 21 ++++++++++----------- src/doc/man/generated_txt/cargo-bench.txt | 9 +++++---- src/doc/man/generated_txt/cargo-build.txt | 9 +++++---- src/doc/man/generated_txt/cargo-check.txt | 9 +++++---- src/doc/man/generated_txt/cargo-doc.txt | 9 +++++---- src/doc/man/generated_txt/cargo-fix.txt | 9 +++++---- src/doc/man/generated_txt/cargo-install.txt | 9 +++++---- src/doc/man/generated_txt/cargo-run.txt | 9 +++++---- src/doc/man/generated_txt/cargo-rustc.txt | 9 +++++---- src/doc/man/generated_txt/cargo-rustdoc.txt | 9 +++++---- src/doc/man/generated_txt/cargo-test.txt | 9 +++++---- src/doc/man/includes/options-timings.md | 10 +++++----- src/doc/src/commands/cargo-bench.md | 10 +++++----- src/doc/src/commands/cargo-build.md | 10 +++++----- src/doc/src/commands/cargo-check.md | 10 +++++----- src/doc/src/commands/cargo-doc.md | 10 +++++----- src/doc/src/commands/cargo-fix.md | 10 +++++----- src/doc/src/commands/cargo-install.md | 10 +++++----- src/doc/src/commands/cargo-run.md | 10 +++++----- src/doc/src/commands/cargo-rustc.md | 10 +++++----- src/doc/src/commands/cargo-rustdoc.md | 10 +++++----- src/doc/src/commands/cargo-test.md | 10 +++++----- src/etc/man/cargo-bench.1 | 10 +++++----- src/etc/man/cargo-build.1 | 10 +++++----- src/etc/man/cargo-check.1 | 10 +++++----- src/etc/man/cargo-doc.1 | 10 +++++----- src/etc/man/cargo-fix.1 | 10 +++++----- src/etc/man/cargo-install.1 | 10 +++++----- src/etc/man/cargo-run.1 | 10 +++++----- src/etc/man/cargo-rustc.1 | 10 +++++----- src/etc/man/cargo-rustdoc.1 | 10 +++++----- src/etc/man/cargo-test.1 | 10 +++++----- tests/testsuite/timings.rs | 2 +- 34 files changed, 167 insertions(+), 158 deletions(-) diff --git a/src/cargo/core/compiler/job_queue.rs b/src/cargo/core/compiler/job_queue.rs index a82e37a6c12..c3d76c8b0c7 100644 --- a/src/cargo/core/compiler/job_queue.rs +++ b/src/cargo/core/compiler/job_queue.rs @@ -839,7 +839,7 @@ impl<'cfg> DrainState<'cfg> { } let time_elapsed = util::elapsed(cx.bcx.config.creation_time().elapsed()); - if let Err(e) = self.timings.finished(cx.bcx, &error) { + if let Err(e) = self.timings.finished(cx, &error) { if error.is_some() { crate::display_error(&e, &mut cx.bcx.config.shell()); } else { diff --git a/src/cargo/core/compiler/timings.rs b/src/cargo/core/compiler/timings.rs index f83ca4eab1d..77dcec94f6d 100644 --- a/src/cargo/core/compiler/timings.rs +++ b/src/cargo/core/compiler/timings.rs @@ -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, TimingOutput}; +use crate::core::compiler::{BuildContext, Context, TimingOutput}; use crate::core::PackageId; use crate::util::cpu::State; use crate::util::machine_message::{self, Message}; @@ -293,7 +293,7 @@ impl<'cfg> Timings<'cfg> { /// Call this when all units are finished. pub fn finished( &mut self, - bcx: &BuildContext<'_, '_>, + cx: &Context<'_, '_>, error: &Option, ) -> CargoResult<()> { if !self.enabled { @@ -303,21 +303,19 @@ impl<'cfg> Timings<'cfg> { self.unit_times .sort_unstable_by(|a, b| a.start.partial_cmp(&b.start).unwrap()); if self.report_html { - self.report_html(bcx, error) + self.report_html(cx, error) .with_context(|| "failed to save timing report")?; } Ok(()) } /// Save HTML report to disk. - fn report_html( - &self, - bcx: &BuildContext<'_, '_>, - error: &Option, - ) -> CargoResult<()> { + fn report_html(&self, cx: &Context<'_, '_>, error: &Option) -> CargoResult<()> { let duration = self.start.elapsed().as_secs_f64(); let timestamp = self.start_str.replace(&['-', ':'][..], ""); - let filename = format!("cargo-timing-{}.html", timestamp); + let timings_path = cx.files().host_root().join("cargo-timings"); + paths::create_dir_all(&timings_path)?; + let filename = timings_path.join(format!("cargo-timing-{}.html", timestamp)); let mut f = BufWriter::new(paths::create(&filename)?); let roots: Vec<&str> = self .root_targets @@ -325,7 +323,7 @@ impl<'cfg> Timings<'cfg> { .map(|(name, _targets)| name.as_str()) .collect(); f.write_all(HTML_TMPL.replace("{ROOTS}", &roots.join(", ")).as_bytes())?; - self.write_summary_table(&mut f, duration, bcx, error)?; + self.write_summary_table(&mut f, duration, cx.bcx, error)?; f.write_all(HTML_CANVAS.as_bytes())?; self.write_unit_table(&mut f)?; // It helps with pixel alignment to use whole numbers. @@ -353,7 +351,8 @@ impl<'cfg> Timings<'cfg> { .join(&filename) .display() ); - paths::link_or_copy(&filename, "cargo-timing.html")?; + let unstamped_filename = timings_path.join("cargo-timing.html"); + paths::link_or_copy(&filename, &unstamped_filename)?; self.config .shell() .status_with_color("Timing", msg, termcolor::Color::Cyan)?; diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index 4af04dcc13b..c1c96b266ad 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -226,10 +226,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index fd3bdfecf47..5973934f079 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -163,10 +163,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt index 0e9a7c846d5..2cf490451eb 100644 --- a/src/doc/man/generated_txt/cargo-check.txt +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -176,10 +176,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt index 72612538c06..9c2eeb7df77 100644 --- a/src/doc/man/generated_txt/cargo-doc.txt +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -147,10 +147,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt index 482741faf9c..3bfcca1a1b4 100644 --- a/src/doc/man/generated_txt/cargo-fix.txt +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -249,10 +249,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt index 5aacdbfdda7..24273d9f3fb 100644 --- a/src/doc/man/generated_txt/cargo-install.txt +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -212,10 +212,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt index 1187c78557c..8186f93659a 100644 --- a/src/doc/man/generated_txt/cargo-run.txt +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -92,10 +92,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt index 22c9a0499b3..e818e85c599 100644 --- a/src/doc/man/generated_txt/cargo-rustc.txt +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -171,10 +171,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt index 74773483ec2..5682af5e590 100644 --- a/src/doc/man/generated_txt/cargo-rustdoc.txt +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -163,10 +163,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index 92834ae8194..5d0f1190afd 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -240,10 +240,11 @@ OPTIONS 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. + target/cargo-timings directory with a report of the compilation. + Also write a report to the same directory 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. diff --git a/src/doc/man/includes/options-timings.md b/src/doc/man/includes/options-timings.md index b6c19f962d6..92b2a43a364 100644 --- a/src/doc/man/includes/options-timings.md +++ b/src/doc/man/includes/options-timings.md @@ -4,11 +4,11 @@ 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. +- `html`: Write a human-readable file `cargo-timing.html` to the + `target/cargo-timings` directory with a report of the compilation. Also write + a report to the same directory 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}} diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index 74307a6bce4..c83eeeb228d 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -271,11 +271,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 6e7dd053e06..1268240da7e 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -206,11 +206,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index 2e795823c9d..dbf6ac55790 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -215,11 +215,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index e2636b6a9c4..f10d4e63e4b 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -189,11 +189,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index 42046b7cab9..b0073444ca0 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -295,11 +295,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 687d7a93060..26359f4d12e 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -242,11 +242,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 2162d4d3e4d..ea44b520d35 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -124,11 +124,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index fbc077f0092..866a387602e 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -203,11 +203,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index 99741446a42..748b07a272a 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -208,11 +208,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index e602060c87e..ea7f830f329 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -287,11 +287,11 @@ 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.
    • +
  • html: Write a human-readable file cargo-timing.html to the +target/cargo-timings directory with a report of the compilation. Also write +a report to the same directory 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.
diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 4b920f12779..63fafbd8cef 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -277,11 +277,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index d70b08b4c14..a99938be469 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -196,11 +196,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index f7099312788..fd7efc183e5 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -207,11 +207,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index fce856a7a35..42e18efba98 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -174,11 +174,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index e1ea6d13fb4..1f1dc57c629 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -302,11 +302,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index e46ba58c84d..20eb512dab2 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -275,11 +275,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 55d962b6ba6..afbee23498e 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -107,11 +107,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index 10375d8e0e8..c694eeda59e 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -202,11 +202,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 11421f534b0..f7a47795c81 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -193,11 +193,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 4405428ecf2..95ddf24d0e3 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -293,11 +293,11 @@ formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html 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. +\h'-04'\(bu\h'+02'\fBhtml\fR: Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR directory with a report of the compilation. Also write +a report to the same directory 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 diff --git a/tests/testsuite/timings.rs b/tests/testsuite/timings.rs index 3b3dfe861fe..8f06ac69bc7 100644 --- a/tests/testsuite/timings.rs +++ b/tests/testsuite/timings.rs @@ -34,7 +34,7 @@ fn timings_works() { [COMPILING] dep v0.1.0 [COMPILING] foo v0.1.0 [..] [FINISHED] [..] - Timing report saved to [..]/foo/cargo-timing-[..].html + Timing report saved to [..]/foo/target/cargo-timings/cargo-timing-[..].html ", ) .run(); From c8542471499a626da2e4188ae15b5c96f119ae35 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sun, 30 Jan 2022 15:18:14 -0800 Subject: [PATCH 4/7] Make `--timings` require `=` if passing an argument This avoids ambiguity between its optional argument and positional arguments. --- src/cargo/util/command_prelude.rs | 13 ++++++++----- 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-doc.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-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-timings.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-doc.md | 2 +- src/doc/src/commands/cargo-fix.md | 2 +- src/doc/src/commands/cargo-install.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/etc/man/cargo-bench.1 | 2 +- src/etc/man/cargo-build.1 | 2 +- src/etc/man/cargo-check.1 | 2 +- src/etc/man/cargo-doc.1 | 2 +- src/etc/man/cargo-fix.1 | 2 +- src/etc/man/cargo-install.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 +- 32 files changed, 39 insertions(+), 36 deletions(-) diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index 383ced3030d..fa1d18c3e3c 100644 --- a/src/cargo/util/command_prelude.rs +++ b/src/cargo/util/command_prelude.rs @@ -236,11 +236,14 @@ pub trait AppExt: Sized { } fn arg_timings(self) -> Self { - self._arg(optional_multi_opt( - "timings", - "FMTS", - "Timing output formats (comma separated): html, json (unstable)", - )) + self._arg( + optional_opt( + "timings", + "Timing output formats (comma separated): html, json (unstable)", + ) + .value_name("FMTS") + .require_equals(true), + ) } } diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index c1c96b266ad..2bd02a6c623 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -219,7 +219,7 @@ OPTIONS than the required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index 5973934f079..a2f61481116 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -156,7 +156,7 @@ OPTIONS the required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt index 2cf490451eb..de04a2bdccb 100644 --- a/src/doc/man/generated_txt/cargo-check.txt +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -169,7 +169,7 @@ OPTIONS the required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt index 9c2eeb7df77..8cf2cdb48bb 100644 --- a/src/doc/man/generated_txt/cargo-doc.txt +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -140,7 +140,7 @@ OPTIONS the required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt index 3bfcca1a1b4..06d5c16471a 100644 --- a/src/doc/man/generated_txt/cargo-fix.txt +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -242,7 +242,7 @@ OPTIONS required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt index 24273d9f3fb..14ac8b67ebe 100644 --- a/src/doc/man/generated_txt/cargo-install.txt +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -205,7 +205,7 @@ OPTIONS for more details on profiles. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt index 8186f93659a..180f913f803 100644 --- a/src/doc/man/generated_txt/cargo-run.txt +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -85,7 +85,7 @@ OPTIONS required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt index e818e85c599..0a6df2c28e5 100644 --- a/src/doc/man/generated_txt/cargo-rustc.txt +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -164,7 +164,7 @@ OPTIONS the required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt index 5682af5e590..14e08cc0f96 100644 --- a/src/doc/man/generated_txt/cargo-rustdoc.txt +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -156,7 +156,7 @@ OPTIONS the required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index 5d0f1190afd..c77d1d29985 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -233,7 +233,7 @@ OPTIONS required Rust version as configured in the project's rust-version field. - --timings fmts + --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 diff --git a/src/doc/man/includes/options-timings.md b/src/doc/man/includes/options-timings.md index 92b2a43a364..829581067f2 100644 --- a/src/doc/man/includes/options-timings.md +++ b/src/doc/man/includes/options-timings.md @@ -1,4 +1,4 @@ -{{#option "`--timings` _fmts_"}} +{{#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 diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index c83eeeb228d..c7a7a445cfd 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -265,7 +265,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 1268240da7e..fb86806a066 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -200,7 +200,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index dbf6ac55790..f2b8311c02a 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -209,7 +209,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index f10d4e63e4b..7629a052620 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -183,7 +183,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index b0073444ca0..1e5c603ca8e 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -289,7 +289,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 26359f4d12e..125eb39ecdd 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -236,7 +236,7 @@ See the the reference for more details -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index ea44b520d35..97882e1849f 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -118,7 +118,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index 866a387602e..cf62cbfd6eb 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -197,7 +197,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index 748b07a272a..61a3d5917b6 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -202,7 +202,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index ea7f830f329..fd16038c72c 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -281,7 +281,7 @@ required Rust version as configured in the project's rust-version f -
--timings fmts
+
--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 diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 63fafbd8cef..def5ef71de5 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -269,7 +269,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index a99938be469..336c806d773 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -188,7 +188,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index fd7efc183e5..44987a56be3 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -199,7 +199,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 42e18efba98..0292cf50f60 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -166,7 +166,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index 1f1dc57c629..7b9102cd24a 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -294,7 +294,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 20eb512dab2..765e15a86e4 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -267,7 +267,7 @@ Install with the given profile. See the \fIthe reference\fR for more details on profiles. .RE .sp -\fB\-\-timings\fR \fIfmts\fR +\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 diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index afbee23498e..1a6b3608de7 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -99,7 +99,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index c694eeda59e..c2e43725513 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -194,7 +194,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index f7a47795c81..c2ae5741256 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -185,7 +185,7 @@ 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 +\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 diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 95ddf24d0e3..75330ae6371 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -285,7 +285,7 @@ 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 +\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 From 81e1998e11c6e09a002bd15de37fbb1131b6eb22 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Sun, 30 Jan 2022 15:23:59 -0800 Subject: [PATCH 5/7] Make `--timings=html` unstable, and only stabilize `--timings` --- src/cargo/util/command_prelude.rs | 9 +++++++-- src/doc/man/generated_txt/cargo-bench.txt | 4 +++- src/doc/man/generated_txt/cargo-build.txt | 4 +++- src/doc/man/generated_txt/cargo-check.txt | 4 +++- src/doc/man/generated_txt/cargo-doc.txt | 4 +++- src/doc/man/generated_txt/cargo-fix.txt | 4 +++- src/doc/man/generated_txt/cargo-install.txt | 4 +++- src/doc/man/generated_txt/cargo-run.txt | 4 +++- src/doc/man/generated_txt/cargo-rustc.txt | 4 +++- src/doc/man/generated_txt/cargo-rustdoc.txt | 4 +++- src/doc/man/generated_txt/cargo-test.txt | 4 +++- src/doc/man/includes/options-timings.md | 5 +++-- src/doc/src/commands/cargo-bench.md | 5 +++-- src/doc/src/commands/cargo-build.md | 5 +++-- src/doc/src/commands/cargo-check.md | 5 +++-- src/doc/src/commands/cargo-doc.md | 5 +++-- src/doc/src/commands/cargo-fix.md | 5 +++-- src/doc/src/commands/cargo-install.md | 5 +++-- src/doc/src/commands/cargo-run.md | 5 +++-- src/doc/src/commands/cargo-rustc.md | 5 +++-- src/doc/src/commands/cargo-rustdoc.md | 5 +++-- src/doc/src/commands/cargo-test.md | 5 +++-- src/doc/src/reference/unstable.md | 4 ++-- src/etc/man/cargo-bench.1 | 5 +++-- src/etc/man/cargo-build.1 | 5 +++-- src/etc/man/cargo-check.1 | 5 +++-- src/etc/man/cargo-doc.1 | 5 +++-- src/etc/man/cargo-fix.1 | 5 +++-- src/etc/man/cargo-install.1 | 5 +++-- src/etc/man/cargo-run.1 | 5 +++-- src/etc/man/cargo-rustc.1 | 5 +++-- src/etc/man/cargo-rustdoc.1 | 5 +++-- src/etc/man/cargo-test.1 | 5 +++-- 33 files changed, 102 insertions(+), 56 deletions(-) diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index fa1d18c3e3c..635a2b17552 100644 --- a/src/cargo/util/command_prelude.rs +++ b/src/cargo/util/command_prelude.rs @@ -239,7 +239,7 @@ pub trait AppExt: Sized { self._arg( optional_opt( "timings", - "Timing output formats (comma separated): html, json (unstable)", + "Timing output formats (unstable) (comma separated): html, json", ) .value_name("FMTS") .require_equals(true), @@ -516,7 +516,12 @@ pub trait ArgMatchesExt { 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, + "html" => { + config + .cli_unstable() + .fail_if_stable_opt("--timings=html", 7405)?; + TimingOutput::Html + } "json" => { config .cli_unstable() diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index 2bd02a6c623..d3de4625dbb 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -223,7 +223,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index a2f61481116..8735155804c 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -160,7 +160,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt index de04a2bdccb..d9139d4aafe 100644 --- a/src/doc/man/generated_txt/cargo-check.txt +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -173,7 +173,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt index 8cf2cdb48bb..141952f1ca0 100644 --- a/src/doc/man/generated_txt/cargo-doc.txt +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -144,7 +144,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt index 06d5c16471a..36136c903fc 100644 --- a/src/doc/man/generated_txt/cargo-fix.txt +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -246,7 +246,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt index 14ac8b67ebe..4482c239e5b 100644 --- a/src/doc/man/generated_txt/cargo-install.txt +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -209,7 +209,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt index 180f913f803..42f23f96181 100644 --- a/src/doc/man/generated_txt/cargo-run.txt +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -89,7 +89,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt index 0a6df2c28e5..282adfbdedb 100644 --- a/src/doc/man/generated_txt/cargo-rustc.txt +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -168,7 +168,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt index 14e08cc0f96..7a73fe8d7b5 100644 --- a/src/doc/man/generated_txt/cargo-rustdoc.txt +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -160,7 +160,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index c77d1d29985..721e7ee7bf2 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -237,7 +237,9 @@ OPTIONS 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: + will default to --timing=html. Specifying an output format (rather + than the default) is unstable and requires -Zunstable-options. Valid + output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/includes/options-timings.md b/src/doc/man/includes/options-timings.md index 829581067f2..f04ab3c0c39 100644 --- a/src/doc/man/includes/options-timings.md +++ b/src/doc/man/includes/options-timings.md @@ -1,8 +1,9 @@ {{#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: +formats; `--timing` without an argument will default to `--timing=html`. +Specifying an output format (rather than the default) is unstable and requires +`-Zunstable-options`. Valid output formats: - `html`: Write a human-readable file `cargo-timing.html` to the `target/cargo-timings` directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index c7a7a445cfd..4ef92e37465 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -268,8 +268,9 @@ required Rust version as configured in the project's rust-version f
--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:

+formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

  • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index fb86806a066..12805d03fae 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -203,8 +203,9 @@ required Rust version as configured in the project's rust-version f
    --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:

    +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

    • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index f2b8311c02a..1645ed3da41 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -212,8 +212,9 @@ required Rust version as configured in the project's rust-version f
      --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:

      +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

      • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index 7629a052620..ddcba30904c 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -186,8 +186,9 @@ required Rust version as configured in the project's rust-version f
        --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:

        +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

        • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index 1e5c603ca8e..2d9cbc1ec5a 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -292,8 +292,9 @@ required Rust version as configured in the project's rust-version f
          --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:

          +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

          • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 125eb39ecdd..3baf93a7f67 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -239,8 +239,9 @@ See the the reference for more details
            --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:

            +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

            • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 97882e1849f..4117192de4a 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -121,8 +121,9 @@ required Rust version as configured in the project's rust-version f
              --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:

              +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

              • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index cf62cbfd6eb..71bec66517b 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -200,8 +200,9 @@ required Rust version as configured in the project's rust-version f
                --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:

                +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

                • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index 61a3d5917b6..76119a7c606 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -205,8 +205,9 @@ required Rust version as configured in the project's rust-version f
                  --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:

                  +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

                  • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index fd16038c72c..7828943a697 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -284,8 +284,9 @@ required Rust version as configured in the project's rust-version f
                    --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:

                    +formats; --timing without an argument will default to --timing=html. +Specifying an output format (rather than the default) is unstable and requires +-Zunstable-options. Valid output formats:

                    • html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. Also write diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index bf0260cdca2..efecbc75633 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -1297,5 +1297,5 @@ 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`.) +(`--timings=html` and the machine-readable `--timings=json` output remain +unstable and require `-Zunstable-options`.) diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index def5ef71de5..7d6e38435f9 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -273,8 +273,9 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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: +formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\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 diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index 336c806d773..aac58a1592d 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -192,8 +192,9 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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: +formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\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 diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index 44987a56be3..0c740814d2a 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -203,8 +203,9 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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: +formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\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 diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 0292cf50f60..4a7e11e429c 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -170,8 +170,9 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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: +formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\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 diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index 7b9102cd24a..b84eb0a771e 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -298,8 +298,9 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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: +formats; \fB\-\-timing\fR without an argument will default to \fB\-\-timing=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\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 diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 765e15a86e4..c5d133c916b 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -271,8 +271,9 @@ See the \fIthe reference\fR Date: Sun, 30 Jan 2022 15:24:55 -0800 Subject: [PATCH 6/7] Fix typo: `--timing` -> `--timings` --- src/doc/man/generated_txt/cargo-bench.txt | 8 ++++---- src/doc/man/generated_txt/cargo-build.txt | 8 ++++---- src/doc/man/generated_txt/cargo-check.txt | 8 ++++---- src/doc/man/generated_txt/cargo-doc.txt | 8 ++++---- src/doc/man/generated_txt/cargo-fix.txt | 8 ++++---- src/doc/man/generated_txt/cargo-install.txt | 8 ++++---- src/doc/man/generated_txt/cargo-run.txt | 8 ++++---- src/doc/man/generated_txt/cargo-rustc.txt | 8 ++++---- src/doc/man/generated_txt/cargo-rustdoc.txt | 8 ++++---- src/doc/man/generated_txt/cargo-test.txt | 8 ++++---- src/doc/man/includes/options-timings.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-doc.md | 2 +- src/doc/src/commands/cargo-fix.md | 2 +- src/doc/src/commands/cargo-install.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/etc/man/cargo-bench.1 | 2 +- src/etc/man/cargo-build.1 | 2 +- src/etc/man/cargo-check.1 | 2 +- src/etc/man/cargo-doc.1 | 2 +- src/etc/man/cargo-fix.1 | 2 +- src/etc/man/cargo-install.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 +- 31 files changed, 61 insertions(+), 61 deletions(-) diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index d3de4625dbb..d0cf157035d 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -222,10 +222,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index 8735155804c..0cfb6539b54 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -159,10 +159,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt index d9139d4aafe..cb2e547064f 100644 --- a/src/doc/man/generated_txt/cargo-check.txt +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -172,10 +172,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt index 141952f1ca0..1341c7f38cd 100644 --- a/src/doc/man/generated_txt/cargo-doc.txt +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -143,10 +143,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt index 36136c903fc..1af91e83269 100644 --- a/src/doc/man/generated_txt/cargo-fix.txt +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -245,10 +245,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt index 4482c239e5b..791bb553058 100644 --- a/src/doc/man/generated_txt/cargo-install.txt +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -208,10 +208,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt index 42f23f96181..7ddfa0cf9ee 100644 --- a/src/doc/man/generated_txt/cargo-run.txt +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -88,10 +88,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt index 282adfbdedb..fde805e9b4e 100644 --- a/src/doc/man/generated_txt/cargo-rustc.txt +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -167,10 +167,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt index 7a73fe8d7b5..a2695c0289e 100644 --- a/src/doc/man/generated_txt/cargo-rustdoc.txt +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -159,10 +159,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index 721e7ee7bf2..72027e10e6b 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -236,10 +236,10 @@ OPTIONS --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. Specifying an output format (rather - than the default) is unstable and requires -Zunstable-options. Valid - output formats: + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: o html: Write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. diff --git a/src/doc/man/includes/options-timings.md b/src/doc/man/includes/options-timings.md index f04ab3c0c39..963b30d4719 100644 --- a/src/doc/man/includes/options-timings.md +++ b/src/doc/man/includes/options-timings.md @@ -1,7 +1,7 @@ {{#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`. +formats; `--timings` without an argument will default to `--timings=html`. Specifying an output format (rather than the default) is unstable and requires `-Zunstable-options`. Valid output formats: diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index 4ef92e37465..95343ef3d39 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -268,7 +268,7 @@ required Rust version as configured in the project's rust-version f
                      --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                        diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 12805d03fae..c1a55f4b07e 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -203,7 +203,7 @@ required Rust version as configured in the project's rust-version f
                        --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                          diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index 1645ed3da41..4c1068f9758 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -212,7 +212,7 @@ required Rust version as configured in the project's rust-version f
                          --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                            diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index ddcba30904c..fc25c692e5b 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -186,7 +186,7 @@ required Rust version as configured in the project's rust-version f
                            --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                              diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index 2d9cbc1ec5a..b00344a3e88 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -292,7 +292,7 @@ required Rust version as configured in the project's rust-version f
                              --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                                diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 3baf93a7f67..7d11122e1f7 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -239,7 +239,7 @@ See the the reference for more details
                                --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                                  diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 4117192de4a..ec7d28a92b0 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -121,7 +121,7 @@ required Rust version as configured in the project's rust-version f
                                  --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                                    diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index 71bec66517b..a1ffcc81166 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -200,7 +200,7 @@ required Rust version as configured in the project's rust-version f
                                    --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                                      diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index 76119a7c606..8417a5d2746 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -205,7 +205,7 @@ required Rust version as configured in the project's rust-version f
                                      --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                                        diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 7828943a697..5cb84bbf07c 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -284,7 +284,7 @@ required Rust version as configured in the project's rust-version f
                                        --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. +formats; --timings without an argument will default to --timings=html. Specifying an output format (rather than the default) is unstable and requires -Zunstable-options. Valid output formats:

                                          diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 7d6e38435f9..b38409e2464 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -273,7 +273,7 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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\&. +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. Specifying an output format (rather than the default) is unstable and requires \fB\-Zunstable\-options\fR\&. Valid output formats: .sp diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index aac58a1592d..80c7b988737 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -192,7 +192,7 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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\&. +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. Specifying an output format (rather than the default) is unstable and requires \fB\-Zunstable\-options\fR\&. Valid output formats: .sp diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index 0c740814d2a..d496867273c 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -203,7 +203,7 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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\&. +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. Specifying an output format (rather than the default) is unstable and requires \fB\-Zunstable\-options\fR\&. Valid output formats: .sp diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 4a7e11e429c..089aac26c48 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -170,7 +170,7 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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\&. +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. Specifying an output format (rather than the default) is unstable and requires \fB\-Zunstable\-options\fR\&. Valid output formats: .sp diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index b84eb0a771e..d5ee2200bcf 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -298,7 +298,7 @@ required Rust version as configured in the project's \fBrust\-version\fR field. .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\&. +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. Specifying an output format (rather than the default) is unstable and requires \fB\-Zunstable\-options\fR\&. Valid output formats: .sp diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index c5d133c916b..bb68b3c8ddf 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -271,7 +271,7 @@ See the \fIthe reference\fR Date: Sun, 30 Jan 2022 19:25:53 -0800 Subject: [PATCH 7/7] 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)