<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Jun 16, 2015 at 8:44 PM, Justin Bogner <span dir="ltr"><<a href="mailto:mail@justinbogner.com" target="_blank">mail@justinbogner.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">Edward Diener <<a href="mailto:eldlistmailingz@tropicsoft.com">eldlistmailingz@tropicsoft.com</a>> writes:<br>
> On 6/16/2015 1:01 PM, Konstantin Tokarev wrote:<br>
>><br>
>><br>
>> 16.06.2015, 19:55, "Edward Diener" <<a href="mailto:eldlistmailingz@tropicsoft.com">eldlistmailingz@tropicsoft.com</a>>:<br>
>>> For any given version of clang, including the latest, is there any list<br>
>>> of command-line compiler options, with their meanings, which clang accepts ?<br>
>><br>
>> clang --help<br>
>> clang -cc1 --help<br>
>> clang -cc1 -mllvm --help<br>
><br>
> Here is the explanation from "clang --help" of the -std option:<br>
><br>
> -std=<value>            Language standard to compile for<br>
><br>
> Incredible ! I did not realize how much vital information can be<br>
> packed into command-line help until I read the explanation.<br>
<br>
</span>The sarcasm isn't necessary. See Reid's response - we know this is a<br>
problem, and it has been for years.<br>
<br>
Clang does not currently document its command line even remotely<br>
sufficiently. We have "clang --help" and the clang user's manual, which<br>
are both helpful but neither of which is really satisfactory.<br>
<br>
The problem, as I see it, is that nobody has really stepped up to just<br>
write a thorough manual of what is available. We've often had<br>
discussions of how to automate writing this (through tablegen or<br>
otherwise), but these tend to lead to these two important results:<br>
<br>
1. Nobody's willing to do the work to design and implement something<br>
   satisfactory.<br>
<br>
2. Several people point out that automated documentation tends not to be<br>
   as readable and clear as hand-written output.<br></blockquote><div><br></div><div>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.</div><div><br></div><div>[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<br></div><div><br></div><div>-- Sean Silva</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
AFAICT, the simplest and most likely to actually happen solution is for<br>
someone to repurpose the users manual into something a bit more suitable<br>
for a man page and expand on the parts where this is lacking. If and<br>
when this document is thorough about the options in clang, it will come<br>
naturally in code review to tell people to update the manual when they<br>
make changes to the command line interface. Also, this should be way<br>
easier now, with the recent discussion of moving the existing man page<br>
to sphinx/RST.<br>
<br>
The main argument against this that I've heard is something to the<br>
effect of "Duplicating this information from tablegen is terrible!" or<br>
"But this will lead to `clang --help` being wildly different from the<br>
man page!". I find it unlikely that either of these will be a real<br>
problem in practice, and when balanced against the fact that no one has<br>
ever stepped up to actually try to automate the problem I can't really<br>
see how they'd be worse than the status quo.<br>
<br>
So, sorry for the rant, but if you have time to incorporate whatever's<br>
missing from today's man page into the user's manual, or just to improve<br>
what's in the user's manual to be a better man page, please do. I'd<br>
strongly support this direction, and I'd certainly try to help out if we<br>
actually start working on this.<br>
<div class=""><div class="h5">_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" rel="noreferrer" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
</div></div></blockquote></div><br></div></div>