[llvm-nm] Switch command line parsing from llvm::cl to OptTable

Part of https://lists.llvm.org/pipermail/llvm-dev/2021-July/151622.html
"Binary utilities: switch command line parsing from llvm::cl to OptTable"

Users should generally observe no difference as long as they only use intended
option forms. Behavior changes:

* `-t=d` is removed. Use `-t d` instead.
* `--demangle=0` cannot be used. Omit the option or use `--no-demangle` instead.
* `--help-list` is removed. This is a `cl::` specific option.

Note:

* `-t` diagnostic gets improved.
* This patch avoids cl::opt collision if we decide to support multiplexing for binary utilities
* One-dash long options are still supported.
* The `-s` collision (`-s segment section` for Mach-O) is unfortunate. `-s` means `--print-armap` in GNU nm.
* This patch removes the last `cl::multi_val` use case from the `llvm/lib/Support/CommandLine.cpp` library

`-M` (`--print-armap`), `-U` (`--defined-only`), and `-W` (`--no-weak`)
are now deprecated. They could conflict with future GNU nm options.
(--print-armap has an existing alias -s, so GNU will unlikely add a new one.
--no-weak (not in GNU nm) is rarely used anyway.)

`--just-symbol-name` is now deprecated in favor of
`--format=just-symbols` and `-j`.

Reviewed By: jhenderson

Differential Revision: https://reviews.llvm.org/D105330

llvm/docs/CommandGuide/llvm-nm.rst

@@ -130,7 +130,7 @@ OPTIONS
 
  Show all symbols, even those usually suppressed.
 
-.. option:: --defined-only, -U
+.. option:: --defined-only
 
  Print only symbols defined in this file.
 
@@ -157,11 +157,7 @@ OPTIONS
 
  Print a summary of command-line options and their meanings.
 
-.. option:: --help-list
-
- Print an uncategorized summary of command-line options and their meanings.
-
-.. option:: --just-symbol-name, -j
+.. option:: -j
 
  Print just the symbol names. Alias for `--format=just-symbols``.
 
@@ -181,7 +177,7 @@ OPTIONS
 
  Show symbols in the order encountered.
 
-.. option:: --no-weak, -W
+.. option:: --no-weak
 
  Don't print weak symbols.
 
@@ -193,7 +189,7 @@ OPTIONS
 
  Use POSIX.2 output format.  Alias for ``--format=posix``.
 
-.. option:: --print-armap, -M
+.. option:: --print-armap
 
  Print the archive symbol table, in addition to the symbols.
 
@@ -235,10 +231,6 @@ OPTIONS
  Display the version of the :program:`llvm-nm` executable, then exit. Does not
  stack with other commands.
 
-.. option:: --without-aliases
-
- Exclude aliases from the output.
-
 .. option:: @<FILE>
 
  Read command-line options from response file `<FILE>`.
@@ -267,7 +259,7 @@ MACH-O SPECIFIC OPTIONS
 
  Do not add any symbols from the dyldinfo.
 
-.. option:: -s=<segment section>
+.. option:: -s <segment> <section>
 
  Dump only symbols from this segment and section name.
 

llvm/docs/ReleaseNotes.rst

@@ -169,6 +169,13 @@ Changes to the LLVM tools
   ``--section-details`` respectively, to match llvm-readelf.
   (`D105055 <https://reviews.llvm.org/D105055>`_)
 
+* The llvm-nm short aliases ``-M`` (``--print-armap``), ``-U``
+  (``--defined-only``), and ``-W`` (``--no-weak``) are now deprecated.
+  Use the long form versions instead.
+  The alias ``--just-symbol-name`` is now deprecated in favor of
+  ``--format=just-symbols`` and ``-j``.
+  (`D105330 <https://reviews.llvm.org/D105330>`_)
+
 Changes to LLDB
 ---------------------------------
 

llvm/test/Object/nm-universal-binary.test

@@ -5,9 +5,9 @@ RUN:         | FileCheck %s -check-prefix CHECK-64-OBJ
 RUN: llvm-nm --arch=x86_64 %p/Inputs/macho-universal.x86_64.i386 \
 RUN:         | FileCheck %s -check-prefix CHECK-OBJ-x86_64
 RUN: not llvm-nm --arch=armv7m %p/Inputs/macho-universal.x86_64.i386 2>&1 \
