[llvm-dwarfdump] Make commandline arguments consistent.

[Higuoxing]

Summary

Currently, llvm-dwarfdump's help message has two issues.

1. Most long options are printed in --long-option, except for some section dumping options, e.g., -apple-names, -debug-addr.

2. Most options are printed with consistent indention, except for some section dumping options.

This patch helps resolve these two issues.

[jhenderson]

Most options are printed with consistent indention, except for some "debug" options.

Could you elaborate on this point, and how this helps fix it? Could you also please paste before/after examples of the help output?

llvm/test/tools/llvm-dwarfdump/cmdline.test

10–11

Why have you singled out the -debug-info option for this extra testing? What about the other options?

[Higuoxing]

In D79618#2028970, @jhenderson wrote:

Most options are printed with consistent indention, except for some "debug" options.

Could you elaborate on this point, and how this helps fix it? Could you also please paste before/after examples of the help output?

Sure, let me explain this.

llvm-dwarfdump offers some options called OffsetOption. These options take an optional argument called offset, which directs llvm-dwarfdump to dump only the entry at the specified offset, e.g., llvm-dwarfdump --debug-info=0x0b some_object will dump the .debug_info entry at offset 0x0b of the object file some_object.

Help messages are printed via printOptionInfo(). If we use the default printOptionInfo() method, these options will be printed as --debug-info=<value>. I guess the original author wants to discard the optional value string =<value>, so he implements a customed one. However, this will cause the command line arguments parser to calculate the wrong numbers of indent whitespaces. As you cant see the examples below, all the "debug" options are lacking some indent whitespaces between argument and help message, and the number of missing whitespaces is as many as characters in =<value>.

Actually, we can simply override the getValueName() method to tell the commandline parser not to print =<value>.

---

Below are the output examples of llvm-dwarfdump --help

Before,

$ llvm-dwarfdump --help
OVERVIEW: pretty-print DWARF debug information in object files and debug info archives.

USAGE: llvm-dwarfdump [options] <input object files or .dSYM bundles>

OPTIONS:

Color Options:

  --color                      - Use colors in output (default=autodetect)

Generic Options:

  --help                       - Display available options (--help-hidden for more)
  --help-list                  - Display list of available options (--help-list-hidden for more)
  --version                    - Display the version of this program

Section-specific Dump Options:
These control which sections are dumped. Where applicable these parameters take an optional =<offset> argument to dump only the entry at the specified offset.

  --all                        - Dump all debug info sections
  -apple-names        - Dump the .apple_names section
  -apple-namespaces   - Dump the .apple_namespaces section
  -apple-objc         - Dump the .apple_objc section
  -apple-types        - Dump the .apple_types section
  -debug-abbrev       - Dump the .debug_abbrev section
  -debug-addr         - Dump the .debug_addr section
  -debug-aranges      - Dump the .debug_aranges section
  -debug-cu-index     - Dump the .debug_cu_index section
  -debug-frame        - Dump the .debug_frame section
  -debug-gnu-pubnames - Dump the .debug_gnu_pubnames section
  -debug-gnu-pubtypes - Dump the .debug_gnu_pubtypes section
  -debug-info         - Dump the .debug_info section
  -debug-line         - Dump the .debug_line section
  -debug-line-str     - Dump the .debug_line_str section
  -debug-loc          - Dump the .debug_loc section
  -debug-loclists     - Dump the .debug_loclists section
  -debug-macro        - Dump the .debug_macro section
  -debug-names        - Dump the .debug_names section
  -debug-pubnames     - Dump the .debug_pubnames section
  -debug-pubtypes     - Dump the .debug_pubtypes section
  -debug-ranges       - Dump the .debug_ranges section
  -debug-rnglists     - Dump the .debug_rnglists section
  -debug-str          - Dump the .debug_str section
  -debug-str-offsets  - Dump the .debug_str_offsets section
  -debug-tu-index     - Dump the .debug_tu_index section
  -debug-types        - Dump the .debug_types section
  --eh-frame                   - Alias for -debug-frame
  -gdb-index          - Dump the .gdb_index section

