[binutils] Add response file option to help and docs

[jhenderson]

Summary

Many LLVM-based tools already support response files (i.e. files containing a list of options, specified with '@'). This change simply updates the documentation and help text for some of these tools to include it. I haven't attempted to fix all tools, just a selection that I am interested in.

I've taken the opportunity to add some tests for --help behaviour, where they were missing. We could expand these tests, but I don't think that's within scope of this patch.

This fixes https://bugs.llvm.org/show_bug.cgi?id=42233 and https://bugs.llvm.org/show_bug.cgi?id=42236.

[jhenderson]

D63565 needs to land first for the llvm-dwarfdump test to work, due to an odd difference in behaviour between -h and --help in llvm-dwarfdump.

[jkorous]

LGTM

[grimar]

LGTM

docs/CommandGuide/llvm-nm.rst

 
  Print only symbols referenced but not defined in this file.
 
 .. option:: --radix=RADIX, -t
 
  Specify the radix of the symbol address(es). Values accepted d(decimal),
  x(hexadecimal) and o(octal).
 
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
 BUGS
 ----
 
  * :program:`llvm-nm` does not support the full set of arguments that GNU
    :program:`nm` does.
 
 EXIT STATUS
 -----------
 
 :program:`llvm-nm` exits with an exit code of zero.
 
 SEE ALSO
 --------
 
 llvm-dis, ar(1), nm(1)

docs/CommandGuide/llvm-objdump.rst

.. option:: -x86-asm-syntax=<style>
 
    .. option:: intel
 
     Intel-style assembly
 
 
   The default disassembly style is **att**.
 
+.. option:: @<FILE>
+
+  Read command-line options and commands from response file `<FILE>`.
+
 BUGS
 ----
 
 To report bugs, please visit <http://llvm.org/bugs/>.
 
 SEE ALSO
 --------
 
 :manpage:`llvm-nm(1)`

docs/CommandGuide/llvm-readobj.rst

 .. option:: -elf-section-groups, -g
 
  Display section groups (only for ELF object files).
 
 .. option:: -demangle, -C
 
  Print demangled symbol names in the output.
 
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
 EXIT STATUS
 -----------
 
 :program:`llvm-readobj` returns 0.

docs/CommandGuide/llvm-symbolizer.rst

.. code-block:: console
     main at /tmp/x.c:3:3
 
     main at /tmp/x.c:14:3
 
     $ llvm-symbolizer --output-style=GNU -p -i=0 -e=addr.exe 0x40054d 0x400568
     inc at /tmp/x.c:3
     main at /tmp/x.c:14
 
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
 EXIT STATUS
 -----------
 
 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
 error.

test/tools/llvm-cxxfilt/help.test

+RUN: llvm-cxxfilt -h | FileCheck %s
+RUN: llvm-cxxfilt --help | FileCheck %s
+
+CHECK: OVERVIEW: llvm symbol undecoration tool
+CHECK: USAGE: llvm-cxxfilt{{(.exe)?}} [options] <mangled>{{$}}
+CHECK: OPTIONS:
+CHECK: @FILE

test/tools/llvm-dwarfdump/cmdline.test

 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

test/tools/llvm-objdump/help.test

+RUN: llvm-objdump --help | FileCheck %s
+
+CHECK: OVERVIEW: llvm object file dumper
+CHECK: USAGE: llvm-objdump{{(.exe)?}} [options] <input object files>{{$}}
+CHECK: OPTIONS:
+CHECK: @FILE

test/tools/llvm-readobj/basic.test

 # Test version switch.
 RUN: llvm-readobj --version | FileCheck %s --check-prefix=VERSION
 RUN: llvm-readelf --version | FileCheck %s --check-prefix=VERSION
 # In default configuration we could match "LLVM version", but the "LLVM" part
 # can be changed with PACKAGE_NAME in CMake, so we match only version.
 VERSION: version
 
 # Test help switch.
-RUN: llvm-readobj --help | FileCheck %s --check-prefixes=HELP,USAGE-OBJ
-RUN: llvm-readelf --help | FileCheck %s --check-prefixes=HELP,USAGE-ELF
+RUN: llvm-readobj --help | FileCheck %s --check-prefixes=HELP,OBJ
+RUN: llvm-readelf --help | FileCheck %s --check-prefixes=HELP,ELF
 HELP: OVERVIEW: LLVM Object Reader