-RUN:         | FileCheck %s -check-prefix CHECK-OBJ-armv7m
+RUN:         | FileCheck %s --check-prefix=CHECK-OBJ-armv7m --implicit-check-not=error:
 RUN: not llvm-nm --arch=foobar %p/Inputs/macho-universal.x86_64.i386 2>&1 \
-RUN:         | FileCheck %s -check-prefix CHECK-OBJ-foobar
+RUN:         | FileCheck %s --check-prefix=CHECK-OBJ-foobar --implicit-check-not=error:
 RUN: llvm-nm --arch=all %p/Inputs/macho-universal-archive.x86_64.i386 \
 RUN:         | FileCheck %s -check-prefix CHECK-AR
 RUN: llvm-nm --arch=all %p/Inputs/macho-universal64-archive.x86_64.i386 \
@@ -31,11 +31,9 @@ CHECK-OBJ-x86_64: 0000000100000000 T __mh_execute_header
 CHECK-OBJ-x86_64: 0000000100000f60 T _main
 CHECK-OBJ-x86_64:                  U dyld_stub_binder
 
-CHECK-OBJ-armv7m-NOT: Unknown architecture named
-CHECK-OBJ-armv7m: does not contain architecture
+CHECK-OBJ-armv7m: error: file: {{.*}} does not contain architecture
 
-CHECK-OBJ-foobar: Unknown architecture named
-CHECK-OBJ-foobar: does not contain architecture
+CHECK-OBJ-foobar: error: for the --arch option: Unknown architecture named 'foobar'
 
 CHECK-AR: macho-universal-archive.x86_64.i386(hello.o) (for architecture x86_64):
 CHECK-AR: 0000000000000068 s EH_frame0

llvm/test/tools/llvm-nm/X86/radix.s

@@ -2,7 +2,8 @@
 // RUN: llvm-mc %s -filetype=obj -triple=x86_64-pc-linux -o %t.o
 // RUN: llvm-nm --radix=d %t.o | FileCheck %s
 // RUN: llvm-nm --radix=o %t.o | FileCheck --check-prefix=OCTAL %s
-// RUN: llvm-nm -t=x %t.o | FileCheck --check-prefix=HEX %s
+// RUN: llvm-nm -tx %t.o | FileCheck --check-prefix=HEX %s
+// RUN: llvm-nm -t x %t.o | FileCheck --check-prefix=HEX %s
 
 	.text
 	.file	"1.c"

llvm/test/tools/llvm-nm/format-bsd.test

@@ -3,7 +3,7 @@
 
 # RUN: yaml2obj %s -o %t.o
 # RUN: llvm-nm %t.o --format=bsd > %t.formatbsd.txt
-# RUN: llvm-nm %t.o -f=bsd > %t.fbsd.txt
+# RUN: llvm-nm %t.o -f bsd > %t.fbsd.txt
 # RUN: llvm-nm %t.o -B > %t.b.txt
 # RUN: llvm-nm %t.o > %t.default.txt
 

llvm/test/tools/llvm-nm/format-sysv-layout.test

@@ -1,6 +1,7 @@
 # RUN: yaml2obj %s -o %t.o
 # RUN: llvm-nm %t.o --debug-syms --format=sysv | FileCheck %s -DFILE=%t.o --strict-whitespace
-# RUN: llvm-nm %t.o --debug-syms -f=sysv | FileCheck %s -DFILE=%t.o --strict-whitespace
+# RUN: llvm-nm %t.o --debug-syms -fsysv | FileCheck %s -DFILE=%t.o --strict-whitespace
+# RUN: llvm-nm %t.o --debug-syms -f sysv | FileCheck %s -DFILE=%t.o --strict-whitespace
 
 !ELF
 FileHeader:

llvm/test/tools/llvm-nm/help.test

@@ -1,3 +1,10 @@
 RUN: llvm-nm --help 2>&1 | FileCheck --implicit-check-not="General Options:" %s