Specific Options:

  --arch=<string>              - Dump debug information for the specified CPU architecture only. Architectures may be specified by name or by number. This option can be specified multiple times, once for each desired architecture.
  --diff                       - Emit diff-friendly output by omitting offsets and addresses.
  --find=<name>                - Search for the exact match for <name> in the accelerator tables and print the matching debug information entries. When no accelerator tables are available, the slower but more complete -name option can be used instead.
  --ignore-case                - Ignore case distinctions when searching.
  --lookup=<address>           - Lookup <address> in the debug information and print out any available file, function, block and line table details.
  --name=<pattern>             - Find and print all debug info entries whose name (DW_AT_name attribute) matches the exact text in <pattern>.  When used with the the -regex option <pattern> is interpreted as a regular expression.
  -o=<filename>                - Redirect output to the specified file.
  --parent-recurse-depth=<N>   - Only recurse to a depth of N when displaying parents of debug info entries.
  --quiet                      - Use with -verify to not emit to STDOUT.
  --recurse-depth=<N>          - Only recurse to a depth of N when displaying children of debug info entries.
  --regex                      - Treat any <pattern> strings as regular expressions when searching instead of just as an exact string match.
  --show-children              - Show a debug info entry's children when selectively printing entries.
  --show-form                  - Show DWARF form types after the DWARF attribute types.
  --show-parents               - Show a debug info entry's parents when selectively printing entries.
  --show-section-sizes         - Show the sizes of all debug sections, expressed in bytes.
  --statistics                 - Emit JSON-formatted debug info quality metrics.
  --summarize-types            - Abbreviate the description of type unit entries.
  --uuid                       - Show the UUID for each architecture.
  --verbose                    - Print more low-level encoding details.
  --verify                     - Verify the DWARF debug info.

Pass @FILE as argument to read options from FILE.

After,

$ llvm-dwarfdump --help                                  
OVERVIEW: pretty-print DWARF debug information in object files and debug info archives.

USAGE: llvm-dwarfdump [options] <input object files or .dSYM bundles>

OPTIONS:

Color Options:

  --color                    - Use colors in output (default=autodetect)

Generic Options:

  --help                     - Display available options (--help-hidden for more)
  --help-list                - Display list of available options (--help-list-hidden for more)
  --version                  - Display the version of this program

Section-specific Dump Options:
These control which sections are dumped. Where applicable these parameters take an optional =<offset> argument to dump only the entry at the specified offset.

  --all                      - Dump all debug info sections
  --apple-names              - Dump the .apple_names section
  --apple-namespaces         - Dump the .apple_namespaces section
  --apple-objc               - Dump the .apple_objc section
  --apple-types              - Dump the .apple_types section
  --debug-abbrev             - Dump the .debug_abbrev section
  --debug-addr               - Dump the .debug_addr section
  --debug-aranges            - Dump the .debug_aranges section
  --debug-cu-index           - Dump the .debug_cu_index section
  --debug-frame              - Dump the .debug_frame section
  --debug-gnu-pubnames       - Dump the .debug_gnu_pubnames section
  --debug-gnu-pubtypes       - Dump the .debug_gnu_pubtypes section
  --debug-info               - Dump the .debug_info section
  --debug-line               - Dump the .debug_line section
  --debug-line-str           - Dump the .debug_line_str section
  --debug-loc                - Dump the .debug_loc section
  --debug-loclists           - Dump the .debug_loclists section
  --debug-macro              - Dump the .debug_macro section
  --debug-names              - Dump the .debug_names section
  --debug-pubnames           - Dump the .debug_pubnames section
  --debug-pubtypes           - Dump the .debug_pubtypes section
  --debug-ranges             - Dump the .debug_ranges section
  --debug-rnglists           - Dump the .debug_rnglists section
  --debug-str                - Dump the .debug_str section
  --debug-str-offsets        - Dump the .debug_str_offsets section
  --debug-tu-index           - Dump the .debug_tu_index section
  --debug-types              - Dump the .debug_types section
  --eh-frame                 - Alias for -debug-frame
  --gdb-index                - Dump the .gdb_index section

Specific Options:

  --arch=<string>            - Dump debug information for the specified CPU architecture only. Architectures may be specified by name or by number. This option can be specified multiple times, once for each desired architecture.
  --diff                     - Emit diff-friendly output by omitting offsets and addresses.
  --find=<name>              - Search for the exact match for <name> in the accelerator tables and print the matching debug information entries. When no accelerator tables are available, the slower but more complete -name option can be used instead.
  --ignore-case              - Ignore case distinctions when searching.
  --lookup=<address>         - Lookup <address> in the debug information and print out any available file, function, block and line table details.
  --name=<pattern>           - Find and print all debug info entries whose name (DW_AT_name attribute) matches the exact text in <pattern>.  When used with the the -regex option <pattern> is interpreted as a regular expression.
  -o=<filename>              - Redirect output to the specified file.
  --parent-recurse-depth=<N> - Only recurse to a depth of N when displaying parents of debug info entries.
  --quiet                    - Use with -verify to not emit to STDOUT.
  --recurse-depth=<N>        - Only recurse to a depth of N when displaying children of debug info entries.
  --regex                    - Treat any <pattern> strings as regular expressions when searching instead of just as an exact string match.
  --show-children            - Show a debug info entry's children when selectively printing entries.
  --show-form                - Show DWARF form types after the DWARF attribute types.
  --show-parents             - Show a debug info entry's parents when selectively printing entries.
  --show-section-sizes       - Show the sizes of all debug sections, expressed in bytes.
  --statistics               - Emit JSON-formatted debug info quality metrics.
  --summarize-types          - Abbreviate the description of type unit entries.
  --uuid                     - Show the UUID for each architecture.
  --verbose                  - Print more low-level encoding details.
  --verify                   - Verify the DWARF debug info.

