Display titles of option groups in swift build --help

[MaxDesiatov]

Recent versions of ArgumentParser support visual grouping of options specified with @OptionGroup property wrapper when title argument is provided. Let's do it for swift build to make its --help output cleaner.

Help output before:

OVERVIEW: Build sources into binary products

SEE ALSO: swift run, swift package, swift test

USAGE: swift build <options>

OPTIONS:
  --package-path <package-path>
                          Specify the package path to operate on (default current directory). This changes the
                          working directory before any other operation
<multiple ungrouped options skipped>

Help output after:

OVERVIEW: Build sources into binary products

SEE ALSO: swift run, swift package, swift test

USAGE: swift build <options>

GLOBAL OPTIONS:
  --package-path <package-path>
                          Specify the package path to operate on (default current directory). This changes the
                          working directory before any other operation
<multiple global options skipped>

BUILD OPTIONS:
  --build-tests           Build both source and test targets
  --show-bin-path         Print the binary output path
  --print-manifest-job-graph
                          Write the command graph for the build manifest as a graphviz file
  --target <target>       Build the specified target
  --product <product>     Build the specified product

OPTIONS:
  --version               Show the version.
  -h, -help, --help       Show help information.

[MaxDesiatov]

@swift-ci smoke test

[neonichu]

Hm, not sure this adds a ton of value? The grouping into "global" and "build" options is fairly arbitrary and based on SwiftPM command structure and not on any real logical reasoning. I think what could be nice is breaking up those groups into actual logical units and titling those. Thanks for mentioning the feature, though!

[MaxDesiatov]

I've tried breaking up GlobalOptions into logical subgroups as you describe, but that's blocked by apple/swift-argument-parser#558

[tomerd]

cc @bitjammer for input on desired UX

[bitjammer]

Some specific comments on what I can see based on the description:

• The idea of cascading, global options should be reconsidered in the future. Not something to solve here, however:
• Instead of calling the group "GLOBAL", I'd recommend something like "GENERAL". Although subcommands are good, users shouldn't have to contend with the idea of command "hierarchy" in swiftpm tools with respect to the options.
• I probably wouldn't consider --show-bin-path a build option. It's really almost a kind of subcommand or mode change, and a general one. Same with --print-manifest-job-graph.

Personally, I'd like to sit down and make more fundamental changes to the usage of the swiftpm tools. That includes cleaning up how these "global" options cascade down to other commands, or what is or isn't a subcommand, such as swift-package-registry and swift-package-collection. I don't have very strong feelings about this change one way or the other in light of that, but I think I agree with Boris here overall.

One thought here from my work on the command line interfaces so far is that some options are much more common than others. Consider sorting options by their apparent frequency within groups as possible. Another thought: if we really must draw boxes around options, they should be task-oriented as much as possible. If there is only one task achievable by the tool, the groupings become somewhat arbitrary as Boris said. I don't have a better answer for this at this time as I haven't had the time to review all of the options again in detail. I hope that helps!