diff --git a/.ignore b/.ignore index e51dabef3e8..716739c37d6 100644 --- a/.ignore +++ b/.ignore @@ -13,6 +13,7 @@ src/etc/man !src/doc/src/commands/manifest-commands.md !src/doc/src/commands/package-commands.md !src/doc/src/commands/publishing-commands.md +!src/doc/src/commands/report-commands.md # Snapshots of HTML reports and log files are just too large tests/testsuite/**/*.jsonl diff --git a/src/doc/man/cargo-report-future-incompatibilities.md b/src/doc/man/cargo-report-future-incompatibilities.md new file mode 100644 index 00000000000..3b1cd762146 --- /dev/null +++ b/src/doc/man/cargo-report-future-incompatibilities.md @@ -0,0 +1,64 @@ +# cargo-report-future-incompatibilities(1) +{{~*set actionverb="Display a report for"}} + +## NAME + +cargo-report-future-incompatibilities --- Reports any crates which will eventually stop compiling + +## SYNOPSIS + +`cargo report future-incompatibilities` [_options_] + +## DESCRIPTION + +Displays a report of future-incompatible warnings that were emitted during +previous builds. +These are warnings for changes that may become hard errors in the future, +causing dependencies to stop building in a future version of rustc. + +For more, see the chapter on [Future incompat report](../reference/future-incompat-report.html). + +## OPTIONS + +{{#options}} + +{{#option "`--id` _id_" }} +Show the report with the specified Cargo-generated id. +If not specified, shows the most recent report. +{{/option}} + +{{/options}} + +{{> section-options-package }} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Display the latest future-incompat report: + + cargo report future-incompat + +2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep@0.0.1 + +## SEE ALSO + +{{man "cargo" 1}}, {{man "cargo-report" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-report.md b/src/doc/man/cargo-report.md index ba33617dbb0..fb3af85570c 100644 --- a/src/doc/man/cargo-report.md +++ b/src/doc/man/cargo-report.md @@ -8,35 +8,36 @@ cargo-report --- Generate and display various kinds of reports `cargo report` _type_ [_options_] -### DESCRIPTION +## DESCRIPTION Displays a report of the given _type_ --- currently, only `future-incompat` is supported ## OPTIONS -{{#options}} +### Display Options -{{#option "`--id` _id_" }} -Show the report with the specified Cargo-generated id -{{/option}} +{{#options}} +{{> options-display }} +{{/options}} -{{#option "`-p` _spec_..." "`--package` _spec_..." }} -Only display a report for the specified package -{{/option}} +### Manifest Options +{{#options}} +{{> options-locked }} {{/options}} -## EXAMPLES +{{> section-options-common }} + +{{> section-environment }} -1. Display the latest future-incompat report: +{{> section-exit-status }} - cargo report future-incompat +## EXAMPLES -2. Display the latest future-incompat report for a specific package: +1. Display the available kinds of reports: - cargo report future-incompat --package my-dep:0.0.1 + cargo report --help ## SEE ALSO -[Future incompat report](../reference/future-incompat-report.html) -{{man "cargo" 1}} +{{man "cargo" 1}}, {{man "cargo-report-future-incompatibilities" 1}} diff --git a/src/doc/man/cargo.md b/src/doc/man/cargo.md index 21bfe620aee..271fd058d8a 100644 --- a/src/doc/man/cargo.md +++ b/src/doc/man/cargo.md @@ -123,6 +123,14 @@ available at . {{man "cargo-yank" 1}}\     Remove a pushed crate from the index. +### Report Commands + +{{man "cargo-report" 1}}\ +    Generate and display various kinds of reports. + +{{man "cargo-report-future-incompatibilities" 1}}\ +    Reports any crates which will eventually stop compiling. + ### General Commands {{man "cargo-help" 1}}\ diff --git a/src/doc/man/generated_txt/cargo-report-future-incompatibilities.txt b/src/doc/man/generated_txt/cargo-report-future-incompatibilities.txt new file mode 100644 index 00000000000..6caa69b8030 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-report-future-incompatibilities.txt @@ -0,0 +1,148 @@ +CARGO-REPORT-FUTURE-INCOMPATIBILITIES(1) + +NAME + cargo-report-future-incompatibilities — Reports any crates which will + eventually stop compiling + +SYNOPSIS + cargo report future-incompatibilities [options] + +DESCRIPTION + Displays a report of future-incompatible warnings that were emitted + during previous builds. These are warnings for changes that may become + hard errors in the future, causing dependencies to stop building in a + future version of rustc. + + For more, see the chapter on Future incompat report + . + +OPTIONS + --id id + Show the report with the specified Cargo-generated id. If not + specified, shows the most recent report. + + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to display a report for. See cargo-pkgid(1) for the SPEC + format. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + . + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + . + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --locked + Asserts that the exact same dependencies and versions are used as + when the existing Cargo.lock file was originally generated. Cargo + will exit with an error when either of the following scenarios + arises: + + o The lock file is missing. + + o Cargo attempted to change the lock file due to a different + dependency resolution. + + It may be used in environments where deterministic builds are + desired, such as in CI pipelines. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + --frozen + Equivalent to specifying both --locked and --offline. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. This + option must appear before the command name, for example cargo -C + path/to/my-project build. + + This option is only available on the nightly channel + and + requires the -Z unstable-options flag to enable (see #10098 + ). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the latest future-incompat report: + + cargo report future-incompat + + 2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep@0.0.1 + +SEE ALSO + cargo(1), cargo-report(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-report.txt b/src/doc/man/generated_txt/cargo-report.txt index f75a60c50e1..81eec46577f 100644 --- a/src/doc/man/generated_txt/cargo-report.txt +++ b/src/doc/man/generated_txt/cargo-report.txt @@ -6,29 +6,121 @@ NAME SYNOPSIS cargo report type [options] - DESCRIPTION +DESCRIPTION Displays a report of the given type — currently, only future-incompat is supported OPTIONS - --id id - Show the report with the specified Cargo-generated id + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + . - -p spec…, --package spec… - Only display a report for the specified package + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + . -EXAMPLES - 1. Display the latest future-incompat report: + --color when + Control when colored output is used. Valid values: - cargo report future-incompat + o auto (default): Automatically detect if color support is + available on the terminal. - 2. Display the latest future-incompat report for a specific package: + o always: Always display colors. - cargo report future-incompat --package my-dep:0.0.1 + o never: Never display colors. -SEE ALSO - Future incompat report - + May also be specified with the term.color config value + . + + Manifest Options + --locked + Asserts that the exact same dependencies and versions are used as + when the existing Cargo.lock file was originally generated. Cargo + will exit with an error when either of the following scenarios + arises: + + o The lock file is missing. + + o Cargo attempted to change the lock file due to a different + dependency resolution. + + It may be used in environments where deterministic builds are + desired, such as in CI pipelines. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + --frozen + Equivalent to specifying both --locked and --offline. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + + for more information. - cargo(1) + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. This + option must appear before the command name, for example cargo -C + path/to/my-project build. + + This option is only available on the nightly channel + and + requires the -Z unstable-options flag to enable (see #10098 + ). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the available kinds of reports: + + cargo report --help + +SEE ALSO + cargo(1), cargo-report-future-incompatibilities(1) diff --git a/src/doc/man/generated_txt/cargo.txt b/src/doc/man/generated_txt/cargo.txt index b2e359fa5f1..7ab37a5a2fa 100644 --- a/src/doc/man/generated_txt/cargo.txt +++ b/src/doc/man/generated_txt/cargo.txt @@ -117,6 +117,13 @@ COMMANDS cargo-yank(1)     Remove a pushed crate from the index. + Report Commands + cargo-report(1) +     Generate and display various kinds of reports. + + cargo-report-future-incompatibilities(1) +     Reports any crates which will eventually stop compiling. + General Commands cargo-help(1)     Display help information about Cargo. diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index 40f6d4a5ed3..011c20492a8 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -66,7 +66,6 @@ * [cargo fix](commands/cargo-fix.md) * [cargo fmt](commands/cargo-fmt.md) * [cargo miri](commands/cargo-miri.md) - * [cargo report](commands/cargo-report.md) * [cargo run](commands/cargo-run.md) * [cargo rustc](commands/cargo-rustc.md) * [cargo rustdoc](commands/cargo-rustdoc.md) @@ -95,6 +94,9 @@ * [cargo package](commands/cargo-package.md) * [cargo publish](commands/cargo-publish.md) * [cargo yank](commands/cargo-yank.md) + * [Report Commands](commands/report-commands.md) + * [cargo report](commands/cargo-report.md) + * [cargo report future-incompatibilities](commands/cargo-report-future-incompatibilities.md) * [Deprecated and Removed](commands/deprecated-and-removed.md) * [FAQ](faq.md) diff --git a/src/doc/src/commands/build-commands.md b/src/doc/src/commands/build-commands.md index f49f1916d79..2e86635c592 100644 --- a/src/doc/src/commands/build-commands.md +++ b/src/doc/src/commands/build-commands.md @@ -9,7 +9,6 @@ * [cargo fix](cargo-fix.md) * [cargo fmt](cargo-fmt.md) * [cargo miri](cargo-miri.md) -* [cargo report](cargo-report.md) * [cargo run](cargo-run.md) * [cargo rustc](cargo-rustc.md) * [cargo rustdoc](cargo-rustdoc.md) diff --git a/src/doc/src/commands/cargo-report-future-incompatibilities.md b/src/doc/src/commands/cargo-report-future-incompatibilities.md new file mode 100644 index 00000000000..c055d5c40e3 --- /dev/null +++ b/src/doc/src/commands/cargo-report-future-incompatibilities.md @@ -0,0 +1,184 @@ +# cargo-report-future-incompatibilities(1) +## NAME + +cargo-report-future-incompatibilities --- Reports any crates which will eventually stop compiling + +## SYNOPSIS + +`cargo report future-incompatibilities` [_options_] + +## DESCRIPTION + +Displays a report of future-incompatible warnings that were emitted during +previous builds. +These are warnings for changes that may become hard errors in the future, +causing dependencies to stop building in a future version of rustc. + +For more, see the chapter on [Future incompat report](../reference/future-incompat-report.html). + +## OPTIONS + +
+ +
--id id
+