Pass @FILE as argument to read options from FILE.

[Higuoxing]

llvm/test/tools/llvm-dwarfdump/cmdline.test

10–11

Because there's only one test case for --debug-* options. Should I add more tests for this?

[jhenderson]

If you are planning on using the description as your commit message, please rephrase the second point "some section dumping options have inconsistent indentation". Also change the first one saying "debug" options to "section dumping options", as the phrasing you use suggests to me that they are for debugging the tool, rather than provide useful output!

If you could fix that, and also add the double-dashes to the rest of the test, I think that would be sufficient for this.

llvm/test/tools/llvm-dwarfdump/cmdline.test

10–11

I was thinking more why do -color/-help etc not use double dashes.

I'm not sure that we need extra testing beyond that point, as I don't think it will provide much use.

[Higuoxing]

Address comments.

• Add double-dashes to the rest of test.

[jhenderson]

LGTM.

llvm/test/tools/llvm-dwarfdump/cmdline.test

 RUN: llvm-dwarfdump -h 2>&1 | FileCheck --check-prefix=HELP %s --implicit-check-not=out-file
 RUN: llvm-dwarfdump --help 2>&1 | FileCheck --check-prefix=HELP %s --implicit-check-not=out-file
 HELP: USAGE: llvm-dwarfdump{{[^ ]*}} [options] <input object files or .dSYM bundles>
 HELP: Color Options
-HELP: -color
+HELP: --color
 HELP: Generic Options
-HELP: -help
-HELP: -help-list
-HELP: -version
+HELP: --help
+HELP: --help-list
+HELP: --version
 HELP: Section-specific Dump Options
-HELP: -debug-info            - Dump the .debug_info section
-HELP: -eh-frame
+HELP: --debug-info            - Dump the .debug_info section
+HELP: --eh-frame
 HELP: Specific Options
-HELP: -diff
-HELP: -find
-HELP: -ignore-case
-HELP: -lookup
-HELP: -name
+HELP: --diff
+HELP: --find
+HELP: --ignore-case
+HELP: --lookup
+HELP: --name
 HELP: -o=<filename>
-HELP: -parent-recurse-depth=<N>
-HELP: -recurse-depth=<N>
-HELP: -regex
-HELP: -show-children
-HELP: -show-form
-HELP: -show-parents
-HELP: -statistics
-HELP: -summarize-types
+HELP: --parent-recurse-depth=<N>
+HELP: --recurse-depth=<N>
+HELP: --regex
+HELP: --show-children
+HELP: --show-form
+HELP: --show-parents
+HELP: --statistics
+HELP: --summarize-types
 HELP: @FILE
 
 RUN: llvm-dwarfdump --version 2>&1 | FileCheck --check-prefix=VERSION %s
 VERSION: {{ version }}
 
 RUN: llvm-dwarfdump -diff -verbose 2>&1 | FileCheck --check-prefix=INCOMPATIBLE %s
 INCOMPATIBLE: error: incompatible arguments: specifying both -diff and -verbose is currently not supported

llvm/tools/llvm-dwarfdump/llvm-dwarfdump.cpp

bool parse(Option &O, StringRef ArgName, StringRef Arg, OffsetOption &Val) {
     Val.IsRequested = true;
     return false;
   }
 
   enum ValueExpected getValueExpectedFlagDefault() const {
     return ValueOptional;
   }
 
-  void printOptionInfo(const Option &O, size_t GlobalWidth) const {
-    outs() << "  -" << O.ArgStr;
-    Option::printHelpStr(O.HelpStr, GlobalWidth, getOptionWidth(O));
-  }
+  StringRef getValueName() const override { return StringRef(); }
 
   void printOptionDiff(const Option &O, OffsetOption V, OptVal Default,
                        size_t GlobalWidth) const {
     printOptionName(O, GlobalWidth);
     outs() << "[=offset]";
   }
 
   // An out-of-line virtual method to provide a 'home' for this class.