Skip to content

Commit 830931e

Browse files
epageepage
committed
WIP: fix(cli): Make --help easier to browse
This mirrors some of the categories from `cargo help` (the man pages).
1 parent e2fbcd9 commit 830931e

File tree

22 files changed

+527
-372
lines changed

22 files changed

+527
-372
lines changed

‎src/cargo/util/command_prelude.rs‎

Lines changed: 74 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@ pub use clap::Command;
2626

2727
use super::config::JobsConfig;
2828

29+
pub mod heading {
30+
pub const PACKAGE_SELECTION: &str = "Package Selection";
31+
pub const TARGET_SELECTION: &str = "Target Selection";
32+
pub const FEATURE_SELECTION: &str = "Feature Selection";
33+
pub const COMPILATION_OPTIONS: &str = "Compilation Options";
34+
}
35+
2936
pub trait CommandExt: Sized {
3037
fn _arg(self, arg: Arg) -> Self;
3138

@@ -37,8 +44,10 @@ pub trait CommandExt: Sized {
3744
all: &'static str,
3845
exclude: &'static str,
3946
) -> Self {
40-
self.arg_package_spec_no_all(package, all, exclude)
41-
._arg(flag("all", "Alias for --workspace (deprecated)"))
47+
self.arg_package_spec_no_all(package, all, exclude)._arg(
48+
flag("all", "Alias for --workspace (deprecated)")
49+
.help_heading(heading::PACKAGE_SELECTION),
50+
)
4251
}
4352

4453
/// Variant of arg_package_spec that does not include the `--all` flag
@@ -51,19 +60,24 @@ pub trait CommandExt: Sized {
5160
exclude: &'static str,
5261
) -> Self {
5362
self.arg_package_spec_simple(package)
54-
._arg(flag("workspace", all))
55-
._arg(multi_opt("exclude", "SPEC", exclude))
63+
._arg(flag("workspace", all).help_heading(heading::PACKAGE_SELECTION))
64+
._arg(multi_opt("exclude", "SPEC", exclude).help_heading(heading::PACKAGE_SELECTION))
5665
}
5766

5867
fn arg_package_spec_simple(self, package: &'static str) -> Self {
59-
self._arg(optional_multi_opt("package", "SPEC", package).short('p'))
68+
self._arg(
69+
optional_multi_opt("package", "SPEC", package)
70+
.short('p')
71+
.help_heading(heading::PACKAGE_SELECTION),
72+
)
6073
}
6174

6275
fn arg_package(self, package: &'static str) -> Self {
6376
self._arg(
6477
optional_opt("package", package)
6578
.short('p')
66-
.value_name("SPEC"),
79+
.value_name("SPEC")
80+
.help_heading(heading::PACKAGE_SELECTION),
6781
)
6882
}
6983

@@ -94,11 +108,13 @@ pub trait CommandExt: Sized {
94108
all: &'static str,
95109
) -> Self {
96110
self.arg_targets_lib_bin_example(lib, bin, bins, example, examples)
97-
._arg(flag("tests", tests))
98-
._arg(optional_multi_opt("test", "NAME", test))
99-
._arg(flag("benches", benches))
100-
._arg(optional_multi_opt("bench", "NAME", bench))
101-
._arg(flag("all-targets", all))
111+
._arg(flag("tests", tests).help_heading(heading::TARGET_SELECTION))
112+
._arg(optional_multi_opt("test", "NAME", test).help_heading(heading::TARGET_SELECTION))
113+
._arg(flag("benches", benches).help_heading(heading::TARGET_SELECTION))
114+
._arg(
115+
optional_multi_opt("bench", "NAME", bench).help_heading(heading::TARGET_SELECTION),
116+
)
117+
._arg(flag("all-targets", all).help_heading(heading::TARGET_SELECTION))
102118
}
103119

104120
fn arg_targets_lib_bin_example(
@@ -109,11 +125,14 @@ pub trait CommandExt: Sized {
109125
example: &'static str,
110126
examples: &'static str,
111127
) -> Self {
112-
self._arg(flag("lib", lib))
113-
._arg(flag("bins", bins))
114-
._arg(optional_multi_opt("bin", "NAME", bin))
115-
._arg(flag("examples", examples))
116-
._arg(optional_multi_opt("example", "NAME", example))
128+
self._arg(flag("lib", lib).help_heading(heading::TARGET_SELECTION))
129+
._arg(flag("bins", bins).help_heading(heading::TARGET_SELECTION))
130+
._arg(optional_multi_opt("bin", "NAME", bin).help_heading(heading::TARGET_SELECTION))
131+
._arg(flag("examples", examples).help_heading(heading::TARGET_SELECTION))
132+
._arg(
133+
optional_multi_opt("example", "NAME", example)
134+
.help_heading(heading::TARGET_SELECTION),
135+
)
117136
}
118137

119138
fn arg_targets_bins_examples(
@@ -123,15 +142,21 @@ pub trait CommandExt: Sized {
123142
example: &'static str,
124143
examples: &'static str,
125144
) -> Self {
126-
self._arg(optional_multi_opt("bin", "NAME", bin))
127-
._arg(flag("bins", bins))
128-
._arg(optional_multi_opt("example", "NAME", example))
129-
._arg(flag("examples", examples))
145+
self._arg(optional_multi_opt("bin", "NAME", bin).help_heading(heading::TARGET_SELECTION))
146+
._arg(flag("bins", bins).help_heading(heading::TARGET_SELECTION))
147+
._arg(
148+
optional_multi_opt("example", "NAME", example)
149+
.help_heading(heading::TARGET_SELECTION),
150+
)
151+
._arg(flag("examples", examples).help_heading(heading::TARGET_SELECTION))
130152
}
131153

132154
fn arg_targets_bin_example(self, bin: &'static str, example: &'static str) -> Self {
133-
self._arg(optional_multi_opt("bin", "NAME", bin))
134-
._arg(optional_multi_opt("example", "NAME", example))
155+
self._arg(optional_multi_opt("bin", "NAME", bin).help_heading(heading::TARGET_SELECTION))
156+
._arg(
157+
optional_multi_opt("example", "NAME", example)
158+
.help_heading(heading::TARGET_SELECTION),
159+
)
135160
}
136161

137162
fn arg_features(self) -> Self {
@@ -141,34 +166,51 @@ pub trait CommandExt: Sized {
141166
"FEATURES",
142167
"Space or comma separated list of features to activate",
143168
)
144-
.short('F'),
169+
.short('F')
170+
.help_heading(heading::FEATURE_SELECTION),
171+
)
172+
._arg(
173+
flag("all-features", "Activate all available features")
174+
.help_heading(heading::FEATURE_SELECTION),
175+
)
176+
._arg(
177+
flag(
178+
"no-default-features",
179+
"Do not activate the `default` feature",
180+
)
181+
.help_heading(heading::FEATURE_SELECTION),
145182
)
146-
._arg(flag("all-features", "Activate all available features"))
147-
._arg(flag(
148-
"no-default-features",
149-
"Do not activate the `default` feature",
150-
))
151183
}
152184

153185
fn arg_release(self, release: &'static str) -> Self {
154-
self._arg(flag("release", release).short('r'))
186+
self._arg(
187+
flag("release", release)
188+
.short('r')
189+
.help_heading(heading::COMPILATION_OPTIONS),
190+
)
155191
}
156192

157193
fn arg_profile(self, profile: &'static str) -> Self {
158-
self._arg(opt("profile", profile).value_name("PROFILE-NAME"))
194+
self._arg(
195+
opt("profile", profile)
196+
.value_name("PROFILE-NAME")
197+
.help_heading(heading::COMPILATION_OPTIONS),
198+
)
159199
}
160200

161201
fn arg_doc(self, doc: &'static str) -> Self {
162202
self._arg(flag("doc", doc))
163203
}
164204

165205
fn arg_target_triple(self, target: &'static str) -> Self {
166-
self._arg(multi_opt("target", "TRIPLE", target))
206+
self._arg(multi_opt("target", "TRIPLE", target).help_heading(heading::COMPILATION_OPTIONS))
167207
}
168208

169209
fn arg_target_dir(self) -> Self {
170210
self._arg(
171-
opt("target-dir", "Directory for all generated artifacts").value_name("DIRECTORY"),
211+
opt("target-dir", "Directory for all generated artifacts")
212+
.value_name("DIRECTORY")
213+
.help_heading(heading::COMPILATION_OPTIONS),
172214
)
173215
}
174216

‎tests/testsuite/cargo_add/help/stdout.log‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,6 @@ Options:
4545
--manifest-path <PATH>
4646
Path to Cargo.toml
4747

48-
-p, --package [<SPEC>]
49-
Package to modify
50-
5148
-q, --quiet
5249
Do not print cargo log messages
5350

@@ -78,6 +75,10 @@ Options:
7875
-Z <FLAG>
7976
Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
8077

78+
Package Selection:
79+
-p, --package [<SPEC>]
80+
Package to modify
81+
8182
Source:
8283
--path <PATH>
8384
Filesystem path to local crate to add

‎tests/testsuite/cargo_bench/help/stdout.log‎

Lines changed: 44 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -7,44 +7,52 @@ Arguments:
77
[args]... Arguments for the bench binary
88

99
Options:
10-
-q, --quiet Do not print cargo log messages
11-
--lib Benchmark only this package's library
12-
--bins Benchmark all binaries
13-
--bin [<NAME>] Benchmark only the specified binary
14-
--examples Benchmark all examples
15-
--example [<NAME>] Benchmark only the specified example
16-
--tests Benchmark all tests
17-
--test [<NAME>] Benchmark only the specified test target
18-
--benches Benchmark all benches
19-
--bench [<NAME>] Benchmark only the specified bench target
20-
--all-targets Benchmark all targets
21-
--no-run Compile, but don't run benchmarks
22-
-p, --package [<SPEC>] Package to run benchmarks for
23-
--workspace Benchmark all packages in the workspace
24-
--exclude <SPEC> Exclude packages from the benchmark
25-
--all Alias for --workspace (deprecated)
26-
-j, --jobs <N> Number of parallel jobs, defaults to # of CPUs.
27-
--keep-going Do not abort the build as soon as there is an error (unstable)
10+
-q, --quiet Do not print cargo log messages
11+
--no-run Compile, but don't run benchmarks
12+
-j, --jobs <N> Number of parallel jobs, defaults to # of CPUs.
13+
--keep-going Do not abort the build as soon as there is an error (unstable)
14+
--manifest-path <PATH> Path to Cargo.toml
15+
--ignore-rust-version Ignore `rust-version` specification in packages
16+
--message-format <FMT> Error format
17+
--no-fail-fast Run all benchmarks regardless of failure
18+
--unit-graph Output build graph in JSON (unstable)
19+
--timings[=<FMTS>] Timing output formats (unstable) (comma separated): html, json
20+
-h, --help Print help
21+
-v, --verbose... Use verbose output (-vv very verbose/build.rs output)
22+
--color <WHEN> Coloring: auto, always, never
23+
--frozen Require Cargo.lock and cache are up to date
24+
--locked Require Cargo.lock is up to date
25+
--offline Run without accessing the network
26+
--config <KEY=VALUE> Override a configuration value
27+
-Z <FLAG> Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for
28+
details
29+
30+
Target Selection:
31+
--lib Benchmark only this package's library
32+
--bins Benchmark all binaries
33+
--bin [<NAME>] Benchmark only the specified binary
34+
--examples Benchmark all examples
35+
--example [<NAME>] Benchmark only the specified example
36+
--tests Benchmark all tests
37+
--test [<NAME>] Benchmark only the specified test target
38+
--benches Benchmark all benches
39+
--bench [<NAME>] Benchmark only the specified bench target
40+
--all-targets Benchmark all targets
41+
42+
Package Selection:
43+
-p, --package [<SPEC>] Package to run benchmarks for
44+
--workspace Benchmark all packages in the workspace
45+
--exclude <SPEC> Exclude packages from the benchmark
46+
--all Alias for --workspace (deprecated)
47+
48+
Compilation Options:
2849
--profile <PROFILE-NAME> Build artifacts with the specified profile
29-
-F, --features <FEATURES> Space or comma separated list of features to activate
30-
--all-features Activate all available features
31-
--no-default-features Do not activate the `default` feature
3250
--target <TRIPLE> Build for the target triple
3351
--target-dir <DIRECTORY> Directory for all generated artifacts
34-
--manifest-path <PATH> Path to Cargo.toml
35-
--ignore-rust-version Ignore `rust-version` specification in packages
36-
--message-format <FMT> Error format
37-
--no-fail-fast Run all benchmarks regardless of failure
38-
--unit-graph Output build graph in JSON (unstable)
39-
--timings[=<FMTS>] Timing output formats (unstable) (comma separated): html, json
40-
-h, --help Print help
41-
-v, --verbose... Use verbose output (-vv very verbose/build.rs output)
42-
--color <WHEN> Coloring: auto, always, never
43-
--frozen Require Cargo.lock and cache are up to date
44-
--locked Require Cargo.lock is up to date
45-
--offline Run without accessing the network
46-
--config <KEY=VALUE> Override a configuration value
47-
-Z <FLAG> Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for
48-
details
52+
53+
Feature Selection:
54+
-F, --features <FEATURES> Space or comma separated list of features to activate
55+
--all-features Activate all available features
56+
--no-default-features Do not activate the `default` feature
4957

5058
Run `cargo help bench` for more detailed information.

‎tests/testsuite/cargo_build/help/stdout.log‎

Lines changed: 29 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,8 @@ Usage: cargo[EXE] build [OPTIONS]
44

55
Options:
66
-q, --quiet Do not print cargo log messages
7-
-p, --package [<SPEC>] Package to build (see `cargo help pkgid`)
8-
--workspace Build all packages in the workspace
9-
--exclude <SPEC> Exclude packages from the build
10-
--all Alias for --workspace (deprecated)
117
-j, --jobs <N> Number of parallel jobs, defaults to # of CPUs.
128
--keep-going Do not abort the build as soon as there is an error (unstable)
13-
--lib Build only this package's library
14-
--bins Build all binaries
15-
--bin [<NAME>] Build only the specified binary
16-
--examples Build all examples
17-
--example [<NAME>] Build only the specified example
18-
--tests Build all tests
19-
--test [<NAME>] Build only the specified test target
20-
--benches Build all benches
21-
--bench [<NAME>] Build only the specified bench target
22-
--all-targets Build all targets
23-
-r, --release Build artifacts in release mode, with optimizations
24-
--profile <PROFILE-NAME> Build artifacts with the specified profile
25-
-F, --features <FEATURES> Space or comma separated list of features to activate
26-
--all-features Activate all available features
27-
--no-default-features Do not activate the `default` feature
28-
--target <TRIPLE> Build for the target triple
29-
--target-dir <DIRECTORY> Directory for all generated artifacts
309
--out-dir <PATH> Copy final artifacts to this directory (unstable)
3110
--manifest-path <PATH> Path to Cargo.toml
3211
--ignore-rust-version Ignore `rust-version` specification in packages
@@ -45,4 +24,33 @@ Options:
4524
-Z <FLAG> Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for
4625
details
4726

27+
Package Selection:
28+
-p, --package [<SPEC>] Package to build (see `cargo help pkgid`)
29+
--workspace Build all packages in the workspace
30+
--exclude <SPEC> Exclude packages from the build
31+
--all Alias for --workspace (deprecated)
32+
33+
Target Selection:
34+
--lib Build only this package's library
35+
--bins Build all binaries
36+
--bin [<NAME>] Build only the specified binary
37+
--examples Build all examples
38+
--example [<NAME>] Build only the specified example
39+
--tests Build all tests
40+
--test [<NAME>] Build only the specified test target
41+
--benches Build all benches
42+
--bench [<NAME>] Build only the specified bench target
43+
--all-targets Build all targets
44+
45+
Compilation Options:
46+
-r, --release Build artifacts in release mode, with optimizations
47+
--profile <PROFILE-NAME> Build artifacts with the specified profile
48+
--target <TRIPLE> Build for the target triple
49+
--target-dir <DIRECTORY> Directory for all generated artifacts
50+
51+
Feature Selection:
52+
-F, --features <FEATURES> Space or comma separated list of features to activate
53+
--all-features Activate all available features
54+
--no-default-features Do not activate the `default` feature
55+
4856
Run `cargo help build` for more detailed information.

0 commit comments

Comments
 (0)