[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

diff --git a/docs/CommandGuide/llvm-nm.rst b/docs/CommandGuide/llvm-nm.rst
index 4678a7a493d523ebaea212172616250c2656215a..874a184664b63b9ca183e61694569532b9e7d13f 100644 (file)
--- a/docs/CommandGuide/llvm-nm.rst
+++ b/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/docs/CommandGuide/llvm-objdump.rst b/docs/CommandGuide/llvm-objdump.rst
index 24bfe9ee060874f4b1c6ce03c40cdd33e7f756ea..8c81560caa92dff799370cbdbf73b7edc8d1514d 100644 (file)
--- a/docs/CommandGuide/llvm-objdump.rst
+++ b/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/docs/CommandGuide/llvm-readobj.rst b/docs/CommandGuide/llvm-readobj.rst
index 7d4679f2032f5cd3ac3daa02c24930fafccd31be..0e752f731ffce8c6478c7e85c2cdfbe010db690c 100644 (file)
--- a/docs/CommandGuide/llvm-readobj.rst
+++ b/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/docs/CommandGuide/llvm-symbolizer.rst b/docs/CommandGuide/llvm-symbolizer.rst
index 1c31a38ae09267a4424add6b333e00ec947c33d3..7e2f205b34c042f131844e2ec8a06c998af35a9c 100644 (file)
--- a/docs/CommandGuide/llvm-symbolizer.rst
+++ b/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/test/tools/llvm-cxxfilt/help.test b/test/tools/llvm-cxxfilt/help.test
new file mode 100644 (file)
index 0000000..78bfad4
--- /dev/null
+++ b/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/test/tools/llvm-dwarfdump/cmdline.test b/test/tools/llvm-dwarfdump/cmdline.test
index 9aa0a1527b2eff0fd9c6e275c3931273cdfdc9b1..5930e71885070499765d166c1d3eb5eb2b90abcf 100644 (file)
--- a/test/tools/llvm-dwarfdump/cmdline.test
+++ b/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/test/tools/llvm-objdump/help.test b/test/tools/llvm-objdump/help.test
new file mode 100644 (file)
index 0000000..940eea3
--- /dev/null
+++ b/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/test/tools/llvm-readobj/basic.test b/test/tools/llvm-readobj/basic.test
index a08cc10aca7d10e136bda02ef582dd091f0f8914..488a47607323d4a888cf9605235f9a5bc98db4a0 100644 (file)
--- a/test/tools/llvm-readobj/basic.test
+++ b/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/test/tools/llvm-size/help.test b/test/tools/llvm-size/help.test
new file mode 100644 (file)
index 0000000..a7bd6ed
--- /dev/null
+++ b/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/test/tools/llvm-strings/help.test b/test/tools/llvm-strings/help.test
new file mode 100644 (file)
index 0000000..9c3f932
--- /dev/null
+++ b/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/test/tools/llvm-symbolizer/help.test b/test/tools/llvm-symbolizer/help.test
index 5c41fccb64834cb9c1cac0bdf7cdd6b4642b0022..12339463631c2424e86fd2e86ba95b3cceef24bc 100644 (file)
--- a/test/tools/llvm-symbolizer/help.test
+++ b/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/tools/llvm-cxxfilt/llvm-cxxfilt.cpp b/tools/llvm-cxxfilt/llvm-cxxfilt.cpp
index eb84c3e83063ed448d31f901b31b43963c43ff6a..9ac8bcf0ff015da6d8c0a54b2c626c5b33d131bb 100644 (file)
--- a/tools/llvm-cxxfilt/llvm-cxxfilt.cpp
+++ b/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/tools/llvm-dwarfdump/llvm-dwarfdump.cpp b/tools/llvm-dwarfdump/llvm-dwarfdump.cpp
index 701efade286b72e3c53181fdbf814d1820619963..05a7aef67ecedd08bcd0bba58eb2e3f529213eb1 100644 (file)
--- a/tools/llvm-dwarfdump/llvm-dwarfdump.cpp
+++ b/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/tools/llvm-objdump/llvm-objdump.cpp b/tools/llvm-objdump/llvm-objdump.cpp
index 4e8418278922a916fe5165d168a8660fb2423770..fc3acb457e41c333fd74c47fc020585f5207c9f0 100644 (file)
--- a/tools/llvm-objdump/llvm-objdump.cpp
+++ b/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/tools/llvm-readobj/llvm-readobj.cpp b/tools/llvm-readobj/llvm-readobj.cpp
index c040541f82a46d269ecc675d2db9d1cf9bfd6865..31e8bbe1a627aca0404cf0b7fca91398886e77d2 100644 (file)
--- a/tools/llvm-readobj/llvm-readobj.cpp
+++ b/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/tools/llvm-size/llvm-size.cpp b/tools/llvm-size/llvm-size.cpp
index e422e69f78515121c54a498b00988571be2ea9be..89b89f06275084c4d3195e1a2e2b400169b87cdb 100644 (file)
--- a/tools/llvm-size/llvm-size.cpp
+++ b/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/tools/llvm-strings/llvm-strings.cpp b/tools/llvm-strings/llvm-strings.cpp
index 996610d26b26fa20af5a6dcab6c106c80033b56a..51313d73401e220291d94e3683a914309b27c15f 100644 (file)
--- a/tools/llvm-strings/llvm-strings.cpp
+++ b/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/tools/llvm-symbolizer/llvm-symbolizer.cpp b/tools/llvm-symbolizer/llvm-symbolizer.cpp
index 00b8931c740c388faaeabf794b1586ef55e38e9e..61a94d67ee043e72a1b29689894e9e34b6bc7e3f 100644 (file)
--- a/tools/llvm-symbolizer/llvm-symbolizer.cpp
+++ b/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)