[cfe-dev] Command line compiler options

[Justin Bogner]

Edward Diener <eldlistmailingz at tropicsoft.com> writes:
> On 6/16/2015 1:01 PM, Konstantin Tokarev wrote:
>>
>>
>> 16.06.2015, 19:55, "Edward Diener" <eldlistmailingz at tropicsoft.com>:
>>> For any given version of clang, including the latest, is there any list
>>> of command-line compiler options, with their meanings, which clang accepts ?
>>
>> clang --help
>> clang -cc1 --help
>> clang -cc1 -mllvm --help
>
> Here is the explanation from "clang --help" of the -std option:
>
> -std=<value>            Language standard to compile for
>
> Incredible ! I did not realize how much vital information can be
> packed into command-line help until I read the explanation.

The sarcasm isn't necessary. See Reid's response - we know this is a
problem, and it has been for years.

Clang does not currently document its command line even remotely
sufficiently. We have "clang --help" and the clang user's manual, which
are both helpful but neither of which is really satisfactory.

The problem, as I see it, is that nobody has really stepped up to just
write a thorough manual of what is available. We've often had
discussions of how to automate writing this (through tablegen or
otherwise), but these tend to lead to these two important results:

1. Nobody's willing to do the work to design and implement something
   satisfactory.

2. Several people point out that automated documentation tends not to be
   as readable and clear as hand-written output.

AFAICT, the simplest and most likely to actually happen solution is for
someone to repurpose the users manual into something a bit more suitable
for a man page and expand on the parts where this is lacking. If and
when this document is thorough about the options in clang, it will come
naturally in code review to tell people to update the manual when they
make changes to the command line interface. Also, this should be way
easier now, with the recent discussion of moving the existing man page
to sphinx/RST.

The main argument against this that I've heard is something to the
effect of "Duplicating this information from tablegen is terrible!" or
"But this will lead to `clang --help` being wildly different from the
man page!". I find it unlikely that either of these will be a real
problem in practice, and when balanced against the fact that no one has
ever stepped up to actually try to automate the problem I can't really
see how they'd be worse than the status quo.

So, sorry for the rant, but if you have time to incorporate whatever's
missing from today's man page into the user's manual, or just to improve
what's in the user's manual to be a better man page, please do. I'd
strongly support this direction, and I'd certainly try to help out if we
actually start working on this.