Add categories to --help text (#4421)

The general shape of the --help output is now:



========================
wasm-foo

Does the foo operation
========================

wasm-foo opts:
--------------

  --foo-bar   ..

Tool opts:
----------

..




The options are now in categories, with the more specific ones - most likely to be
wanted by the user - first. I think this makes the list a lot less confusing.

In particular, in wasm-opt all the opt passes are now in their own category.

Also add a script to make it easy to update the help tests.

1 files changed, 19 insertions, 0 deletions

diff --git a/src/tools/wasm-opt.cpp b/src/tools/wasm-opt.cpp
index 2ccf11fa0..c026be21b 100644
--- a/src/tools/wasm-opt.cpp
+++ b/src/tools/wasm-opt.cpp
@@ -91,11 +91,14 @@ int main(int argc, const char* argv[]) {
   std::string outputSourceMapFilename;
   std::string outputSourceMapUrl;
 
+  const std::string WasmOptOption = "wasm-opt options";
+
   OptimizationOptions options("wasm-opt", "Read, write, and optimize files");
   options
     .add("--output",
          "-o",
          "Output file (stdout if not specified)",
+         WasmOptOption,
          Options::Arguments::One,
          [](Options* o, const std::string& argument) {
            o->extra["output"] = argument;
@@ -104,23 +107,27 @@ int main(int argc, const char* argv[]) {
     .add("--emit-text",
          "-S",
          "Emit text instead of binary for the output file",
+         WasmOptOption,
          Options::Arguments::Zero,
          [&](Options* o, const std::string& argument) { emitBinary = false; })
     .add("--converge",
          "-c",
          "Run passes to convergence, continuing while binary size decreases",
+         WasmOptOption,
          Options::Arguments::Zero,
          [&](Options* o, const std::string& arguments) { converge = true; })
     .add(
       "--fuzz-exec-before",
       "-feh",
       "Execute functions before optimization, helping fuzzing find bugs",
+      WasmOptOption,
       Options::Arguments::Zero,
       [&](Options* o, const std::string& arguments) { fuzzExecBefore = true; })
     .add("--fuzz-exec",
          "-fe",
          "Execute functions before and after optimization, helping fuzzing "
          "find bugs",
+         WasmOptOption,
          Options::Arguments::Zero,
          [&](Options* o, const std::string& arguments) {
            fuzzExecBefore = fuzzExecAfter = true;
@@ -130,6 +137,7 @@ int main(int argc, const char* argv[]) {
          "An extra command to run on the output before and after optimizing. "
          "The output is compared between the two, and an error occurs if they "
          "are not equal",
+         WasmOptOption,
          Options::Arguments::One,
          [&](Options* o, const std::string& arguments) {
            extraFuzzCommand = arguments;
@@ -139,11 +147,13 @@ int main(int argc, const char* argv[]) {
       "-ttf",
       "Translate the input into a valid wasm module *somehow*, useful for "
       "fuzzing",
+      WasmOptOption,
       Options::Arguments::Zero,
       [&](Options* o, const std::string& arguments) { translateToFuzz = true; })
     .add("--initial-fuzz",
          "-if",
          "Initial wasm content in translate-to-fuzz (-ttf) mode",
+         WasmOptOption,
          Options::Arguments::One,
          [&initialFuzz](Options* o, const std::string& argument) {
            initialFuzz = argument;
@@ -152,22 +162,26 @@ int main(int argc, const char* argv[]) {
          "-fp",
          "Pick a random set of passes to run, useful for fuzzing. this depends "
          "on translate-to-fuzz (it picks the passes from the input)",
+         WasmOptOption,
          Options::Arguments::Zero,
          [&](Options* o, const std::string& arguments) { fuzzPasses = true; })
     .add("--no-fuzz-memory",
          "",
          "don't emit memory ops when fuzzing",
+         WasmOptOption,
          Options::Arguments::Zero,
          [&](Options* o, const std::string& arguments) { fuzzMemory = false; })
     .add("--no-fuzz-oob",
          "",
          "don't emit out-of-bounds loads/stores/indirect calls when fuzzing",
+         WasmOptOption,
          Options::Arguments::Zero,
          [&](Options* o, const std::string& arguments) { fuzzOOB = false; })
     .add("--emit-js-wrapper",
          "-ejw",
          "Emit a JavaScript wrapper file that can run the wasm with some test "
          "values, useful for fuzzing",
+         WasmOptOption,
          Options::Arguments::One,
          [&](Options* o, const std::string& arguments) {
            emitJSWrapper = arguments;
@@ -176,6 +190,7 @@ int main(int argc, const char* argv[]) {
          "-esw",
          "Emit a wasm spec interpreter wrapper file that can run the wasm with "
          "some test values, useful for fuzzing",
+         WasmOptOption,
          Options::Arguments::One,
          [&](Options* o, const std::string& arguments) {
            emitSpecWrapper = arguments;
@@ -184,6 +199,7 @@ int main(int argc, const char* argv[]) {
          "-esw",
          "Emit a C wrapper file that can run the wasm after it is compiled "
          "with wasm2c, useful for fuzzing",
+         WasmOptOption,
          Options::Arguments::One,
          [&](Options* o, const std::string& arguments) {
            emitWasm2CWrapper = arguments;
@@ -191,6 +207,7 @@ int main(int argc, const char* argv[]) {
     .add("--input-source-map",
          "-ism",
          "Consume source map from the specified file",
+         WasmOptOption,
          Options::Arguments::One,
          [&inputSourceMapFilename](Options* o, const std::string& argument) {
            inputSourceMapFilename = argument;
@@ -198,6 +215,7 @@ int main(int argc, const char* argv[]) {
     .add("--output-source-map",
          "-osm",
          "Emit source map to the specified file",
+         WasmOptOption,
          Options::Arguments::One,
          [&outputSourceMapFilename](Options* o, const std::string& argument) {
            outputSourceMapFilename = argument;
@@ -205,6 +223,7 @@ int main(int argc, const char* argv[]) {
     .add("--output-source-map-url",
          "-osu",
          "Emit specified string as source map URL",
+         WasmOptOption,
          Options::Arguments::One,
          [&outputSourceMapUrl](Options* o, const std::string& argument) {
            outputSourceMapUrl = argument;