[cfe-dev] Command line compiler options

[Justin Bogner]

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.

> 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