[cfe-dev] Command line compiler options

[Sean Silva]

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

> Sean Silva <chisophugis at gmail.com> writes:
> > On Tue, Jun 16, 2015 at 8:44 PM, Justin Bogner <mail at justinbogner.com>
> wrote:
> >> 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.
>
> The answer to "How do you use clang?" in 2009 was "man gcc". It was cute
> then, but it's embarrasing now.
>

"The implementation of this {GCC,MSVC} option in our {GCC,MSVC} compatible
driver follows that of {GCC,MSVC}  documented here: <link>". That's not
embarrassing IMO.

-- Sean Silva



>
> > 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.
>
> DRY is about implementing software. Trying to apply it to documentation
> inevitably leads to terrible documentation, in my experience.
>

> > 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).
>
> I don't necessarily disagree with you here, at least in the sense that I
> don't think we should document (for example) every gcc extension we
> implement in great detail. The issue at hand is the smaller question of
> "what flags does clang accept?". The answer today is "all of the gcc
> ones! Oh, but some of them do nothing, or aren't accepted at all. And
> there are clang specific ones - I think we documented a few of those in
> the clang user's manual, maybe."
>
> We can document which flags a particular version of clang accepts
> without stating "we implement feature X, it works exacly like blah, and
> we promise to support it forever". We can mitigate misunderstandings by
> stating that particular options are for compatibility when that's all
> they exist for, and I don't see why bugs in the documentation should be
> treated differently than any other bug.
>
> > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20150617/5d3f12f0/attachment.html>