[cfe-dev] Command line compiler options

[Edward Diener]

On 6/17/2015 12:20 AM, Sean Silva wrote:
>
>
> On Tue, Jun 16, 2015 at 8:44 PM, Justin Bogner <mail at justinbogner.com
> <mailto:mail at justinbogner.com>> wrote:
>
>     Edward Diener <eldlistmailingz at tropicsoft.com
>     <mailto: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
>     <mailto: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.
>
>
> I can't find the bugzilla where I described this, but there's actually
> another problem, which is potentially more serious. Even if we did
> magically have a large body of documentation that covered a lot of these
> gaps, it's not a sure thing that we would want to incorporate this
> content into our docs [1]. The issue is that many of our options are
> specifically there for GCC or MSVC compatibility, so providing an
> independent (duplicated) description of the option opens the door to
> divergence.

As I suggested previously if the documentation for a particular command 
line option merely said that it is the same as the corresponding option 
in gcc or msvc, and then mentioned the actual gcc or msvc compiler 
release which that version of clang was emulating, the end-user could 
then look up the option for gcc or msvc, both pretty readily available 
online.

> Our current rough "policy" of documenting features of clang
> that are not compatibility features (or where they are incompatible in
> some way) is actually pretty economical and in line with SPOT/DRY
> principles. It also means that all of our bug reports are "bug in
> compatibility with GCC/MSVC" and we can asymptotically approach
> compatibility (i.e. fixable with patches). Compare this to "I, a user of
> your compiler, relied on a feature that you documented as behaving in a
> particular way, and now you are changing it" which leaves us between a
> rock and a hard place: stay incompatible with the other compilers or
> break our own compatibility promises (not fixable with patches; we are
> now in the realm of social/political issues). It's an open question
> whether the open-source project wants to risk that support problem, or
> whether there is a safe set of options we can document without worrying
> about this; but arbitrarily thorough documentation essentially turns any
> existing compatibility bugs (or misunderstandings of a GCC/MSVC option
> on the part of the documenter) into potentially "forever" support costs.
>
> [1] suffice it to say I know at least one company that ships a ~100 page
> "C/C++ Compiler Reference" with their clang-based platform toolchain
>
> -- Sean Silva
>
>
>     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.