[CMake] What are the best way to set project-wide compiler flags?

[Todd Greer]

Hi,

My development team and I have struggled with what should be a simple question: what is the best way to add project-wide compiler flags?
As background, we develop C++ software that builds for Windows, Mac, and several different Linux platforms. For a given platform, the set of compiler flags should be consistent, and under source control.

Here are the ways I've seen from the documentation and miscellaneous sources:
1. add_definitions function
2. COMPILE_FLAGS property
3. CMAKE_CXX_FLAGS / CMAKE_<lang>_FLAGS cache variable

If you read the reference documentation (http://www.cmake.org/cmake/help/v2.8.10/cmake.html), the clear winner is add_definitions. It's the only thing documented to apply to all configurations, and it specifically states that it "can be used to add any flags," even though "it was originally intended to add preprocessor definitions." The COMPILE_FLAGS property works as well, but has to be set for each target. CMAKE_<lang>_FLAGS isn't mentioned at all there, (though its configuration-specific versions are), but it's often discussed in postings.

It seems clear that we should use add_definitions, except that there are so many posts various places saying *not* to use add_definitions for flags. Unfortunately, I've never seen an explanation of why. 

So, which should I trust: the reference documentation, or the several people who say differently? If add_definitions is bad for flags, why is that? 

Thank you,
Todd Greer
Principal Scientist, Affinegy, Inc.