Strictly appending to CMAKE_<LANG>_FLAGS

[mrjoel (Joel Johnson)]

@brad.king

our particular CI jobs in some cases use incremental build areas, which makes the environment variable approach insufficient (since it’s only used during the first configuration).

Please explain that use case in more detail. Are you trying to append to the current CMAKE_CXX_FLAGS value in an existing CMakeCache.txt, reconfigure, and build again?

Precisely - we have jobs in CI (Jenkins in this particular case, but also GitLab CI) for quick-turn checks of multiple branches which use ccache, incremental builds, and provide user-facing options/parameters which internally result in changing effective C++ compiler options (e.g. warning-as-error, optimization level, etc.). A single job builds with all of MSVC, gcc, and clang, so we convert the single job parameter into the compiler-specific options. There is obviously a separate build area for each compiler, but multiple build areas are driven by a single job with distinct parallel stages.

We want to be able to switch branches and compilation options, then on a subsequent incremental build minimize needed rebuilds as well as use applicable results from ccache’s cache (typically only branch churn in subsets of the overall codebase). This works fine now that we’ve added the tailored application of WIN32 on targets where needed. However due to the WIN32 default vs. non-default special casing it seemed excessively complicated or at least non-intuitive. In particular, using CXXFLAGS was insufficient since it is only considered on initial build area creation, and not subsequent reexecutions of cmake with different options for our incremental builds.

@brad.king

CXXFLAGS is the official way to say “use default flags plus these”.

As I explained in the linked CMake Issue 23956, the difference between CMAKE_CXX_FLAGS and CXXFLAGS is intentional.

Fair point, and I’d even mentioned (somewhere?) that it may be a documentation clarification. The usage of CMAKE_CXX_FLAGS overriding the env var is completely sensical.

@brad.king

the default value for [CMAKE_CXX_FLAGS] is taken from a combination of builtin flags and the CXXFLAGS environment variable.

This is the crux of what I didn’t find clear in the documentation and may perhaps be worth a tweak. The docs simply indicate that CXXFLAGS is used “to determine CXX default compilation flags, after which the value for CXXFLAGS is stored in the cache as CMAKE_CXX_FLAGS”. To my reading:

• there isn’t a clear distinction that the behavior is different. The implications behind “to determine CXX flags” are at best subtle. I read “to determine” (now knowing incorrectly) as “determines” or “specifies”, rather than “merged with/appended to possibly other internal flags” indicating it’s only part of the resultant whole.
• This is further emphasized and seemingly reinforced by “the value for CXXFLAGS is stored in the cache as CMAKE_CXX_FLAGS” rather then something like “the resultant determined value (including CXXFLAGS) is store in the cache…”
• The combination of the above points seemed to falsely reinforce my understanding that the usage of CXXFLAGS and CMAKE_CXX_FLAGS were equivalent, with the former only serving as an alternate environment-based mechanism to seed the latter.

Hopefully this helps clarify and make sense of my perspective when working through it. If it’d be useful I’d be happy to draft a doc patch.