Page MenuHomePhabricator

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

Authored by jhenderson on Jun 7 2019, 10:00 AM.

Details

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.

Diff Detail

Repository
rL LLVM

Event Timeline

jhenderson created this revision.Jun 7 2019, 10:00 AM
Herald added a project: Restricted Project. · View Herald TranscriptJun 7 2019, 10:01 AM
Herald added a subscriber: aprantl. · View Herald Transcript

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.

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

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.

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

jhenderson retitled this revision from [llvm-dwarfdump] Add --out-file to help text to [llvm-dwarfdump] Add -o to help text and remove --out-file from documentation.
jhenderson edited the summary of this revision. (Show Details)
jhenderson added a reviewer: aprantl.

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

jhenderson edited the summary of this revision. (Show Details)Jun 10 2019, 9:50 AM

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 accepted this revision.Jun 10 2019, 4:12 PM

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.

This revision is now accepted and ready to land.Jun 10 2019, 4:12 PM

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.

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

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!

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.

This revision was automatically updated to reflect the committed changes.