[binutils] Add response file option to help and docs

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.

Reviewed by: grimar, MaskRay, jkorous

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

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@364036 91177308-0d34-0410-b5e6-96231b3b80d8

docs/CommandGuide/llvm-nm.rst

@@ -136,6 +136,10 @@ OPTIONS
  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
 ----
 

docs/CommandGuide/llvm-objdump.rst

@@ -316,6 +316,10 @@ MACH-O ONLY OPTIONS AND COMMANDS
 
   Display weak binding information.
 
+.. option:: @<FILE>
+
+  Read command-line options and commands from response file `<FILE>`.
+
 BUGS
 ----
 

docs/CommandGuide/llvm-readobj.rst

@@ -88,6 +88,10 @@ input. Otherwise, it will read from the specified ``filenames``.
 
  Print demangled symbol names in the output.
 
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
 EXIT STATUS
 -----------
 

docs/CommandGuide/llvm-symbolizer.rst

@@ -169,6 +169,10 @@ OPTIONS
     inc at /tmp/x.c:3
     main at /tmp/x.c:14
 
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
 EXIT STATUS
 -----------
 

test/tools/llvm-cxxfilt/help.test

@@ -0,0 +1,7 @@
+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

@@ -25,6 +25,7 @@ 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 }}

test/tools/llvm-objdump/help.test

@@ -0,0 +1,6 @@
+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

@@ -33,8 +33,14 @@ RUN: llvm-readelf --version | FileCheck %s --check-prefix=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

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,7 @@
+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

@@ -1,8 +1,12 @@
-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

@@ -52,6 +52,9 @@ static cl::alias TypesShort("t", cl::desc("alias for --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;
 

tools/llvm-dwarfdump/llvm-dwarfdump.cpp

@@ -220,6 +220,8 @@ static opt<bool> Verbose("verbose",
                          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
 /// @}
 //===----------------------------------------------------------------------===//

tools/llvm-objdump/llvm-objdump.cpp

@@ -330,6 +330,9 @@ static cl::opt<bool>
          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;
 

tools/llvm-readobj/llvm-readobj.cpp

@@ -363,6 +363,9 @@ namespace opts {
              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 {

tools/llvm-size/llvm-size.cpp

@@ -99,6 +99,9 @@ static cl::alias TotalSizesShort("t", cl::desc("Short for --totals"),
 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;

tools/llvm-strings/llvm-strings.cpp

@@ -54,6 +54,9 @@ static cl::opt<radix>
           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))

tools/llvm-symbolizer/llvm-symbolizer.cpp

@@ -154,6 +154,9 @@ static cl::opt<DIPrinter::OutputStyle>
                              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)