llvm dev - Jul 2019 - RFC: llvm-readelf Mach-O & COFF options

My personal preference is that llvm-readelf only show the elf related
options with -help and show all with -help-hidden. There is support for
this in CommandLine.h, but I don't know how tricky it gets when we don't
want them to be hidden for llvm-readobj. I haven't looked into this fully.

For some reference, I have compiled how the other alias tools are handled.
Many of these are aliases to llvm-ar, it is helpful to know that llvm-ar
doesn't use CommandLine.h to parse its options.

llvm-addr2line -> llvm-symbolizer: help is the same, docs mention it is an
alias and only note the differences between it and llvm-symbolizer.
llvm-dlltool -> llvm-ar: help is different and -help-hidden changes
nothing. I couldn't find docs for llvm-dlltool.
llvm-lib -> llvm-ar: *no* help option for llvm-lib. The docs don't even
have a see also for ar.
llvm-ranlib -> llvm-ar: help is different. Docs mention it is an alias and
note the differences.
llvm-strip -> llvm-objcopy: help is slightly different. Docs do not mention
it is an alias.

The lack of a pattern makes some sense given different tools will have
different requirements. Perhaps a useless widening of the scope of your
question then. But back to your question, I personally think that a man
page has the room to include _hidden_ options and don't see any benefit in
excluding them. I also think it makes sense to mention it is an alias in
the man page because it is a little curious otherwise why something called
readelf has so many options for non elf files, in my opinion.

Best,
Alex
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190629/bcc044c5/attachment.html>

Hi Alex,

It's worth noting that the "alias" nature is really an
implementation
detail of the tools. There is nothing stopping us within the build process
producing a completely separate executable (indeed, I think, though I'm not
certain, that essentially this is what happens on Windows). Some tools
(e.g. llvm-strip and llvm-objcopy) intentionally have a different set of
options, and indeed the other options aren't even available.

I personally am against having "hidden" options documented in either
form.
They should be either hidden in all forms or nowhere (except possibly
--help-hidden). Hidden options should, in my opinion, be limited to a)
options that are irrelevant to the tool, b) options that are experimental
and not ready for use, or c) options intended only for those in the know
about how to use them. I'd argue that the llvm-readelf Mach-O/COFF options
fall under a), since llvm-readelf is intended to be a GNU readelf
equivalent, which doesn't support these switches, and they don't have
any
use for ELF objects. Users who wish to dump Mach-O and COFF output should
be using llvm-readobj. Additionally, as noted in my original email, many
people will be migrating from GNU readelf to llvm-readelf, and may find the
large number of extra switches irrelevant, making it harder to interpret
the help output.

James

On Sat, 29 Jun 2019 at 07:28, Alex Brachet-Mialot <
alexbrachetmialot at gmail.com> wrote:
> My personal preference is that llvm-readelf only show the elf related
> options with -help and show all with -help-hidden. There is support for
> this in CommandLine.h, but I don't know how tricky it gets when we
don't
> want them to be hidden for llvm-readobj. I haven't looked into this
fully.
>
> For some reference, I have compiled how the other alias tools are handled.
> Many of these are aliases to llvm-ar, it is helpful to know that llvm-ar
> doesn't use CommandLine.h to parse its options.
>
> llvm-addr2line -> llvm-symbolizer: help is the same, docs mention it is
an
> alias and only note the differences between it and llvm-symbolizer.
> llvm-dlltool -> llvm-ar: help is different and -help-hidden changes
> nothing. I couldn't find docs for llvm-dlltool.
> llvm-lib -> llvm-ar: *no* help option for llvm-lib. The docs don't
even
> have a see also for ar.
> llvm-ranlib -> llvm-ar: help is different. Docs mention it is an alias
and
> note the differences.
> llvm-strip -> llvm-objcopy: help is slightly different. Docs do not
> mention it is an alias.
>
> The lack of a pattern makes some sense given different tools will have
> different requirements. Perhaps a useless widening of the scope of your
> question then. But back to your question, I personally think that a man
> page has the room to include _hidden_ options and don't see any benefit
in
> excluding them. I also think it makes sense to mention it is an alias in
> the man page because it is a little curious otherwise why something called
> readelf has so many options for non elf files, in my opinion.
>
> Best,
> Alex
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190701/5b11ea84/attachment.html>

