Command line compiler options

For any given version of clang, including the latest, is there any list of command-line compiler options, with their meanings, which clang accepts ?

http://clang.llvm.org/docs/UsersManual.html

Contains a section called “command line options”, which to my reading is complete.

Typing clang --help will give you a list of the options that particular version of clang supports, with short descriptions of what each option does.

Unfortunately, it’s only encoded in the source. =/ At some point I would like it if we could do write a tablegen backend to generate such documentation.

And of course, the older versions of the documentation is available like this:
http://llvm.org/releases/3.6.0/tools/clang/docs/UsersManual.html

Substitute 3.6.0 for whatever version you want - although it seems to stop at 3.3 (no zero on the end!)

[There are older version of docs here: http://llvm.org/releases/ - but if you go back far enough, it’s no longer called clang!]

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

http://clang.llvm.org/docs/UsersManual.html
<https://urldefense.proofpoint.com/v2/url?u=http-3A__clang.llvm.org_docs_UsersManual.html&d=AwMFaQ&c=8hUWFZcy2Z-Za5rBPlktOQ&r=CnzuN65ENJ1H9py9XLiRvC_UQz6u3oG6GUNn7_wosSM&m=zLEOq-VXwfpKNAdAkHqmSyTnsvQ2AnIbGowAWxUJokM&s=hWs1GmrmaTNo439zan_9XGonCIqx-VXI1-9c6gmmm1U&e=&gt;
Contains a section called "command line options", which to my reading is
complete.

It is not even remotely complete, for any clang release. As very simple example of this try finding out what -std= options are available for C++.

Typing `clang --help` will give you a list of the options that
particular version of clang supports, with short descriptions of what
each option does.

I will try that for the latest version I have built.

Unfortunately that does no good for earlier versions of clang I may not have but about which I need to find out what it supported.

Unfortunately, it's only encoded in the source. =/ At some point I would
like it if we could do write a tablegen backend to generate such
documentation.

Thanks ! Clang really does need to document for each release the full set of command-line options it supports in its documentation. If it supports, for any given clang release, the exact same option as gcc it would only need to specify the release of gcc to which that option corresponds, since documentation for gcc command-line options for any given gcc major.minor release is readily available.

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.

I have used clang and it's a great compiler but if you do not want to be badgered by continual questions in your mailing list about how clang actual works when used by an end-user I would suggest that clang actually spend some time telling programmers how to use their product. The "Clang Compiler User’s Manual" is not that documentation if a programmer must spend hours of his time just to find out what the values and their meanings are which the "-std" option takes for any given version of clang, including the latest.

If only the compiler could document itself :slight_smile:

On a more serious note, patches in this area are more than welcome. It took
me some time to realize this, but people working on clang are mostly
employed by companies that want them to work on whatever's important to
them. This means that those people know exactly how to use the compiler. If
you're buying a product based on clang then you can request the company
that's selling it to provide documentation. But for you, me and everyone
else using the open source compiler it means that anything we see missing
we'll have to do ourselves or just wait until someone gets to it, if they
do. I'm sure you'll find out the list of possible values for -std switch,
why not contribute a patch documenting them once you do?

On a personal note, I find your tone unacceptable if you expect a
productive discussion. I understand your frustration as I've been there
many times but you have to understand that people in this community are
doing their best and are aware of shortcomings, which is why patches are
more than welcome.

Edward Diener <eldlistmailingz@tropicsoft.com> writes:

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.

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.

Edward Diener <eldlistmailingz@tropicsoft.com> writes:
>>
>>
>>> 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

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.

I have used clang and it's a great compiler but if you do not want to be
badgered by continual questions in your mailing list about how clang actual
works when used by an end-user I would suggest that clang actually spend
some time telling programmers how to use their product. The "Clang Compiler
User’s Manual" is not that documentation if a programmer must spend hours
of his time just to find out what the values and their meanings are which
the "-std" option takes for any given version of clang, including the
latest.

The standard answer is to look at GCC's documentation, since you are using
our gcc-compatible driver (or Microsoft's documentation if your are using
our cl.exe compatible driver). Feel free to report any compatibility issues.

-- Sean Silva

Sean Silva <chisophugis@gmail.com> writes:

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.

Couldn't this problem be avoided by linking to the appropriate spots in the
GCC/MSVC documentation whenever clang provides a features that is supposed to
be exactly the same as the corresponding feature in the other compilers?

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.

Of course another problem for example with -std=X is that “full support for X is not implied by X being a valid choice” - -std=c++11 would be available as a valid option for quite some time before the actual C++11 standard support was complete - because people were working TOWARDS complete support. Similarly, using clang to compile CL2.0 is allowed with -cl-std=CL2.0, but that doesn’t mean that the current trunk branch is supporting all features of CL2.0 - but you can’t offer the support at all, if you don’t have a way to specify it, and it gets rather messing having to add an option -std=c++11-incomplete, and then when it’s complete, change that into c++11 (in particular, there may be 100s of tests that need to be updated for this]

I have no suggestion as to how to solve this.

Auto-generated support is probably more maintainable than relying on people writing separate documentation, but it is still relying on the people writing the code to accept the option to write good descriptions that make sense [and those reviewing it spotting when it’s not up to date].

Of course, you also have to keep those descriptions up to date when things change - e.g. optimization settings may change over time, so the listing of “-O2 enables ” would have to be kept up to date. That sort of information is often a bit tricky to find.

    I would suggest that clang actually spend some time telling
    programmers how to use their product.

If only the compiler could document itself :slight_smile:

On a more serious note, patches in this area are more than welcome. It
took me some time to realize this, but people working on clang are
mostly employed by companies that want them to work on whatever's
important to them. This means that those people know exactly how to use
the compiler. If you're buying a product based on clang then you can
request the company that's selling it to provide documentation. But for
you, me and everyone else using the open source compiler it means that
anything we see missing we'll have to do ourselves or just wait until
someone gets to it, if they do. I'm sure you'll find out the list of
possible values for -std switch, why not contribute a patch documenting
them once you do?

I am not a clang contributor. I do use clang when testing Boost libraries and I am appreciative of the clang support I get here.

On a personal note, I find your tone unacceptable if you expect a
productive discussion.

My "humor" was borne out of frustration. I need to know not only about the latest clang, but previous versions, because Boost supports many versions of many compilers in most of its libraries. I understand that clang developers work on the compiler itself and that documentation gets overlooked. But no matter how good the compiler is, if an end-user has a hard time using it because documentation is poor or entirely lacking in some areas, how much good will the product be to end-users ?

    Edward Diener <eldlistmailingz@tropicsoft.com
    <mailto:eldlistmailingz@tropicsoft.com>>
    writes:
    >>
    >> 16.06.2015, 19:55, "Edward Diener" <eldlistmailingz@tropicsoft.com
    <mailto:eldlistmailingz@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.

Which version of gcc ? That is my point. Even documentation saying which version of gcc a particular version of clang's functionality is emulating is something I have not found in any clang docs. Gcc options do change per gcc release, as to what are acceptable values, as I am sure you know.

Couldn't this problem be avoided by linking to the appropriate spots in the
GCC/MSVC documentation whenever clang provides a features that is supposed to
be exactly the same as the corresponding feature in the other compilers?

Or at the least specifying which version of gcc/msvc is being emulated for any specific version of clang. The gcc or msvc documentation for any version can be found online. But options and what values they accept do sometimes change between releases.

As my previous comment said, I’m not entirely sure that simply having command line options documented is sufficient to solve the type or problem that (I think) you are trying to solve: What options does compiler version X, Y and Z support, and what option do I need to use to get access to compiler feature F, G or H. Because, as I said, compiler option may say “-std=support for C++11” (or C99, or whatever), but it doesn’t mean that a particular version FULLY supports that standard (unless you are actually expecting something like “-std=C++11 enabled C++11 standard complience - version X supports all C++11 features {,except} [list of features {,not} supported]”.

I’m not saying the current documentation is great, but I’m not sue that your quest will immediately be solved by having better documentation of the command line options alone. You still need to read other documentation items to understand exactly what is supported and what is not.

And even then you still have the issue that “feature X is supported” in the documentation, but due to some bug or limitation in the compiler, stuff doesn’t work. So to say that “compiler version X works for ” will still be dependent on testing with EXACTLY compiler version X in some way, to ensure that for all supported targets, for all supported options, the code generated by the compiler works correctly. This is very hard to maintain good test coverage on, and gets increasingly worse with the number of supported configurations…