Show the report with the specified Cargo-generated id. +If not specified, shows the most recent report.

+
+ + +
+ +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +
+ +
-p spec
+
--package spec
+

The package to display a report for. See cargo-pkgid(1) for the SPEC +format.

+
+ + +
+ +### Display Options + +
+
-v
+
--verbose
+

Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+ + +
-q
+
--quiet
+

Do not print cargo log messages. +May also be specified with the term.quiet +config value.

+
+ + +
--color when
+

Control when colored output is used. Valid values:

+
    +
  • auto (default): Automatically detect if color support is available on the +terminal.
    • +
  • always: Always display colors.
    • +
  • never: Never display colors.
    • +
+

May also be specified with the term.color +config value.

+
+ +
+ +### Manifest Options + +
+
--locked
+

Asserts that the exact same dependencies and versions are used as when the +existing Cargo.lock file was originally generated. Cargo will exit with an +error when either of the following scenarios arises:

+
    +
  • The lock file is missing.
    • +
  • Cargo attempted to change the lock file due to a different dependency resolution.
    • +
+

It may be used in environments where deterministic builds are desired, +such as in CI pipelines.

+
+ + +
--offline
+

Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+
+ + +
--frozen
+

Equivalent to specifying both --locked and --offline.

+
+ +
+ +### Common Options + +
+ +
+toolchain
+