-CHECK: Generic Options:
-CHECK: llvm-nm Options:
+RUN: llvm-nm -h 2>&1 | FileCheck --implicit-check-not="General Options:" %s
+CHECK: OPTIONS:
+CHECK:   --debug-syms
+CHECK:   --demangle
+CHECK:   --format=<format>
+CHECK: llvm-nm Mach-O Specific Options:
+CHECK:   --arch=<value>
+CHECK:   -s
+CHECK: Pass @FILE {{.*}}

llvm/test/tools/llvm-nm/just-symbols.test

@@ -7,7 +7,7 @@
 # RUN: llvm-nm --just-symbol-name %t.o | diff %t.txt -
 # RUN: llvm-nm --format=just-symbols %t.o | diff %t.txt -
 # RUN: llvm-nm --format=sysv -j %t.o | diff %t.txt -
-# RUN: llvm-nm -j --format=posix %t.o | diff %t.txt -
+# RUN: llvm-nm -j --format=posix %t.o | not diff -q %t.txt %t1.txt
 
 # RUN: FileCheck %s --input-file=%t.txt --implicit-check-not={{.}} --check-prefix=COMMON
 

llvm/test/tools/llvm-nm/libtool-version.test

@@ -4,5 +4,5 @@
 
 RUN: llvm-nm -V | FileCheck %s
 RUN: llvm-nm --version | FileCheck %s
-CHECK: LLVM version
 CHECK: GNU
+CHECK: LLVM version

llvm/tools/llvm-nm/CMakeLists.txt

@@ -6,14 +6,20 @@ set(LLVM_LINK_COMPONENTS
   Core
   Demangle
   Object
+  Option
   Support
   TextAPI
   )
 
+set(LLVM_TARGET_DEFINITIONS Opts.td)
+tablegen(LLVM Opts.inc -gen-opt-parser-defs)
+add_public_tablegen_target(NmOptsTableGen)
+
 add_llvm_tool(llvm-nm
   llvm-nm.cpp
 
   DEPENDS
+  NmOptsTableGen
   intrinsics_gen
   )
 

llvm/tools/llvm-nm/Opts.td

