WIP: fix(cli): Make --help easier to browse

epage · epage · commit 81c785c21df1 · 2023-03-28T05:47:16.000-05:00
This mirrors some of the categories from `cargo help` (the man pages).
diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs
@@ -23,6 +23,13 @@ pub use clap::{value_parser, Arg, ArgAction, ArgMatches};
 
 pub use clap::Command;
 
+pub mod heading {
+    pub const PACKAGE_SELECTION: &str = "Package Selection";
+    pub const TARGET_SELECTION: &str = "Target Selection";
+    pub const FEATURE_SELECTION: &str = "Feature Selection";
+    pub const COMPILATION_OPTIONS: &str = "Compilation Options";
+}
+
 pub trait CommandExt: Sized {
     fn _arg(self, arg: Arg) -> Self;
 
@@ -34,8 +41,10 @@ pub trait CommandExt: Sized {
         all: &'static str,
         exclude: &'static str,
     ) -> Self {
-        self.arg_package_spec_no_all(package, all, exclude)
-            ._arg(flag("all", "Alias for --workspace (deprecated)"))
+        self.arg_package_spec_no_all(package, all, exclude)._arg(
+            flag("all", "Alias for --workspace (deprecated)")
+                .help_heading(heading::PACKAGE_SELECTION),
+        )
     }
 
     /// Variant of arg_package_spec that does not include the `--all` flag
@@ -48,19 +57,24 @@ pub trait CommandExt: Sized {
         exclude: &'static str,
     ) -> Self {
         self.arg_package_spec_simple(package)
-            ._arg(flag("workspace", all))
-            ._arg(multi_opt("exclude", "SPEC", exclude))
+            ._arg(flag("workspace", all).help_heading(heading::PACKAGE_SELECTION))
+            ._arg(multi_opt("exclude", "SPEC", exclude).help_heading(heading::PACKAGE_SELECTION))
     }
 
     fn arg_package_spec_simple(self, package: &'static str) -> Self {
-        self._arg(optional_multi_opt("package", "SPEC", package).short('p'))
+        self._arg(
+            optional_multi_opt("package", "SPEC", package)
+                .short('p')
+                .help_heading(heading::PACKAGE_SELECTION),
+        )
     }
 
     fn arg_package(self, package: &'static str) -> Self {
         self._arg(
             optional_opt("package", package)
                 .short('p')
-                .value_name("SPEC"),
+                .value_name("SPEC")
+                .help_heading(heading::PACKAGE_SELECTION),
         )
     }
 
@@ -91,11 +105,13 @@ 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(flag("benches", benches))
-            ._arg(flag("all-targets", all))
+            ._arg(optional_multi_opt("test", "NAME", test).help_heading(heading::TARGET_SELECTION))
+            ._arg(flag("tests", tests).help_heading(heading::TARGET_SELECTION))
+            ._arg(
+                optional_multi_opt("bench", "NAME", bench).help_heading(heading::TARGET_SELECTION),
+            )
+            ._arg(flag("benches", benches).help_heading(heading::TARGET_SELECTION))
+            ._arg(flag("all-targets", all).help_heading(heading::TARGET_SELECTION))
     }
 
     fn arg_targets_lib_bin_example(
@@ -106,11 +122,14 @@ pub trait CommandExt: Sized {
         example: &'static str,
         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(flag("examples", examples))
+        self._arg(flag("lib", lib).help_heading(heading::TARGET_SELECTION))
+            ._arg(optional_multi_opt("bin", "NAME", bin).help_heading(heading::TARGET_SELECTION))
+            ._arg(flag("bins", bins).help_heading(heading::TARGET_SELECTION))
+            ._arg(
+                optional_multi_opt("example", "NAME", example)
+                    .help_heading(heading::TARGET_SELECTION),
+            )
+            ._arg(flag("examples", examples).help_heading(heading::TARGET_SELECTION))
     }
 
     fn arg_targets_bins_examples(
@@ -120,15 +139,21 @@ pub trait CommandExt: Sized {
         example: &'static str,
         examples: &'static str,
     ) -> Self {
-        self._arg(optional_multi_opt("bin", "NAME", bin))
-            ._arg(flag("bins", bins))
-            ._arg(optional_multi_opt("example", "NAME", example))
-            ._arg(flag("examples", examples))
+        self._arg(optional_multi_opt("bin", "NAME", bin).help_heading(heading::TARGET_SELECTION))
+            ._arg(flag("bins", bins).help_heading(heading::TARGET_SELECTION))
+            ._arg(
+                optional_multi_opt("example", "NAME", example)
+                    .help_heading(heading::TARGET_SELECTION),
+            )
+            ._arg(flag("examples", examples).help_heading(heading::TARGET_SELECTION))
     }
 
     fn arg_targets_bin_example(self, bin: &'static str, example: &'static str) -> Self {
-        self._arg(optional_multi_opt("bin", "NAME", bin))
-            ._arg(optional_multi_opt("example", "NAME", example))
+        self._arg(optional_multi_opt("bin", "NAME", bin).help_heading(heading::TARGET_SELECTION))
+            ._arg(
+                optional_multi_opt("example", "NAME", example)
+                    .help_heading(heading::TARGET_SELECTION),
+            )
     }
 
     fn arg_features(self) -> Self {
@@ -138,34 +163,51 @@ pub trait CommandExt: Sized {
                 "FEATURES",
                 "Space or comma separated list of features to activate",
             )
-            .short('F'),
+            .short('F')
+            .help_heading(heading::FEATURE_SELECTION),
+        )
+        ._arg(
+            flag("all-features", "Activate all available features")
+                .help_heading(heading::FEATURE_SELECTION),
+        )
+        ._arg(
+            flag(
+                "no-default-features",
+                "Do not activate the `default` feature",
+            )
+            .help_heading(heading::FEATURE_SELECTION),
         )
-        ._arg(flag("all-features", "Activate all available features"))
-        ._arg(flag(
-            "no-default-features",
-            "Do not activate the `default` feature",
-        ))
     }
 
     fn arg_release(self, release: &'static str) -> Self {
-        self._arg(flag("release", release).short('r'))
+        self._arg(
+            flag("release", release)
+                .short('r')
+                .help_heading(heading::COMPILATION_OPTIONS),
+        )
     }
 
     fn arg_profile(self, profile: &'static str) -> Self {
-        self._arg(opt("profile", profile).value_name("PROFILE-NAME"))
+        self._arg(
+            opt("profile", profile)
+                .value_name("PROFILE-NAME")
+                .help_heading(heading::COMPILATION_OPTIONS),
+        )
     }
 
     fn arg_doc(self, doc: &'static str) -> Self {
         self._arg(flag("doc", doc))
     }
 
     fn arg_target_triple(self, target: &'static str) -> Self {
-        self._arg(multi_opt("target", "TRIPLE", target))
+        self._arg(multi_opt("target", "TRIPLE", target).help_heading(heading::COMPILATION_OPTIONS))
     }
 
     fn arg_target_dir(self) -> Self {
         self._arg(
-            opt("target-dir", "Directory for all generated artifacts").value_name("DIRECTORY"),
+            opt("target-dir", "Directory for all generated artifacts")
+                .value_name("DIRECTORY")
+                .help_heading(heading::COMPILATION_OPTIONS),
         )
     }
 
diff --git a/tests/testsuite/cargo_build/help/stdout.log b/tests/testsuite/cargo_build/help/stdout.log
@@ -4,36 +4,15 @@ Usage: cargo build [OPTIONS]
 
 Options:
   -q, --quiet                   Do not print cargo log messages
-  -p, --package [<SPEC>]        Package to build (see `cargo help pkgid`)
-      --workspace               Build all packages in the workspace
-      --exclude <SPEC>          Exclude packages from the build
   -v, --verbose...              Use verbose output (-vv very verbose/build.rs output)
-      --all                     Alias for --workspace (deprecated)
       --color <WHEN>            Coloring: auto, always, never
   -j, --jobs <N>                Number of parallel jobs, defaults to # of CPUs
       --keep-going              Do not abort the build as soon as there is an error (unstable)
       --frozen                  Require Cargo.lock and cache are up to date
-      --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
-      --all-targets             Build all targets
-  -r, --release                 Build artifacts in release mode, with optimizations
-      --profile <PROFILE-NAME>  Build artifacts with the specified profile
-  -F, --features <FEATURES>     Space or comma separated list of features to activate
-      --all-features            Activate all available features
-      --no-default-features     Do not activate the `default` feature
-      --target <TRIPLE>         Build for the target triple
-      --target-dir <DIRECTORY>  Directory for all generated artifacts
       --out-dir <PATH>          Copy final artifacts to this directory (unstable)
       --manifest-path <PATH>    Path to Cargo.toml
       --ignore-rust-version     Ignore `rust-version` specification in packages
@@ -44,4 +23,33 @@ Options:
       --timings[=<FMTS>]        Timing output formats (unstable) (comma separated): html, json
   -h, --help                    Print help
 
+Package Selection:
+  -p, --package [<SPEC>]  Package to build (see `cargo help pkgid`)
+      --workspace         Build all packages in the workspace
+      --exclude <SPEC>    Exclude packages from the build
+      --all               Alias for --workspace (deprecated)
+
+Target Selection:
+      --lib               Build only this package's library
+      --bin [<NAME>]      Build only the specified binary
+      --bins              Build all binaries
+      --example [<NAME>]  Build only the specified example
+      --examples          Build all examples
+      --test [<NAME>]     Build only the specified test target
+      --tests             Build all tests
+      --bench [<NAME>]    Build only the specified bench target
+      --benches           Build all benches
+      --all-targets       Build all targets
+
+Compilation Options:
+  -r, --release                 Build artifacts in release mode, with optimizations
+      --profile <PROFILE-NAME>  Build artifacts with the specified profile
+      --target <TRIPLE>         Build for the target triple
+      --target-dir <DIRECTORY>  Directory for all generated artifacts
+
+Feature Selection:
+  -F, --features <FEATURES>  Space or comma separated list of features to activate
+      --all-features         Activate all available features
+      --no-default-features  Do not activate the `default` feature
+
 Run `cargo help build` for more detailed information.
