Changing how build-script's help text is organized

I was talking to @etcwilde earlier today, and one of the problems he pointed out was the build-script's help text can be a bit overwhelming.

At this point, I've gotten used to it, so it's a bit hard for me to judge, but I figured, if this is a problem for some folks, we should consider changing it. In my discussion with Evan, the following ideas came up:

  1. We can have common options be shown through --help and uncommon options shown through (strawman) --help-hidden.
  2. Maybe we can group the options in a more useful way.
  3. Maybe providing more examples helps?

There's also the separate issue where certain flags like --reconfigure are opaque to people in what they do (this includes me; I only have a fuzzy understanding of what it does).

Do people have thoughts on this topic? Anyone have objections to separating out options into commonly used options and less commonly used options? Certainly, it's possible that one person's "wait this option exists??" can be another person's "I use that all the time!", especially if the two people work on different parts of the project, but I think for many flags, it is relatively clear if it is used frequently or not...

8 Likes

+1 to shrinking the default help message! It's both intimidating if you aren't used to it, and difficult to navigate if you are looking for something specific.

Maybe --help-verbose or --help-all? These things are not hidden because of any intrinsic reason you shouldn't use them (unlike, e.g. clang --help-hidden).

  1. Maybe providing more examples helps?

I would say fewer examples and less prose overall (e.g. the first thing you see if you print the message to a console, since it's at the bottom, is a "philosophy" section). For examples, I would expect to see a small number of highly relevant ones using only the "full" names of options so that they're easy to understand. We could then suggest somewhere else to find more extensive documentation.

build-script --release-debuginfo
build-script --release-debuginfo --xcode
build-script --preset=buildbot_incremental,tools=RA,stdlib=RA

For myself, I would like something with more progressive disclosure. For a fully-fledged installable tool this might be the distinction between build-script --help and man build-script. Since we probably don't expect people to install a man page for it, maybe we can split some of it up and have --help-verbose or --help-examples. Alternatively, we could move the more extensive documentation to something we link to on the web or in the docs directory.

4 Likes

I agree with less prose. Something that is easily grep-able. If a tool’s help-text is longer than a page, I’ll run it through grep a few times. If I find what I’m looking for, I use it, if I don’t then I assume (maybe incorrectly) that it can’t do it.

Filed https://bugs.swift.org/browse/SR-14395 to track this work.

2 Likes
Terms of Service

Privacy Policy

Cookie Policy