Document optimization flags

[54aefcd4-c07d-4252-8441-723563c8826f]

Bugzilla Link	20543
Version	trunk
OS	All
CC	@pogo59,@rnk,@silvasean

Extended Description

I have tried to find documentation about the optimization flags available in the current version of clang (ToT) without much success (both in the webpage, the manual, and google). Google always points me to: http://clang.llvm.org/docs/UsersManual.html but I see no information there regarding optimization levels/flags.

I'm particularly interested in:

• which optimization flags are there and a description of what they do (e.g. -ffast-math),

• which optimization levels are there (e.g. O2) and which flags does each level enable,

• which potentially-useful but unstable/not supported llvm optimization options are there (e.g. -mllvm -inline-threshold=value has a large impact on performance [0]) and a link to the llvm docs that describe them.

I asked this in the mailing list [1] but no answers so far. Anyhow, even if this is already documented somewhere it should be easier to find than it is now.

[0] http://www.reddit.com/r/cpp/comments/24663s/range_comprehensions/ch46dye [1] http://lists.cs.uiuc.edu/pipermail/cfe-users/2014-July/000541.html

[silvasean]

These flags do wildly different things. Some don't even affect the execution speed of the compiled program (e.g. -pipe, which theoretically just affects how the sub-tasks of the compiler driver communicate with each other).

This is exactly why I think they should be documented somewhere. There is a lot of misconceptions about them.

Can you give a concrete example? Does anybody have the misconception that -pipe will make their program faster?

It seems like what you are asking for is more "everything I can possibly tweak on the compiler command line to see if it affects performance". Is that correct?

I'm asking here is for a page listing all optimization-related flags.

Ok, that sounds doable. Can you start a discussion on cfe-dev to refine exactly what will go in the document? There are some options like -fassume-sane-operator-new that can affect performance but don't affect the optimizer per se (that is, it just controls the behavior of the frontend and the IR it generates, but doesn't actually configure the optimizer differently).

A page listing all flags that the compiler can take (e.g. not only those that are optimization related) would also be valuable (e.g. for things like -pipe). And of course, a page about "everything I can possibly tweak on the compiler command line" that might affect performance would be also valuable.

Things like -DNDEBUG isn't even an "optimization command line option", it's just -D for a macro of special significance.

Yes. There is no place for it on a page documenting the optimization-related flags of a compiler but it should be in a page about "everything I can possibly tweak on the compiler command line that might affect performance".

There isn't really a good place for that in our docs, since usually such macros affect things that are not part of the compiler (e.g. they opt into a faster but backwards-incompatible implementation of some aspect of the standard library).

I personally think its a bit silly to document -DNDEBUG since we can assume that the user already knows about this and aren't tweaking performance on +Asserts builds.

I can't really think what a page "everything I can possibly tweak on the compiler command line that might affect performance" would have besides the relevant optimization flags (which you are proposing as a page by itself), so I'm not sure sure a "everything I can possibly tweak on the compiler command line that might affect performance" page even makes sense.

-mllvm is special in that it essentially passes command line options directly to the LLVM optimizer, which is unstable and should not be relied upon for backwards compatibility! If you really want to know the options it accepts then look at what the opt tool accepts. If a user is really "willing to go this far" then they should use clang's -emit-llvm option and do their optimization through opt. (NOT RECOMMENDED!)

Just mentioning that one can pass flags to the LLVM optimizer directly and linking its documentation (or the documentation of its flags) should be enough. One should definitely mention that tinkering with these is not recommended for the reasons you mention above. In a page about "everything I can possibly tweak" one could mention some of them but keeping these in sync with the LLVM optimizer docs is too much work (users can go to their docs directly as you said).

There isn't anywhere to link to though, as these flags are not documented anywhere since they are in general implementation details (actually the fact that inline-threshold is set globally with a flag could be considered a bug; this behavior is fundamentally at odds with the design of LLVM's optimizer).

[54aefcd4-c07d-4252-8441-723563c8826f]

These flags do wildly different things. Some don't even affect the execution speed of the compiled program (e.g. -pipe, which theoretically just affects how the sub-tasks of the compiler driver communicate with each other).

This is exactly why I think they should be documented somewhere. There is a lot of misconceptions about them.

It seems like what you are asking for is more "everything I can possibly tweak on the compiler command line to see if it affects performance". Is that correct?

