[llvm-dwarfdump] Add -o to help text and remove --out-file from documentation

[jhenderson]

Summary

-o is in the documentation, but not in the llvm-dwarfdump help text. This patch adds it by inverting the -o and --out-file aliasing. It also removes --out-file from the help text, since we don't really want people to be using this switch in practice.

[aprantl]

I'm mildly against this change. IIRC, the idea was that --out-file is a long-form option that nobody uses in practice and we wanted people to prefer -o instead, which is what people are most familiar with working with compilers. So if -o shows up in the --help output, I'd leave it at that.

[aprantl]

That said, if clang also documents -o as --out-file, I think consistency wins.

[jhenderson]

Just checked clang, and its documentation and help text both mention '-o' and not '--out-file' or another equivalent long-form. I'm happy to change this to expose the '-o' option and replace '--out-file' in the documentation with '-o', if you think that's wise? I don't think we want inconsistency between the help text and documentation.

[JDevlieghere]

+1 on making -o the canonical argument and the out-file the alias.

[jhenderson]

Remove --out-file from documentation and replace in help text with -o.

[jhenderson]

In D63013#1535260, @aprantl wrote:

I'm mildly against this change. IIRC, the idea was that --out-file is a long-form option that nobody uses in practice and we wanted people to prefer -o instead, which is what people are most familiar with working with compilers. So if -o shows up in the --help output, I'd leave it at that.

Could we just delete --out-file, if we don't want people to use it?

[aprantl]

In D63013#1536440, @jhenderson wrote:

In D63013#1535260, @aprantl wrote:

I'm mildly against this change. IIRC, the idea was that --out-file is a long-form option that nobody uses in practice and we wanted people to prefer -o instead, which is what people are most familiar with working with compilers. So if -o shows up in the --help output, I'd leave it at that.

Could we just delete --out-file, if we don't want people to use it?

Not any more, I'm afraid :-)
Once an option is out there we will no doubt get complaints that we broke somebody's scripts if we remove it.

[dblaikie]

In D63013#1537125, @aprantl wrote:

In D63013#1536440, @jhenderson wrote:

In D63013#1535260, @aprantl wrote:

I'm mildly against this change. IIRC, the idea was that --out-file is a long-form option that nobody uses in practice and we wanted people to prefer -o instead, which is what people are most familiar with working with compilers. So if -o shows up in the --help output, I'd leave it at that.

Could we just delete --out-file, if we don't want people to use it?

Not any more, I'm afraid :-)
Once an option is out there we will no doubt get complaints that we broke somebody's scripts if we remove it.

(I'd be in favor of removing it, if it doesn't serve much purpose - does anyone know the history of why it was added?)

We've changed the behavior of llvm-dwarfdump pretty significantly over the years (these days it prints with coloured output, only dumping debug_info by default, and in non-verbose mode (skipping forms and other things)) - it's a fairly "compiler/debugger developer centric tool" which is a small enough audience we've been pretty comfortable making usability improvements even if they'd break some kind of compatibility.

[aprantl]

dwarfdump(-classic) on macOS also supported the --out-file option and on macOS we strive for compatibility with the older tool.

[dblaikie]

In D63013#1537212, @aprantl wrote:

dwarfdump(-classic) on macOS also supported the --out-file option and on macOS we strive for compatibility with the older tool.

Fair enough - good to know!

[jhenderson]

In D63013#1537212, @aprantl wrote:

dwarfdump(-classic) on macOS also supported the --out-file option and on macOS we strive for compatibility with the older tool.

Okay, I'm convinced! I'll go and land this now then.

docs/CommandGuide/llvm-dwarfdump.rst

.. option:: -n <pattern>, --name=<pattern>
             <pattern> become a regular expression for more flexible
             pattern matching.
 
 .. option:: --lookup=<address>
 
             Lookup <address> in the debug information and print out the file,
             function, block, and line table details.
 
-.. option:: -o <path>, --out-file=<path>
+.. option:: -o <path>
 
             Redirect output to a file specified by <path>.
 
 .. option:: -p, --show-parents
 
             Show a debug info entry's parent objects when using the
             :option:`--debug-info`, :option:`--find`, and
             :option:`--name` options.

test/tools/llvm-dwarfdump/cmdline.test

-RUN: llvm-dwarfdump -h 2>&1 | FileCheck --check-prefix=HELP %s
-RUN: llvm-dwarfdump --help 2>&1 | FileCheck --check-prefix=HELP %s
+RUN: llvm-dwarfdump -h 2>&1 | FileCheck --check-prefix=HELP %s --implicit-check-not=out-file
+RUN: llvm-dwarfdump --help 2>&1 | FileCheck --check-prefix=HELP %s --implicit-check-not=out-file
 HELP: USAGE: llvm-dwarfdump{{[^ ]*}} [options] <input object files or .dSYM bundles>
 HELP-NOT: -reverse-iterate
 HELP: Color Options
 HELP: -color
 HELP: Section-specific Dump Options
 HELP: -debug-info            - Dump the .debug_info section
 HELP: -eh-frame
 HELP: Specific Options
 HELP: -diff
 HELP: -find
 HELP: -ignore-case
 HELP: -lookup
 HELP: -name
+HELP: -o=<filename>
 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-NOT: -reverse-iterate
 
 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

tools/llvm-dwarfdump/llvm-dwarfdump.cpp

static list<std::string> Name(
     value_desc("pattern"), cat(DwarfDumpCategory));
 static alias NameAlias("n", desc("Alias for -name"), aliasopt(Name));
 static opt<uint64_t>
     Lookup("lookup",
            desc("Lookup <address> in the debug information and print out any "
                 "available file, function, block and line table details."),
            value_desc("address"), cat(DwarfDumpCategory));
 static opt<std::string>
-    OutputFilename("out-file", cl::init("-"),
+    OutputFilename("o", cl::init("-"),
                    cl::desc("Redirect output to the specified file."),
-                   cl::value_desc("filename"));
-static alias OutputFilenameAlias("o", desc("Alias for -out-file."),
-                                 aliasopt(OutputFilename),
-                                 cat(DwarfDumpCategory));
+                   cl::value_desc("filename"), cat(DwarfDumpCategory));
+static alias OutputFilenameAlias("out-file", desc("Alias for -o."),
+                                 aliasopt(OutputFilename));
 static opt<bool>
     UseRegex("regex",
              desc("Treat any <pattern> strings as regular expressions when "
                   "searching instead of just as an exact string match."),
              cat(DwarfDumpCategory));
 static alias RegexAlias("x", desc("Alias for -regex"), aliasopt(UseRegex));
 static opt<bool>
     ShowChildren("show-children",