If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.

+
+ + +
--config KEY=VALUE or PATH
+

Overrides a Cargo configuration value. The argument should be in TOML syntax of KEY=VALUE, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the command-line overrides section for more information.

+
+ + +
-C PATH
+

Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (Cargo.toml), as well as +the directories searched for discovering .cargo/config.toml, for example. This option must +appear before the command name, for example cargo -C path/to/my-project build.

+

This option is only available on the nightly +channel and +requires the -Z unstable-options flag to enable (see +#10098).

+
+ + +
-h
+
--help
+

Prints help information.

+
+ + +
-Z flag
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.

+
+ + +
+ +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + +## EXAMPLES + +1. Display the latest future-incompat report: + + cargo report future-incompat + +2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep@0.0.1 + +## SEE ALSO + +[cargo(1)](cargo.html), [cargo-report(1)](cargo-report.html), [cargo-build(1)](cargo-build.html) diff --git a/src/doc/src/commands/cargo-report.md b/src/doc/src/commands/cargo-report.md index f7553b14c73..048ac94a8f1 100644 --- a/src/doc/src/commands/cargo-report.md +++ b/src/doc/src/commands/cargo-report.md @@ -8,38 +8,143 @@ cargo-report --- Generate and display various kinds of reports `cargo report` _type_ [_options_] -### DESCRIPTION +## DESCRIPTION Displays a report of the given _type_ --- currently, only `future-incompat` is supported ## OPTIONS +### Display Options +
+
-v
+
--verbose
+

Use verbose output. May be specified twice for “very verbose” output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+ + +
-q
+
--quiet
+

Do not print cargo log messages. +May also be specified with the term.quiet +config value.

+
-
--id id
-

Show the report with the specified Cargo-generated id

+ +
--color when
+

Control when colored output is used. Valid values:

+
    +
  • auto (default): Automatically detect if color support is available on the +terminal.
    • +
  • always: Always display colors.
    • +
  • never: Never display colors.
    • +
+

May also be specified with the term.color +config value.

+
+ +### Manifest Options -
-p spec…
-
--package spec…
-

Only display a report for the specified package

+
+
--locked
+

Asserts that the exact same dependencies and versions are used as when the +existing Cargo.lock file was originally generated. Cargo will exit with an +error when either of the following scenarios arises:

+
    +
  • The lock file is missing.
    • +
  • Cargo attempted to change the lock file due to a different dependency resolution.
    • +
+

It may be used in environments where deterministic builds are desired, +such as in CI pipelines.

+
--offline
+

Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+
+ + +
--frozen
+

Equivalent to specifying both --locked and --offline.

+
+
-## EXAMPLES +### Common Options + +
+ +
+toolchain
+

If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.

+
-1. Display the latest future-incompat report: - cargo report future-incompat +
--config KEY=VALUE or PATH
+

Overrides a Cargo configuration value. The argument should be in TOML syntax of KEY=VALUE, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the command-line overrides section for more information.

+
+ + +
-C PATH
+

Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (Cargo.toml), as well as +the directories searched for discovering .cargo/config.toml, for example. This option must +appear before the command name, for example cargo -C path/to/my-project build.

+

This option is only available on the nightly +channel and +requires the -Z unstable-options flag to enable (see +#10098).

+
+ + +
-h
+
--help
+

Prints help information.

+
+ + +
-Z flag
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.

+
+ + +
+ +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + +## EXAMPLES -2. Display the latest future-incompat report for a specific package: +1. Display the available kinds of reports: - cargo report future-incompat --package my-dep:0.0.1 + cargo report --help ## SEE ALSO -[Future incompat report](../reference/future-incompat-report.html) -[cargo(1)](cargo.html) +[cargo(1)](cargo.html), [cargo-report-future-incompatibilities(1)](cargo-report-future-incompatibilities.html) diff --git a/src/doc/src/commands/cargo.md b/src/doc/src/commands/cargo.md index 03676e24927..ad328144c6f 100644 --- a/src/doc/src/commands/cargo.md +++ b/src/doc/src/commands/cargo.md @@ -123,6 +123,14 @@ available at . [cargo-yank(1)](cargo-yank.html)\     Remove a pushed crate from the index. +### Report Commands + +[cargo-report(1)](cargo-report.html)\ +    Generate and display various kinds of reports. + +[cargo-report-future-incompatibilities(1)](cargo-report-future-incompatibilities.html)\ +    Reports any crates which will eventually stop compiling. + ### General Commands [cargo-help(1)](cargo-help.html)\ diff --git a/src/doc/src/commands/index.md b/src/doc/src/commands/index.md index 8de601a618d..5e636823c16 100644 --- a/src/doc/src/commands/index.md +++ b/src/doc/src/commands/index.md @@ -4,4 +4,5 @@ * [Manifest Commands](manifest-commands.md) * [Package Commands](package-commands.md) * [Publishing Commands](publishing-commands.md) +* [Report Commands](report-commands.md) * [Deprecated and Removed](deprecated-and-removed.md) diff --git a/src/doc/src/commands/report-commands.md b/src/doc/src/commands/report-commands.md new file mode 100644 index 00000000000..6e97cb65dc1 --- /dev/null +++ b/src/doc/src/commands/report-commands.md @@ -0,0 +1,3 @@ +# Report Commands + +* [cargo report](cargo-report.md) diff --git a/src/etc/man/cargo-report-future-incompatibilities.1 b/src/etc/man/cargo-report-future-incompatibilities.1 new file mode 100644 index 00000000000..5c749f189bb --- /dev/null +++ b/src/etc/man/cargo-report-future-incompatibilities.1 @@ -0,0 +1,188 @@ +'\" t +.TH "CARGO\-REPORT\-FUTURE\-INCOMPATIBILITIES" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-report\-future\-incompatibilities \[em] Reports any crates which will eventually stop compiling +.SH "SYNOPSIS" +\fBcargo report future\-incompatibilities\fR [\fIoptions\fR] +.SH "DESCRIPTION" +Displays a report of future\-incompatible warnings that were emitted during +previous builds. +These are warnings for changes that may become hard errors in the future, +causing dependencies to stop building in a future version of rustc. +.sp +For more, see the chapter on \fIFuture incompat report\fR \&. +.SH "OPTIONS" +.sp +\fB\-\-id\fR \fIid\fR +.RS 4 +Show the report with the specified Cargo\-generated id. +If not specified, shows the most recent report. +.RE +.SS "Package Selection" +By default, the package in the current working directory is selected. The \fB\-p\fR +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +The package to display a report for. See \fBcargo\-pkgid\fR(1) for the SPEC +format. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR \&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-locked\fR +.RS 4 +Asserts that the exact same dependencies and versions are used as when the +existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an +error when either of the following scenarios arises: +.sp +.RS 4 +\h'-04'\(bu\h'+03'The lock file is missing. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'Cargo attempted to change the lock file due to a different dependency resolution. +.RE +.sp +It may be used in environments where deterministic builds are desired, +such as in CI pipelines. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. +.RE +.sp +\fB\-\-frozen\fR +.RS 4 +Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must +appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&. +.sp +This option is only available on the \fInightly +channel\fR and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR ). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Display the latest future\-incompat report: +.sp +.RS 4 +.nf +cargo report future\-incompat +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Display the latest future\-incompat report for a specific package: +.sp +.RS 4 +.nf +cargo report future\-incompat \-\-package my\-dep@0.0.1 +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-report\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-report.1 b/src/etc/man/cargo-report.1 index 24b6305699b..f507d6853e6 100644 --- a/src/etc/man/cargo-report.1 +++ b/src/etc/man/cargo-report.1 @@ -7,42 +7,151 @@ cargo\-report \[em] Generate and display various kinds of reports .SH "SYNOPSIS" \fBcargo report\fR \fItype\fR [\fIoptions\fR] -.SS "DESCRIPTION" +.SH "DESCRIPTION" Displays a report of the given \fItype\fR \[em] currently, only \fBfuture\-incompat\fR is supported .SH "OPTIONS" +.SS "Display Options" .sp -\fB\-\-id\fR \fIid\fR +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 -Show the report with the specified Cargo\-generated id +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-p\fR \fIspec\fR\[u2026], -\fB\-\-package\fR \fIspec\fR\[u2026] +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 -Only display a report for the specified package +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR \&. .RE -.SH "EXAMPLES" .sp +\fB\-\-color\fR \fIwhen\fR .RS 4 -\h'-04' 1.\h'+01'Display the latest future\-incompat report: +Control when colored output is used. Valid values: .sp .RS 4 -.nf -cargo report future\-incompat -.fi +\h'-04'\(bu\h'+03'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-locked\fR +.RS 4 +Asserts that the exact same dependencies and versions are used as when the +existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an +error when either of the following scenarios arises: +.sp +.RS 4 +\h'-04'\(bu\h'+03'The lock file is missing. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'Cargo attempted to change the lock file due to a different dependency resolution. +.RE +.sp +It may be used in environments where deterministic builds are desired, +such as in CI pipelines. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE +.sp +\fB\-\-frozen\fR +.RS 4 +Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. This option must +appear before the command name, for example \fBcargo \-C path/to/my\-project build\fR\&. +.sp +This option is only available on the \fInightly +channel\fR and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR ). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. .RE .sp +\fB\-Z\fR \fIflag\fR .RS 4 -\h'-04' 2.\h'+01'Display the latest future\-incompat report for a specific package: +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+03'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Display the available kinds of reports: .sp .RS 4 .nf -cargo report future\-incompat \-\-package my\-dep:0.0.1 +cargo report \-\-help .fi .RE .RE .SH "SEE ALSO" -\fIFuture incompat report\fR -.sp -\fBcargo\fR(1) +\fBcargo\fR(1), \fBcargo\-report\-future\-incompatibilities\fR(1) diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 index 80c8682a6ef..a45843c5ff0 100644 --- a/src/etc/man/cargo.1 +++ b/src/etc/man/cargo.1 @@ -147,6 +147,14 @@ available at \&. \fBcargo\-yank\fR(1) .br \ \ \ \ Remove a pushed crate from the index. +.SS "Report Commands" +\fBcargo\-report\fR(1) +.br +\ \ \ \ Generate and display various kinds of reports. +.sp +\fBcargo\-report\-future\-incompatibilities\fR(1) +.br +\ \ \ \ Reports any crates which will eventually stop compiling. .SS "General Commands" \fBcargo\-help\fR(1) .br diff --git a/tests/testsuite/cargo_report_future_incompat/help/mod.rs b/tests/testsuite/cargo_report_future_incompat/help/mod.rs new file mode 100644 index 00000000000..d0667ab4098 --- /dev/null +++ b/tests/testsuite/cargo_report_future_incompat/help/mod.rs @@ -0,0 +1,14 @@ +use crate::prelude::*; +use cargo_test_support::file; +use cargo_test_support::str; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .args(["report", "future-incompat"]) + .arg("--help") + .assert() + .success() + .stdout_eq(file!["stdout.term.svg"]) + .stderr_eq(str![""]); +} diff --git a/tests/testsuite/cargo_report_future_incompat/help/stdout.term.svg b/tests/testsuite/cargo_report_future_incompat/help/stdout.term.svg new file mode 100644 index 00000000000..8392fecb480 --- /dev/null +++ b/tests/testsuite/cargo_report_future_incompat/help/stdout.term.svg @@ -0,0 +1,69 @@ + + + + + + + Reports any crates which will eventually stop compiling + + + + Usage: cargo[EXE] report future-incompatibilities [OPTIONS] + + + + Options: + + --id <id> identifier of the report generated by a Cargo command invocation + + -v, --verbose... Use verbose output (-vv very verbose/build.rs output) + + -q, --quiet Do not print cargo log messages + + --color <WHEN> Coloring [possible values: auto, always, never] + + --config <KEY=VALUE|PATH> Override a configuration value + + -Z <FLAG> Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for + + details + + -h, --help Print help + + + + Package Selection: + + -p, --package [<SPEC>] Package to display a report for + + + + Manifest Options: + + --locked Assert that `Cargo.lock` will remain unchanged + + --offline Run without accessing the network + + --frozen Equivalent to specifying both --locked and --offline + + + + + + diff --git a/tests/testsuite/cargo_report_future_incompat/mod.rs b/tests/testsuite/cargo_report_future_incompat/mod.rs new file mode 100644 index 00000000000..c0ce1118071 --- /dev/null +++ b/tests/testsuite/cargo_report_future_incompat/mod.rs @@ -0,0 +1 @@ +mod help; diff --git a/tests/testsuite/main.rs b/tests/testsuite/main.rs index ff63c642b5d..16971afb716 100644 --- a/tests/testsuite/main.rs +++ b/tests/testsuite/main.rs @@ -52,6 +52,7 @@ mod cargo_publish; mod cargo_read_manifest; mod cargo_remove; mod cargo_report; +mod cargo_report_future_incompat; mod cargo_report_rebuilds; mod cargo_report_sessions; mod cargo_report_timings;