[cmake-developers] Documentation for CMAKE_*_FLAGS_* not homogenous

[David Cole]

On Mon, Nov 12, 2012 at 2:08 AM, Eric Noulard <eric.noulard at gmail.com> wrote:
> HI there,
>
> While reading the builtin doc for
> CMAKE_<LANG>_FLAGS_<BUILD_TYPE>
> answering a questoin I was surprise by the fact that the documentation for
> the CMAKE_*_FLAGS_*  variable is not very homogenous.
>
> We currently have:
> CMAKE_EXE_LINKER_FLAGS
> CMAKE_EXE_LINKER_FLAGS_[CMAKE_BUILD_TYPE]
> CMAKE_<LANG>_FLAGS_DEBUG
> CMAKE_<LANG>_FLAGS_MINSIZEREL
> CMAKE_<LANG>_FLAGS_RELEASE
> CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
>
>
> Is there any reason we have
> CMAKE_<LANG>_FLAGS_DEBUG
> CMAKE_<LANG>_FLAGS_MINSIZEREL
> CMAKE_<LANG>_FLAGS_RELEASE
> CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
>
> instead of:
> CMAKE_<LANG>_FLAGS_<CMAKE_BUILD_TYPE>
>
> and why do we get:
> CMAKE_EXE_LINKER_FLAGS_[CMAKE_BUILD_TYPE]
>
> and not:
> CMAKE_EXE_LINKER_FLAGS_<CMAKE_BUILD_TYPE>
>
> then what is the relationship between
> CMAKE_EXE_LINKER_FLAGS
> and
> CMAKE_EXE_LINKER_FLAGS_<CMAKE_BUILD_TYPE>
>
> the builtin doc says nothing about it?
>
> Last but not least we do not have documentation for
> CMAKE_<LANG>_FLAGS
>
> even if it is used by many bits of *.cmake files
> and that Wiki
> http://www.cmake.org/Wiki/CMake_Useful_Variables
> says:
> None (CMAKE_C_FLAGS or CMAKE_CXX_FLAGS used)
>
> I think the documentations of all those vars may be improved:
>
> 1) use homogeneous naming

This is a good idea, but obviously, we have to support all the
existing names that we already actually use. In making things
homogeneous, we may add new variables to make them consistent with
others, but still use the old ones if they're defined... It will make
for more clutter in the code. Is it worth it in this case?


> 2) improve doc content and in particular explain their
>     links and reference appropriate properties
>
>        COMPILE_FLAGS
>        COMPILE_DEFINITIONS
>        COMPILE_DEFINITIONS_<CONFIG>
>
>      note again here that we have "<CONFIG>" and not
>      "<CMAKE_BUILD_TYPE>"
>

We should always use "<CONFIG>" in these bits of documentation...
There is no CMAKE_BUILD_TYPE in multi-configuration generators, or
even if there is one by a project's CMakeLists file, the multi-config
generators ignore it, ... but there is the concept of
per-configuration settings.


> I can work on a patch proposal but before doing that I'd like to
> collect feedback/opinion.

You have mine. Hopefully others chime in too...

> Moreover if some of you want to fix that before I thikn about it go ahead :-]
>

Sorry. Probably not this week. :-)


D