[cfe-dev] Command line compiler options

[Sean Silva]

On Tue, Jun 16, 2015 at 8:44 PM, Justin Bogner <mail at justinbogner.com>
wrote:

> 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.
>

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. 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.
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20150616/15e37d7d/attachment.html>