@@ -0,0 +1,76 @@
+include "llvm/Option/OptParser.td"
+
+class F<string letter, string help> : Flag<["-"], letter>, HelpText<help>;
+class FF<string name, string help> : Flag<["--", "-"], name>, HelpText<help>;
+
+multiclass BB<string name, string help1, string help2> {
+  def NAME: Flag<["--", "-"], name>, HelpText<help1>;
+  def no_ # NAME: Flag<["--", "-"], "no-" # name>, HelpText<help2>;
+}
+
+multiclass Eq<string name, string help> {
+  def NAME #_EQ : Joined<["--", "-"], name #"=">,
+                  HelpText<help>;
+  def : Separate<["--", "-"], name>, Alias<!cast<Joined>(NAME #_EQ)>;
+}
+
+def debug_syms : FF<"debug-syms", "Show all symbols, even debugger only">;
+def defined_only : FF<"defined-only", "Show only defined symbols">;
+defm demangle : BB<"demangle", "Demangle C++ symbol names", "Don't demangle symbol names">;
+def dynamic : FF<"dynamic", "Display dynamic symbols instead of normal symbols">;
+def extern_only : FF<"extern-only", "Show only external symbols">;
+defm format : Eq<"format", "Specify output format: bsd (default), posix, sysv, darwin, just-symbols">, MetaVarName<"<format>">;
+def help : FF<"help", "Display this help">;
+def no_llvm_bc : FF<"no-llvm-bc", "Disable LLVM bitcode reader">;
+def no_sort : FF<"no-sort", "Show symbols in order encountered">;
+def no_weak : FF<"no-weak", "Show only non-weak symbols">;
+def numeric_sort : FF<"numeric-sort", "Sort symbols by address">;
+def print_armap : FF<"print-armap", "Print the archive map">;
+def print_file_name : FF<"print-file-name", "Precede each symbol with the object file it came from">;
+def print_size : FF<"print-size", "Show symbol size as well as address">;
+def quiet : FF<"quiet", "Suppress 'no symbols' diagnostic">;
+defm radix : Eq<"radix", "Radix (o/d/x) for printing symbol Values">, MetaVarName<"<radix>">;
+def reverse_sort : FF<"reverse-sort", "Sort in reverse order">;
+def size_sort : FF<"size-sort", "Sort symbols by size">;
+def special_syms : FF<"special-syms", "Do not filter special symbols from the output">;
+def undefined_only : FF<"undefined-only", "Show only undefined symbols">;
+def version : FF<"version", "Display the version">;
+def without_aliases : FF<"without-aliases", "Exclude aliases from output">, Flags<[HelpHidden]>;
+
+// Mach-O specific options.
+def grp_mach_o : OptionGroup<"kind">, HelpText<"llvm-nm Mach-O Specific Options">;
+
+def add_dyldinfo : FF<"add-dyldinfo", "Add symbols from the dyldinfo not already in the symbol table">, Group<grp_mach_o>;
+def add_inlinedinfo : FF<"add-inlinedinfo", "Add symbols from the inlined libraries, TBD only">, Group<grp_mach_o>;
+defm arch : Eq<"arch", "architecture(s) from a Mach-O file to dump">, Group<grp_mach_o>;
+def dyldinfo_only : FF<"dyldinfo-only", "Show only symbols from the dyldinfo">, Group<grp_mach_o>;
+def no_dyldinfo : FF<"no-dyldinfo", "Don't add any symbols from the dyldinfo">, Group<grp_mach_o>;
+def s : F<"s", "Dump only symbols from this segment and section name">, Group<grp_mach_o>;
+def x : F<"x", "Print symbol entry in hex">, Group<grp_mach_o>;
+
+def : FF<"just-symbol-name", "Alias for --format=just-symbols">, Alias<format_EQ>, AliasArgs<["just-symbols"]>, Flags<[HelpHidden]>;
+def : FF<"portability", "Alias for --format=posix">, Alias<format_EQ>, AliasArgs<["posix"]>;
+
+def : F<"a", "Alias for --debug-syms">, Alias<debug_syms>;
+def : F<"A", "Alias for --print-file-name">, Alias<print_file_name>;
+def : F<"B", "Alias for --format=bsd">, Alias<format_EQ>, AliasArgs<["bsd"]>;
+def : F<"C", "Alias for --demangle">, Alias<demangle>;
+def : F<"D", "Alias for --dynamic">, Alias<dynamic>;
+def : JoinedOrSeparate<["-"], "f">, HelpText<"Alias for --format">, Alias<format_EQ>, MetaVarName<"<format>">;
+def : F<"h", "Alias for --help">, Alias<help>;
+def : F<"g", "Alias for --extern-only">, Alias<extern_only>;
+def : F<"j", "Alias for --format=just-symbols">, Alias<format_EQ>, AliasArgs<["just-symbols"]>;
+def : F<"m", "Alias for --format=darwin">, Alias<format_EQ>, AliasArgs<["darwin"]>;
+def : F<"M", "Deprecated alias for --print-armap">, Alias<print_armap>, Flags<[HelpHidden]>;
+def : F<"n", "Alias for --numeric-sort">, Alias<numeric_sort>;
+def : F<"o", "Alias for --print-file-name">, Alias<print_file_name>;
+def : F<"p", "Alias for --no-sort">, Alias<no_sort>;
+def : F<"P", "Alias for --format=posix">, Alias<format_EQ>, AliasArgs<["posix"]>;
+def : F<"r", "Alias for --reverse-sort">, Alias<reverse_sort>;
+def : F<"S", "Alias for --print-size">, Alias<print_size>;
+def : JoinedOrSeparate<["-"], "t">, HelpText<"Alias for --radix">, Alias<radix_EQ>, MetaVarName<"<radix>">;
+def : F<"u", "Alias for --undefined-only">, Alias<undefined_only>;
+def : F<"U", "Deprecated alias for --defined-only">, Alias<defined_only>, Flags<[HelpHidden]>;
+def : F<"v", "Alias for --numeric-sort">, Alias<numeric_sort>;
+def : F<"V", "Alias for --version">, Alias<version>;
+def : F<"W", "Deprecated alias for --no-weak">, Alias<no_weak>, Flags<[HelpHidden]>;