Tweak build help to clarify role of --bin

[kornelski]

From user feedback 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, 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:

      --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:

      --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

[rustbot]

r? @weihanglo

(rustbot has picked a reviewer for you, use r? to override)

[weihanglo]

This is another data point that #11912 might be useful.

I'll take a deeper look of it tomorrow.

[weihanglo]

Pretty reasonable enhancement. Thank you!

I'd like to know what people's thoughts on this, especially @epage who's the maintainer of clap.

[epage]

Seems like a reasonable change to me

[weihanglo]

Will merge this and move on. We can always reverse the change easily.

@bors r+

[bors]

📌 Commit 75a1dd0 has been approved by weihanglo

It is now in the queue for this repository.

[bors]

⌛ Testing commit 75a1dd0 with merge a6c0d43...

[bors]

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing a6c0d43 to master...