[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

llvm-svn: 364036

18 files changed, 80 insertions, 6 deletions

diff --git a/llvm/docs/CommandGuide/llvm-nm.rst b/llvm/docs/CommandGuide/llvm-nm.rst
index 4678a7a493d..874a184664b 100644
--- a/llvm/docs/CommandGuide/llvm-nm.rst
+++ b/llvm/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
 ----
 
diff --git a/llvm/docs/CommandGuide/llvm-objdump.rst b/llvm/docs/CommandGuide/llvm-objdump.rst
index 24bfe9ee060..8c81560caa9 100644
--- a/llvm/docs/CommandGuide/llvm-objdump.rst
+++ b/llvm/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
 ----
 
diff --git a/llvm/docs/CommandGuide/llvm-readobj.rst b/llvm/docs/CommandGuide/llvm-readobj.rst
index 7d4679f2032..0e752f731ff 100644
--- a/llvm/docs/CommandGuide/llvm-readobj.rst
+++ b/llvm/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
 -----------
 
diff --git a/llvm/docs/CommandGuide/llvm-symbolizer.rst b/llvm/docs/CommandGuide/llvm-symbolizer.rst
index 1c31a38ae09..7e2f205b34c 100644
--- a/llvm/docs/CommandGuide/llvm-symbolizer.rst
+++ b/llvm/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
 -----------
 
diff --git a/llvm/test/tools/llvm-cxxfilt/help.test b/llvm/test/tools/llvm-cxxfilt/help.test
new file mode 100644
index 00000000000..78bfad4aa3d
--- /dev/null
+++ b/llvm/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
diff --git a/llvm/test/tools/llvm-dwarfdump/cmdline.test b/llvm/test/tools/llvm-dwarfdump/cmdline.test
index 9aa0a1527b2..5930e718850 100644
--- a/llvm/test/tools/llvm-dwarfdump/cmdline.test
+++ b/llvm/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 }}
diff --git a/llvm/test/tools/llvm-objdump/help.test b/llvm/test/tools/llvm-objdump/help.test
new file mode 100644
index 00000000000..940eea3293a
--- /dev/null
+++ b/llvm/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
diff --git a/llvm/test/tools/llvm-readobj/basic.test b/llvm/test/tools/llvm-readobj/basic.test
index a08cc10aca7..488a4760732 100644
--- a/llvm/test/tools/llvm-readobj/basic.test
+++ b/llvm/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
diff --git a/llvm/test/tools/llvm-size/help.test b/llvm/test/tools/llvm-size/help.test
new file mode 100644
index 00000000000..a7bd6edf7a9
--- /dev/null
+++ b/llvm/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
diff --git a/llvm/test/tools/llvm-strings/help.test b/llvm/test/tools/llvm-strings/help.test
new file mode 100644
index 00000000000..9c3f932abae
--- /dev/null
+++ b/llvm/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
diff --git a/llvm/test/tools/llvm-symbolizer/help.test b/llvm/test/tools/llvm-symbolizer/help.test
index 5c41fccb648..12339463631 100644
--- a/llvm/test/tools/llvm-symbolizer/help.test
+++ b/llvm/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
diff --git a/llvm/tools/llvm-cxxfilt/llvm-cxxfilt.cpp b/llvm/tools/llvm-cxxfilt/llvm-cxxfilt.cpp
index eb84c3e8306..9ac8bcf0ff0 100644
--- a/llvm/tools/llvm-cxxfilt/llvm-cxxfilt.cpp
+++ b/llvm/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;
 
diff --git a/llvm/tools/llvm-dwarfdump/llvm-dwarfdump.cpp b/llvm/tools/llvm-dwarfdump/llvm-dwarfdump.cpp
index 701efade286..05a7aef67ec 100644
--- a/llvm/tools/llvm-dwarfdump/llvm-dwarfdump.cpp
+++ b/llvm/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
 /// @}
 //===----------------------------------------------------------------------===//
diff --git a/llvm/tools/llvm-objdump/llvm-objdump.cpp b/llvm/tools/llvm-objdump/llvm-objdump.cpp
index 4e841827892..fc3acb457e4 100644
--- a/llvm/tools/llvm-objdump/llvm-objdump.cpp
+++ b/llvm/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;
 
diff --git a/llvm/tools/llvm-readobj/llvm-readobj.cpp b/llvm/tools/llvm-readobj/llvm-readobj.cpp
index c040541f82a..31e8bbe1a62 100644
--- a/llvm/tools/llvm-readobj/llvm-readobj.cpp
+++ b/llvm/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 {
diff --git a/llvm/tools/llvm-size/llvm-size.cpp b/llvm/tools/llvm-size/llvm-size.cpp
index e422e69f785..89b89f06275 100644
--- a/llvm/tools/llvm-size/llvm-size.cpp
+++ b/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;
diff --git a/llvm/tools/llvm-strings/llvm-strings.cpp b/llvm/tools/llvm-strings/llvm-strings.cpp
index 996610d26b2..51313d73401 100644
--- a/llvm/tools/llvm-strings/llvm-strings.cpp
+++ b/llvm/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))
diff --git a/llvm/tools/llvm-symbolizer/llvm-symbolizer.cpp b/llvm/tools/llvm-symbolizer/llvm-symbolizer.cpp
index 00b8931c740..61a94d67ee0 100644
--- a/llvm/tools/llvm-symbolizer/llvm-symbolizer.cpp
+++ b/llvm/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)