llvm-readelf should not show any non-ELF options and should probably fail
on non-ELF input IMO.

There are two things preventing this. One is the build system and the other
is the is the options parsing code. The options parsing code isn't very
amenable to having different options and help messages for different
aliases. It is actually possible to dynamically allocate the options so
it's not impossible but it's a hassle and I'm not sure that it's
what we
want to do. Switching over to TableGen. +Petr Hosek <phosek at google.com>
my
local CMake expert wasn't able to figure out how to build multiple tools in
the same tool repo to allow for easy code sharing at the time we made
llvm-strip. He might know now however. This too has a workaround I think
because you can import code from parallel directories it's just not really
a path that's ideal to go down. I think we need to support `llvm-readobj
-elf-output-style=GNU` no matter what and it would be ideal if
`llvm-readelf` where consistent with that so at the very least we want the
same code to be used to do the printing for both. What options are used or
output is another story. We have multiple ways to make the options and help
messages different but all of them are headache's IMO.

If we do solve this then we should take this opportunity to fix issues with
things like `--dyn-syms` to make the two tools properly command line
compatible which is an issue I personally hit a lot when I switch between
using `llvm-readelf` and `readelf`

On Mon, Jul 1, 2019 at 2:55 AM James Henderson via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> Hi Alex,
>
> It's worth noting that the "alias" nature is really an
implementation
> detail of the tools. There is nothing stopping us within the build process
> producing a completely separate executable (indeed, I think, though I'm
not
> certain, that essentially this is what happens on Windows). Some tools
> (e.g. llvm-strip and llvm-objcopy) intentionally have a different set of
> options, and indeed the other options aren't even available.
>
> I personally am against having "hidden" options documented in
either form.
> They should be either hidden in all forms or nowhere (except possibly
> --help-hidden). Hidden options should, in my opinion, be limited to a)
> options that are irrelevant to the tool, b) options that are experimental
> and not ready for use, or c) options intended only for those in the know
> about how to use them. I'd argue that the llvm-readelf Mach-O/COFF
options
> fall under a), since llvm-readelf is intended to be a GNU readelf
> equivalent, which doesn't support these switches, and they don't
have any
> use for ELF objects. Users who wish to dump Mach-O and COFF output should
> be using llvm-readobj. Additionally, as noted in my original email, many
> people will be migrating from GNU readelf to llvm-readelf, and may find the
> large number of extra switches irrelevant, making it harder to interpret
> the help output.
>
> James
>
> On Sat, 29 Jun 2019 at 07:28, Alex Brachet-Mialot <
> alexbrachetmialot at gmail.com> wrote:
>
>> My personal preference is that llvm-readelf only show the elf related
>> options with -help and show all with -help-hidden. There is support for
>> this in CommandLine.h, but I don't know how tricky it gets when we
don't
>> want them to be hidden for llvm-readobj. I haven't looked into this
fully.
>>
>> For some reference, I have compiled how the other alias tools are
>> handled. Many of these are aliases to llvm-ar, it is helpful to know
that
>> llvm-ar doesn't use CommandLine.h to parse its options.
>>
>> llvm-addr2line -> llvm-symbolizer: help is the same, docs mention it
is
>> an alias and only note the differences between it and llvm-symbolizer.
>> llvm-dlltool -> llvm-ar: help is different and -help-hidden changes
>> nothing. I couldn't find docs for llvm-dlltool.
>> llvm-lib -> llvm-ar: *no* help option for llvm-lib. The docs
don't even
>> have a see also for ar.
>> llvm-ranlib -> llvm-ar: help is different. Docs mention it is an
alias
>> and note the differences.
>> llvm-strip -> llvm-objcopy: help is slightly different. Docs do not
>> mention it is an alias.
>>
>> The lack of a pattern makes some sense given different tools will have
>> different requirements. Perhaps a useless widening of the scope of your
>> question then. But back to your question, I personally think that a man
>> page has the room to include _hidden_ options and don't see any
benefit in
>> excluding them. I also think it makes sense to mention it is an alias
in
>> the man page because it is a little curious otherwise why something
called
>> readelf has so many options for non elf files, in my opinion.
>>
>> Best,
>> Alex
>>
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190701/d75333c1/attachment.html>