diff --git a/src/bin/cargo/commands/help.rs b/src/bin/cargo/commands/help.rs index 913dabb1424..d838a627731 100644 --- a/src/bin/cargo/commands/help.rs +++ b/src/bin/cargo/commands/help.rs @@ -79,10 +79,13 @@ fn try_help(gctx: &GlobalContext, subcommand: &str) -> CargoResult { None => return Ok(false), }; - if resolve_executable(Path::new("man")).is_ok() { - let man = match extract_man(subcommand, "1") { - Some(man) => man, - None => return Ok(false), + // ALLOWED: For testing cargo itself only. + #[allow(clippy::disallowed_methods)] + let force_help_text = std::env::var("__CARGO_TEST_FORCE_HELP_TXT").is_ok(); + + if resolve_executable(Path::new("man")).is_ok() && !force_help_text { + let Some(man) = extract_man(subcommand, "1") else { + return Ok(false); }; write_and_spawn(subcommand, &man, "man")?; } else { @@ -90,7 +93,9 @@ fn try_help(gctx: &GlobalContext, subcommand: &str) -> CargoResult { Some(txt) => txt, None => return Ok(false), }; - if resolve_executable(Path::new("less")).is_ok() { + if force_help_text { + drop(std::io::stdout().write_all(&txt)); + } else if resolve_executable(Path::new("less")).is_ok() { write_and_spawn(subcommand, &txt, "less")?; } else if resolve_executable(Path::new("more")).is_ok() { write_and_spawn(subcommand, &txt, "more")?; diff --git a/src/doc/man/cargo-help.md b/src/doc/man/cargo-help.md index 4a5a8f51575..af9911c69d8 100644 --- a/src/doc/man/cargo-help.md +++ b/src/doc/man/cargo-help.md @@ -12,6 +12,26 @@ cargo-help --- Get help for a Cargo command Prints a help message for the given command. +## OPTIONS + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + ## EXAMPLES 1. Get help for a command: diff --git a/src/doc/man/cargo-remove.md b/src/doc/man/cargo-remove.md index e0d7c360ea6..f875db04a85 100644 --- a/src/doc/man/cargo-remove.md +++ b/src/doc/man/cargo-remove.md @@ -88,9 +88,9 @@ Package to remove from. cargo remove --dev trybuild -3. Remove `nom` from the `x86_64-pc-windows-gnu` dependencies table +3. Remove `nom` from the `wasm32-unknown-unknown` dependencies table - cargo remove --target x86_64-pc-windows-gnu nom + cargo remove --target wasm32-unknown-unknown nom ## SEE ALSO {{man "cargo" 1}}, {{man "cargo-add" 1}} diff --git a/src/doc/man/generated_txt/cargo-help.txt b/src/doc/man/generated_txt/cargo-help.txt index 0107ebe2c04..1b16b53cd07 100644 --- a/src/doc/man/generated_txt/cargo-help.txt +++ b/src/doc/man/generated_txt/cargo-help.txt @@ -9,6 +9,112 @@ SYNOPSIS DESCRIPTION Prints a help message for the given command. +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 + . + + --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. Get help for a command: diff --git a/src/doc/man/generated_txt/cargo-remove.txt b/src/doc/man/generated_txt/cargo-remove.txt index 9d8c14afcc9..cd889c9b775 100644 --- a/src/doc/man/generated_txt/cargo-remove.txt +++ b/src/doc/man/generated_txt/cargo-remove.txt @@ -152,9 +152,9 @@ EXAMPLES cargo remove --dev trybuild - 3. Remove nom from the x86_64-pc-windows-gnu dependencies table + 3. Remove nom from the wasm32-unknown-unknown dependencies table - cargo remove --target x86_64-pc-windows-gnu nom + cargo remove --target wasm32-unknown-unknown nom SEE ALSO cargo(1), cargo-add(1) diff --git a/src/doc/src/commands/cargo-help.md b/src/doc/src/commands/cargo-help.md index db5cb342abf..2e3a890d396 100644 --- a/src/doc/src/commands/cargo-help.md +++ b/src/doc/src/commands/cargo-help.md @@ -12,6 +12,133 @@ cargo-help --- Get help for a Cargo command Prints a help message for the given command. +## 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.

+
+ + +
--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. Get help for a command: diff --git a/src/doc/src/commands/cargo-remove.md b/src/doc/src/commands/cargo-remove.md index 4eca891b7a2..63d38657fbe 100644 --- a/src/doc/src/commands/cargo-remove.md +++ b/src/doc/src/commands/cargo-remove.md @@ -200,9 +200,9 @@ details on environment variables that Cargo reads. cargo remove --dev trybuild -3. Remove `nom` from the `x86_64-pc-windows-gnu` dependencies table +3. Remove `nom` from the `wasm32-unknown-unknown` dependencies table - cargo remove --target x86_64-pc-windows-gnu nom + cargo remove --target wasm32-unknown-unknown nom ## SEE ALSO [cargo(1)](cargo.html), [cargo-add(1)](cargo-add.html) diff --git a/src/etc/man/cargo-help.1 b/src/etc/man/cargo-help.1 index 655328550c0..46b810b5e3c 100644 --- a/src/etc/man/cargo-help.1 +++ b/src/etc/man/cargo-help.1 @@ -9,6 +9,139 @@ cargo\-help \[em] Get help for a Cargo command \fBcargo help\fR [\fIsubcommand\fR] .SH "DESCRIPTION" Prints a help message for the given command. +.SH "OPTIONS" +.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 diff --git a/src/etc/man/cargo-remove.1 b/src/etc/man/cargo-remove.1 index 15d964f9981..cc65aa28aea 100644 --- a/src/etc/man/cargo-remove.1 +++ b/src/etc/man/cargo-remove.1 @@ -202,11 +202,11 @@ cargo remove \-\-dev trybuild .RE .sp .RS 4 -\h'-04' 3.\h'+01'Remove \fBnom\fR from the \fBx86_64\-pc\-windows\-gnu\fR dependencies table +\h'-04' 3.\h'+01'Remove \fBnom\fR from the \fBwasm32\-unknown\-unknown\fR dependencies table .sp .RS 4 .nf -cargo remove \-\-target x86_64\-pc\-windows\-gnu nom +cargo remove \-\-target wasm32\-unknown\-unknown nom .fi .RE .RE diff --git a/tests/testsuite/cargo_help/mod.rs b/tests/testsuite/cargo_help/mod.rs index c0ce1118071..a0ee2ee2d9e 100644 --- a/tests/testsuite/cargo_help/mod.rs +++ b/tests/testsuite/cargo_help/mod.rs @@ -1 +1,12 @@ mod help; +mod nested_alias_dash_joined; +mod nested_cmd; +mod nested_cmd_dash_joined; +mod nested_cmd_suggestion; +mod nested_cmd_with_extra_flags; +mod nested_subcommand_suggestion; +mod single_alias; +mod single_cmd; +mod single_cmd_space_joined; +mod single_cmd_suggestion; +mod single_cmd_with_extra_flags; diff --git a/tests/testsuite/cargo_help/nested_alias_dash_joined/mod.rs b/tests/testsuite/cargo_help/nested_alias_dash_joined/mod.rs new file mode 100644 index 00000000000..0f59e38d4df --- /dev/null +++ b/tests/testsuite/cargo_help/nested_alias_dash_joined/mod.rs @@ -0,0 +1,14 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("report-future-incompat") + .assert() + .code(101) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/nested_alias_dash_joined/stderr.term.svg b/tests/testsuite/cargo_help/nested_alias_dash_joined/stderr.term.svg new file mode 100644 index 00000000000..c9a39bc8e59 --- /dev/null +++ b/tests/testsuite/cargo_help/nested_alias_dash_joined/stderr.term.svg @@ -0,0 +1,33 @@ + + + + + + + error: no such command: `report-future-incompat` + + + + help: view all installed commands with `cargo --list` + + help: find a package to install `report-future-incompat` with `cargo search cargo-report-future-incompat` + + + + + + diff --git a/tests/testsuite/cargo_help/nested_alias_dash_joined/stdout.term.txt b/tests/testsuite/cargo_help/nested_alias_dash_joined/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/nested_cmd/mod.rs b/tests/testsuite/cargo_help/nested_cmd/mod.rs new file mode 100644 index 00000000000..29dc2e3816a --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd/mod.rs @@ -0,0 +1,15 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("report") + .arg("future-incompatibilities") + .assert() + .code(1) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/nested_cmd/stderr.term.svg b/tests/testsuite/cargo_help/nested_cmd/stderr.term.svg new file mode 100644 index 00000000000..cce37f84ba7 --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd/stderr.term.svg @@ -0,0 +1,39 @@ + + + + + + + error: unexpected argument 'future-incompatibilities' found + + + + Usage: cargo[EXE] help [OPTIONS] [COMMAND] + + + + For more information, try '--help'. + + + + + + diff --git a/tests/testsuite/cargo_help/nested_cmd/stdout.term.txt b/tests/testsuite/cargo_help/nested_cmd/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/nested_cmd_dash_joined/mod.rs b/tests/testsuite/cargo_help/nested_cmd_dash_joined/mod.rs new file mode 100644 index 00000000000..88a8757b4f6 --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd_dash_joined/mod.rs @@ -0,0 +1,14 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("report-future-incompatibilities") + .assert() + .code(101) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/nested_cmd_dash_joined/stderr.term.svg b/tests/testsuite/cargo_help/nested_cmd_dash_joined/stderr.term.svg new file mode 100644 index 00000000000..f9bcdfb420e --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd_dash_joined/stderr.term.svg @@ -0,0 +1,33 @@ + + + + + + + error: no such command: `report-future-incompatibilities` + + + + help: view all installed commands with `cargo --list` + + help: find a package to install `report-future-incompatibilities` with `cargo search cargo-report-future-incompatibilities` + + + + + + diff --git a/tests/testsuite/cargo_help/nested_cmd_dash_joined/stdout.term.txt b/tests/testsuite/cargo_help/nested_cmd_dash_joined/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/nested_cmd_suggestion/mod.rs b/tests/testsuite/cargo_help/nested_cmd_suggestion/mod.rs new file mode 100644 index 00000000000..e01c165e46e --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd_suggestion/mod.rs @@ -0,0 +1,14 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("report-future-incomp") + .assert() + .code(101) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/nested_cmd_suggestion/stderr.term.svg b/tests/testsuite/cargo_help/nested_cmd_suggestion/stderr.term.svg new file mode 100644 index 00000000000..8bc92080948 --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd_suggestion/stderr.term.svg @@ -0,0 +1,33 @@ + + + + + + + error: no such command: `report-future-incomp` + + + + help: view all installed commands with `cargo --list` + + help: find a package to install `report-future-incomp` with `cargo search cargo-report-future-incomp` + + + + + + diff --git a/tests/testsuite/cargo_help/nested_cmd_suggestion/stdout.term.txt b/tests/testsuite/cargo_help/nested_cmd_suggestion/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/mod.rs b/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/mod.rs new file mode 100644 index 00000000000..bbf17ce63e8 --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/mod.rs @@ -0,0 +1,16 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("report") + .arg("future-incompatibilities") + .arg("--id") + .assert() + .code(1) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/stderr.term.svg b/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/stderr.term.svg new file mode 100644 index 00000000000..cce37f84ba7 --- /dev/null +++ b/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/stderr.term.svg @@ -0,0 +1,39 @@ + + + + + + + error: unexpected argument 'future-incompatibilities' found + + + + Usage: cargo[EXE] help [OPTIONS] [COMMAND] + + + + For more information, try '--help'. + + + + + + diff --git a/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/stdout.term.txt b/tests/testsuite/cargo_help/nested_cmd_with_extra_flags/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/nested_subcommand_suggestion/mod.rs b/tests/testsuite/cargo_help/nested_subcommand_suggestion/mod.rs new file mode 100644 index 00000000000..1e806bb120e --- /dev/null +++ b/tests/testsuite/cargo_help/nested_subcommand_suggestion/mod.rs @@ -0,0 +1,15 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + // Valid parent command `report`, but invalid subcommand `foo` + snapbox::cmd::Command::cargo_ui() + .arg("help") + .arg("report") + .arg("foo") + .assert() + .code(1) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/nested_subcommand_suggestion/stderr.term.svg b/tests/testsuite/cargo_help/nested_subcommand_suggestion/stderr.term.svg new file mode 100644 index 00000000000..798862e31e2 --- /dev/null +++ b/tests/testsuite/cargo_help/nested_subcommand_suggestion/stderr.term.svg @@ -0,0 +1,39 @@ + + + + + + + error: unexpected argument 'foo' found + + + + Usage: cargo[EXE] help [OPTIONS] [COMMAND] + + + + For more information, try '--help'. + + + + + + diff --git a/tests/testsuite/cargo_help/nested_subcommand_suggestion/stdout.term.txt b/tests/testsuite/cargo_help/nested_subcommand_suggestion/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/single_alias/mod.rs b/tests/testsuite/cargo_help/single_alias/mod.rs new file mode 100644 index 00000000000..b19a8263306 --- /dev/null +++ b/tests/testsuite/cargo_help/single_alias/mod.rs @@ -0,0 +1,14 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("rm") + .assert() + .success() + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/single_alias/stderr.term.svg b/tests/testsuite/cargo_help/single_alias/stderr.term.svg new file mode 100644 index 00000000000..824d5a945cf --- /dev/null +++ b/tests/testsuite/cargo_help/single_alias/stderr.term.svg @@ -0,0 +1,21 @@ + + + + + + + + + diff --git a/tests/testsuite/cargo_help/single_alias/stdout.term.txt b/tests/testsuite/cargo_help/single_alias/stdout.term.txt new file mode 100644 index 00000000000..cd889c9b775 --- /dev/null +++ b/tests/testsuite/cargo_help/single_alias/stdout.term.txt @@ -0,0 +1,161 @@ +CARGO-REMOVE(1) + +NAME + cargo-remove — Remove dependencies from a Cargo.toml manifest file + +SYNOPSIS + cargo remove [options] dependency… + +DESCRIPTION + Remove one or more dependencies from a Cargo.toml manifest. + +OPTIONS + Section options + --dev + Remove as a development dependency + . + + --build + Remove as a build dependency + . + + --target target + Remove as a dependency to the given target platform + . + + To avoid unexpected shell expansions, you may use quotes around each + target, e.g., --target 'cfg(unix)'. + + Miscellaneous Options + --dry-run + Don’t actually write to the manifest. + + 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 + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --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. + + Package Selection + -p spec…, --package spec… + Package to remove from. + + 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. Remove regex as a dependency + + cargo remove regex + + 2. Remove trybuild as a dev-dependency + + cargo remove --dev trybuild + + 3. Remove nom from the wasm32-unknown-unknown dependencies table + + cargo remove --target wasm32-unknown-unknown nom + +SEE ALSO + cargo(1), cargo-add(1) + diff --git a/tests/testsuite/cargo_help/single_cmd/mod.rs b/tests/testsuite/cargo_help/single_cmd/mod.rs new file mode 100644 index 00000000000..37ac12ed01f --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd/mod.rs @@ -0,0 +1,14 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("build") + .assert() + .success() + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/single_cmd/stderr.term.svg b/tests/testsuite/cargo_help/single_cmd/stderr.term.svg new file mode 100644 index 00000000000..824d5a945cf --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd/stderr.term.svg @@ -0,0 +1,21 @@ + + + + + + + + + diff --git a/tests/testsuite/cargo_help/single_cmd/stdout.term.txt b/tests/testsuite/cargo_help/single_cmd/stdout.term.txt new file mode 100644 index 00000000000..027ddf2c585 --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd/stdout.term.txt @@ -0,0 +1,384 @@ +CARGO-BUILD(1) + +NAME + cargo-build — Compile the current package + +SYNOPSIS + cargo build [options] + +DESCRIPTION + Compile local packages and all of their dependencies. + +OPTIONS + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Build only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Build all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo build will build all + binary and library targets of the selected packages. Binaries are + skipped if they have required-features that are missing. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to build. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_ environment variable + + is set when the integration test is built and run so that it can use the + env macro or the var + function to locate the + executable. + + Passing target selection flags will build only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Build the package’s library. + + --bin name… + Build the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Build all binary targets. + + --example name… + Build the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Build all example targets. + + --test name… + Build the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Build all targets that have the test = true manifest flag set. By + default this includes the library and binaries built as unittests, + and integration tests. Be aware that this will also build any + required dependencies, so the lib target may be built twice (once as + a unittest, and once as a dependency for binaries, integration + tests, etc.). Targets may be enabled or disabled by setting the test + flag in the manifest settings for the target. + + --bench name… + Build the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Build all targets that have the bench = true manifest flag set. By + default this includes the library and binaries built as benchmarks, + and bench targets. Be aware that this will also build any required + dependencies, so the lib target may be built twice (once as a + benchmark, and once as a dependency for binaries, benchmarks, etc.). + Targets may be enabled or disabled by setting the bench flag in the + manifest settings for the target. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Build for the specified target architecture. Flag may be specified + multiple times. The default is the host architecture. The general + format of the triple is ---. + + Possible values: + + o Any supported target in rustc --print target-list. + + o "host-tuple", which will internally be substituted by the + host’s target. This can be particularly useful if you’re + cross-compiling some crates, and don’t want to specify your + host’s machine as a target (for instance, an xtask in a shared + project that may be worked on by many hosts). + + o A path to a custom target specification. See Custom Target Lookup + Path + + for more information. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + -r, --release + Build optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Build with the given profile. See the reference + for more + details on profiles. + + --timings + Output information how long each compilation takes, and track + concurrency information over time. + + A file cargo-timing.html will be written to the target/cargo-timings + directory at the end of the build. An additional report with a + timestamp in its filename is also written if you want to look at a + previous run. These reports are suitable for human consumption only, + and do not provide machine-readable timing data. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + . Defaults to + target in the root of the workspace. + + --artifact-dir directory + Copy final artifacts to this directory. + + This option is unstable and available only on the nightly channel + and + requires the -Z unstable-options flag to enable. See + for more + information. + + 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 + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --ignore-rust-version + Ignore rust-version specification in packages. + + --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. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + If a string default is provided, it sets the value back to defaults. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + + For example if the current package depends on dependencies fails and + works, one of which fails to build, cargo build -j1 may or may not + build the one that succeeds (depending on which one of the two + builds Cargo picked to run first), whereas cargo build -j1 + --keep-going would definitely run both builds, even if the one run + first fails. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +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. Build the local package and all of its dependencies: + + cargo build + + 2. Build with optimizations: + + cargo build --release + +SEE ALSO + cargo(1), cargo-rustc(1) + diff --git a/tests/testsuite/cargo_help/single_cmd_space_joined/mod.rs b/tests/testsuite/cargo_help/single_cmd_space_joined/mod.rs new file mode 100644 index 00000000000..16c03e5709f --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd_space_joined/mod.rs @@ -0,0 +1,16 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + // Should be `generate-lockfile` but typed wrong as two commands. + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("generate") + .arg("lockfile") + .assert() + .code(1) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/single_cmd_space_joined/stderr.term.svg b/tests/testsuite/cargo_help/single_cmd_space_joined/stderr.term.svg new file mode 100644 index 00000000000..8d09dbc9e42 --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd_space_joined/stderr.term.svg @@ -0,0 +1,39 @@ + + + + + + + error: unexpected argument 'lockfile' found + + + + Usage: cargo[EXE] help [OPTIONS] [COMMAND] + + + + For more information, try '--help'. + + + + + + diff --git a/tests/testsuite/cargo_help/single_cmd_space_joined/stdout.term.txt b/tests/testsuite/cargo_help/single_cmd_space_joined/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/single_cmd_suggestion/mod.rs b/tests/testsuite/cargo_help/single_cmd_suggestion/mod.rs new file mode 100644 index 00000000000..d4e031376dc --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd_suggestion/mod.rs @@ -0,0 +1,14 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("built") + .assert() + .code(101) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/single_cmd_suggestion/stderr.term.svg b/tests/testsuite/cargo_help/single_cmd_suggestion/stderr.term.svg new file mode 100644 index 00000000000..25101261ecd --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd_suggestion/stderr.term.svg @@ -0,0 +1,37 @@ + + + + + + + error: no such command: `built` + + + + help: a command with a similar name exists: `build` + + + + help: view all installed commands with `cargo --list` + + help: find a package to install `built` with `cargo search cargo-built` + + + + + + diff --git a/tests/testsuite/cargo_help/single_cmd_suggestion/stdout.term.txt b/tests/testsuite/cargo_help/single_cmd_suggestion/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/testsuite/cargo_help/single_cmd_with_extra_flags/mod.rs b/tests/testsuite/cargo_help/single_cmd_with_extra_flags/mod.rs new file mode 100644 index 00000000000..8a983e3330f --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd_with_extra_flags/mod.rs @@ -0,0 +1,15 @@ +use crate::prelude::*; +use cargo_test_support::file; + +#[cargo_test] +fn case() { + snapbox::cmd::Command::cargo_ui() + .env("__CARGO_TEST_FORCE_HELP_TXT", "1") + .arg("help") + .arg("build") + .arg("--release") + .assert() + .code(1) + .stdout_eq(file!["stdout.term.txt"]) + .stderr_eq(file!["stderr.term.svg"]); +} diff --git a/tests/testsuite/cargo_help/single_cmd_with_extra_flags/stderr.term.svg b/tests/testsuite/cargo_help/single_cmd_with_extra_flags/stderr.term.svg new file mode 100644 index 00000000000..05634befedd --- /dev/null +++ b/tests/testsuite/cargo_help/single_cmd_with_extra_flags/stderr.term.svg @@ -0,0 +1,43 @@ + + + + + + + error: unexpected argument '--release' found + + + + tip: to pass '--release' as a value, use '-- --release' + + + + Usage: cargo[EXE] help <COMMAND> + + + + For more information, try '--help'. + + + + + + diff --git a/tests/testsuite/cargo_help/single_cmd_with_extra_flags/stdout.term.txt b/tests/testsuite/cargo_help/single_cmd_with_extra_flags/stdout.term.txt new file mode 100644 index 00000000000..e69de29bb2d