-USAGE-OBJ: llvm-readobj{{.*}} [options] <input object files>
-USAGE-ELF: llvm-readelf{{.*}} [options] <input object files>
+OBJ: llvm-readobj{{.*}} [options] <input object files>
+ELF: llvm-readelf{{.*}} [options] <input object files>
+HELP: OPTIONS:
+OBJ: -s - Alias for --section-headers
+OBJ: -t - Alias for --symbols
+ELF: -s - Alias for --symbols
+ELF-NOT: {{ }}-t{{ }}
+HELP: @FILE

test/tools/llvm-size/help.test

+RUN: llvm-size -h | FileCheck %s
+RUN: llvm-size --help | FileCheck %s
+
+CHECK: OVERVIEW: llvm object size dumper
+CHECK: USAGE: llvm-size{{(.exe)?}} [options] <input files>{{$}}
+CHECK: OPTIONS:
+CHECK: @FILE

test/tools/llvm-strings/help.test

+RUN: llvm-strings -h | FileCheck %s
+RUN: llvm-strings --help | FileCheck %s
+
+CHECK: OVERVIEW: llvm string dumper
+CHECK: USAGE: llvm-strings{{(.exe)?}} [options] <input object files>{{$}}
+CHECK: OPTIONS:
+CHECK: @FILE

test/tools/llvm-symbolizer/help.test

-RUN: llvm-symbolizer -help | FileCheck %s --check-prefix=SYMBOLIZER
-RUN: llvm-addr2line -help | FileCheck %s --check-prefix=ADDR2LINE
+RUN: llvm-symbolizer -h | FileCheck %s --check-prefix=SYMBOLIZER
+RUN: llvm-symbolizer --help | FileCheck %s --check-prefix=SYMBOLIZER
+RUN: llvm-addr2line -h | FileCheck %s --check-prefix=ADDR2LINE
+RUN: llvm-addr2line --help | FileCheck %s --check-prefix=ADDR2LINE
 
 SYMBOLIZER: OVERVIEW: llvm-symbolizer
 SYMBOLIZER: USAGE: llvm-symbolizer{{(.exe)?}} [options] <input addresses>...
+SYMBOLIZER: @FILE
 
 ADDR2LINE: OVERVIEW: llvm-addr2line
 ADDR2LINE: USAGE: llvm-addr2line{{(.exe)?}} [options] <input addresses>...
+ADDR2LINE: @FILE

tools/llvm-cxxfilt/llvm-cxxfilt.cpp

Types("types",
           cl::desc("attempt to demangle types as well as function names"),
           cl::init(false));
 static cl::alias TypesShort("t", cl::desc("alias for --types"),
                             cl::aliasopt(Types));
 
 static cl::list<std::string>
 Decorated(cl::Positional, cl::desc("<mangled>"), cl::ZeroOrMore);
 