I'm asking here is for a page listing all optimization-related flags. A page listing all flags that the compiler can take (e.g. not only those that are optimization related) would also be valuable (e.g. for things like -pipe). And of course, a page about "everything I can possibly tweak on the compiler command line" that might affect performance would be also valuable.

Things like -DNDEBUG isn't even an "optimization command line option", it's just -D for a macro of special significance.

Yes. There is no place for it on a page documenting the optimization-related flags of a compiler but it should be in a page about "everything I can possibly tweak on the compiler command line that might affect performance".

-mllvm is special in that it essentially passes command line options directly to the LLVM optimizer, which is unstable and should not be relied upon for backwards compatibility! If you really want to know the options it accepts then look at what the opt tool accepts. If a user is really "willing to go this far" then they should use clang's -emit-llvm option and do their optimization through opt. (NOT RECOMMENDED!)

Just mentioning that one can pass flags to the LLVM optimizer directly and linking its documentation (or the documentation of its flags) should be enough. One should definitely mention that tinkering with these is not recommended for the reasons you mention above. In a page about "everything I can possibly tweak" one could mention some of them but keeping these in sync with the LLVM optimizer docs is too much work (users can go to their docs directly as you said).

[silvasean]

Any documentation about the available flags would be greatly appreciated. For instance I'm also using -march=native, -mtune=native, -pipe, -fdata-sections, -ffunction-sections, -fvectorize, and -fslp-vectorize-aggressive (and well -DNDEBUG..) but I don't know if these flags do anything or if there are other flags that I should be using instead.

These flags do wildly different things. Some don't even affect the execution speed of the compiled program (e.g. -pipe, which theoretically just affects how the sub-tasks of the compiler driver communicate with each other). Things like -DNDEBUG isn't even an "optimization command line option", it's just -D for a macro of special significance.

It seems like what you are asking for is more "everything I can possibly tweak on the compiler command line to see if it affects performance". Is that correct?

A bonus would be including a section about other flags that you can tune through the clang front-end (like potentially useful llvm flags) and to forward the user to the corresponding documentation (e.g. llvm docs). I think that a list of these options is very valuable and can save a lot of time to some users willing to go this far. In the previously mentioned "micro benchmark" tunning -mllvm -inline-threshold reduced execution time by 4x...

-mllvm is special in that it essentially passes command line options directly to the LLVM optimizer, which is unstable and should not be relied upon for backwards compatibility! If you really want to know the options it accepts then look at what the opt tool accepts. If a user is really "willing to go this far" then they should use clang's -emit-llvm option and do their optimization through opt. (NOT RECOMMENDED!)

[54aefcd4-c07d-4252-8441-723563c8826f]

Any documentation about the available flags would be greatly appreciated. For instance I'm also using -march=native, -mtune=native, -pipe, -fdata-sections, -ffunction-sections, -fvectorize, and -fslp-vectorize-aggressive (and well -DNDEBUG..) but I don't know if these flags do anything or if there are other flags that I should be using instead.

A bonus would be including a section about other flags that you can tune through the clang front-end (like potentially useful llvm flags) and to forward the user to the corresponding documentation (e.g. llvm docs). I think that a list of these options is very valuable and can save a lot of time to some users willing to go this far. In the previously mentioned "micro benchmark" tunning -mllvm -inline-threshold reduced execution time by 4x...

[rnk]

We generally only have high-level optimization flags, like -flto, -O, -ffast-math, and -fstrict-aliasing. We could document these. I don't think we will ever document options in -mllvm, though.

[54aefcd4-c07d-4252-8441-723563c8826f]

It would also be nice to know:

• which optimization flags are there for gcc compatibility only but do nothing.

[gonzalobg]

Blast from the past.

I have an application that produces correct results with gcc -Ofast, but incorrect results with clang -Ofast, but correct results with clang -O3 and all fast-math flags but one. The shortcout of using -Ofast -fno-that-one-flag however produces incorrect results, so my conclusion is that -Ofast is not "-O3 -ffast-math" in clang. I searched the clang docs to try to find out what -Ofast does without much luck. I was going to open a doc bug, but found out that my past self did that almost 10 years ago.

It would be nice to document - like GCC documents - what the -O flags do. Knowing that would be helpful when initially triaging bugs that could be either in the user program, in a broken optimization, or in the user assumption that some optimization that's safe, actually is not.