Skip to content

Commit

Permalink
Auto merge of #12157 - kornelski:binargs, r=weihanglo
Browse files Browse the repository at this point in the history
Tweak build help to clarify role of --bin

From [user feedback](https://internals.rust-lang.org/t/pre-issue-feature-request-give-me-the-option-to-not-build-a-target/18852/5) the `--bin`'s description "Build only the specified binary" could be understood as "Don't build lib" rather than "Build this bin (with lib) and not other bins".

I don't know if a better wording explaining subtelty of lib+bin crates would fit in the small space of CLI help. However, reordering the args to show `--bin` after `--bins` rather than after `--lib` gives it a more accurate context. So I've merely put the `--bin` (and test/bench/example) after their plural counterpart.

I've also noticed an issue with clap [inserting global args between subcommand's args](clap-rs/clap#4920), and `--locked` definitely doesn't belong right between the two bin args. I've added a workaround for that issue. The workaround is otherwise harmless, and shouldn't cause problems if clap decides to update sort order of subcommands.

Changes this:

```text
      --lib                     Build only this package's library
      --bin [<NAME>]            Build only the specified binary
      --locked                  Require Cargo.lock is up to date
      --bins                    Build all binaries
      --offline                 Run without accessing the network
      --config <KEY=VALUE>      Override a configuration value
      --example [<NAME>]        Build only the specified example
      --examples                Build all examples
  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
      --test [<NAME>]           Build only the specified test target
      --tests                   Build all tests
      --bench [<NAME>]          Build only the specified bench target
      --benches                 Build all benches
```

to this:

```text
      --lib                     Build only this package's library
      --bins                    Build all binaries
      --bin [<NAME>]            Build only the specified binary
      --examples                Build all examples
      --example [<NAME>]        Build only the specified example
      --tests                   Build all tests
      --test [<NAME>]           Build only the specified test target
      --benches                 Build all benches
      --bench [<NAME>]          Build only the specified bench target
[…]
      --locked                  Require Cargo.lock is up to date
      --offline                 Run without accessing the network
      --config <KEY=VALUE>      Override a configuration value
  -Z <FLAG>                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
```
  • Loading branch information
bors committed May 20, 2023
2 parents 2015080 + 75a1dd0 commit a6c0d43
Show file tree
Hide file tree
Showing 2 changed files with 7 additions and 4 deletions.
3 changes: 3 additions & 0 deletions src/bin/cargo/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -440,6 +440,9 @@ pub fn cli() -> Command {
"cargo [OPTIONS] [COMMAND]"
};
Command::new("cargo")
// Subcommands all count their args' display order independently (from 0),
// which makes their args interspersed with global args. This puts global args last.
.next_display_order(1000)
.allow_external_subcommands(true)
// Doesn't mix well with our list of common cargo commands. See clap-rs/clap#3108 for
// opening clap up to allow us to style our help template
Expand Down
8 changes: 4 additions & 4 deletions src/cargo/util/command_prelude.rs
Original file line number Diff line number Diff line change
Expand Up @@ -91,10 +91,10 @@ pub trait CommandExt: Sized {
all: &'static str,
) -> Self {
self.arg_targets_lib_bin_example(lib, bin, bins, example, examples)
._arg(optional_multi_opt("test", "NAME", test))
._arg(flag("tests", tests))
._arg(optional_multi_opt("bench", "NAME", bench))
._arg(optional_multi_opt("test", "NAME", test))
._arg(flag("benches", benches))
._arg(optional_multi_opt("bench", "NAME", bench))
._arg(flag("all-targets", all))
}

Expand All @@ -107,10 +107,10 @@ pub trait CommandExt: Sized {
examples: &'static str,
) -> Self {
self._arg(flag("lib", lib))
._arg(optional_multi_opt("bin", "NAME", bin))
._arg(flag("bins", bins))
._arg(optional_multi_opt("example", "NAME", example))
._arg(optional_multi_opt("bin", "NAME", bin))
._arg(flag("examples", examples))
._arg(optional_multi_opt("example", "NAME", example))
}

fn arg_targets_bins_examples(
Expand Down

0 comments on commit a6c0d43

Please sign in to comment.