+static cl::extrahelp
+    HelpResponse("\nPass @FILE as argument to read options from FILE.\n");
+
 static std::string demangle(llvm::raw_ostream &OS, const std::string &Mangled) {
   int Status;
 
   const char *DecoratedStr = Mangled.c_str();
   if (StripUnderscore)
     if (DecoratedStr[0] == '_')
       ++DecoratedStr;
   size_t DecoratedLength = strlen(DecoratedStr);

tools/llvm-dwarfdump/llvm-dwarfdump.cpp

 static opt<bool> DumpUUID("uuid", desc("Show the UUID for each architecture."),
                           cat(DwarfDumpCategory));
 static alias DumpUUIDAlias("u", desc("Alias for -uuid."), aliasopt(DumpUUID));
 static opt<bool> Verbose("verbose",
                          desc("Print more low-level encoding details."),
                          cat(DwarfDumpCategory));
 static alias VerboseAlias("v", desc("Alias for -verbose."), aliasopt(Verbose),
                           cat(DwarfDumpCategory));
+static cl::extrahelp
+    HelpResponse("\nPass @FILE as argument to read options from FILE.\n");
 } // namespace
 /// @}
 //===----------------------------------------------------------------------===//
 
 static void error(StringRef Prefix, std::error_code EC) {
   if (!EC)
     return;
   WithColor::error() << Prefix << ": " << EC.message() << "\n";

tools/llvm-objdump/llvm-objdump.cpp

static cl::alias UnwindInfoShort("u", cl::desc("Alias for --unwind-info"),
                                  cl::NotHidden, cl::Grouping,
                                  cl::aliasopt(UnwindInfo));
 
 static cl::opt<bool>
     Wide("wide", cl::desc("Ignored for compatibility with GNU objdump"),
          cl::cat(ObjdumpCat));
 static cl::alias WideShort("w", cl::Grouping, cl::aliasopt(Wide));
 
+static cl::extrahelp
+    HelpResponse("\nPass @FILE as argument to read options from FILE.\n");
+
 static StringSet<> DisasmFuncsSet;
 static StringRef ToolName;
 
 typedef std::vector<std::tuple<uint64_t, StringRef, uint8_t>> SectionSymbolsTy;
 
 static bool shouldKeep(object::SectionRef S) {
   if (FilterSections.empty())
     return true;

tools/llvm-readobj/llvm-readobj.cpp

cl::opt<bool> Addrsig("addrsig",
                         cl::desc("Display address-significance table"));
 
   // -elf-output-style
   cl::opt<OutputStyleTy>
       Output("elf-output-style", cl::desc("Specify ELF dump style"),
              cl::values(clEnumVal(LLVM, "LLVM default style"),
                         clEnumVal(GNU, "GNU readelf style")),
              cl::init(LLVM));
+
+  cl::extrahelp
+      HelpResponse("\nPass @FILE as argument to read options from FILE.\n");
 } // namespace opts
 
 namespace llvm {
 
 LLVM_ATTRIBUTE_NORETURN void reportError(Twine Msg) {
   errs() << "\n";
   WithColor::error(errs()) << Msg << "\n";
   exit(1);

tools/llvm-size/llvm-size.cpp

TotalSizes("totals",
                cl::init(false), cl::cat(SizeCat));
 
 static cl::alias TotalSizesShort("t", cl::desc("Short for --totals"),
                                  cl::aliasopt(TotalSizes));
 
 static cl::list<std::string>
     InputFilenames(cl::Positional, cl::desc("<input files>"), cl::ZeroOrMore);
 
+static cl::extrahelp
+    HelpResponse("\nPass @FILE as argument to read options from FILE.\n");
+
 static bool HadError = false;
 
 static std::string ToolName;
 
 /// If ec is not success, print the error and return true.
 static bool error(std::error_code ec) {
   if (!ec)
     return false;

tools/llvm-strings/llvm-strings.cpp

 static cl::opt<radix>
     Radix("radix", cl::desc("print the offset within the file"),
           cl::values(clEnumValN(octal, "o", "octal"),
                      clEnumValN(hexadecimal, "x", "hexadecimal"),
                      clEnumValN(decimal, "d", "decimal")),
           cl::init(none));
 static cl::alias RadixShort("t", cl::desc(""), cl::aliasopt(Radix));
 
+static cl::extrahelp
+    HelpResponse("\nPass @FILE as argument to read options from FILE.\n");
+
 static void strings(raw_ostream &OS, StringRef FileName, StringRef Contents) {
   auto print = [&OS, FileName](unsigned Offset, StringRef L) {
     if (L.size() < static_cast<size_t>(MinLength))
       return;
     if (PrintFileName)
       OS << FileName << ": ";
     switch (Radix) {
     case none:

tools/llvm-symbolizer/llvm-symbolizer.cpp

 static cl::opt<DIPrinter::OutputStyle>
     ClOutputStyle("output-style", cl::init(DIPrinter::OutputStyle::LLVM),
                   cl::desc("Specify print style"),
                   cl::values(clEnumValN(DIPrinter::OutputStyle::LLVM, "LLVM",
                                         "LLVM default style"),
                              clEnumValN(DIPrinter::OutputStyle::GNU, "GNU",
                                         "GNU addr2line style")));
 
+static cl::extrahelp
+    HelpResponse("\nPass @FILE as argument to read options from FILE.\n");
+
 template<typename T>
 static bool error(Expected<T> &ResOrErr) {
   if (ResOrErr)
     return false;
   logAllUnhandledErrors(ResOrErr.takeError(), errs(),
                         "LLVMSymbolizer: error reading file: ");
   return true;
 }