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

[Eric Noulard]

2012/11/12 David Cole <david.cole at kitware.com>:
> 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?

May be I wasn't that clear.
My proposal is to fix the naming scheme **in the documentation**
not the name of the actual variables which are just fine I think.

i.e.
replace doc of
CMAKE_<LANG>_FLAGS_DEBUG
CMAKE_<LANG>_FLAGS_MINSIZEREL
CMAKE_<LANG>_FLAGS_RELEASE
CMAKE_<LANG>_FLAGS_RELWITHDEBINFO

with generic and improved doc for:
CMAKE_<LANG>_FLAGS_<CONFIG>


then replace doc of:
CMAKE_EXE_LINKER_FLAGS_[CMAKE_BUILD_TYPE]
with
CMAKE_EXE_LINKER_FLAGS_<CONFIG>

Unless both  "CMAKE_BUILD_TYPE" and "CONFIG" are used in
generator expression already?

>> 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.

OK then the doc should not contain

"CMAKE_EXE_LINKER_FLAGS_[CMAKE_BUILD_TYPE]"

but

"CMAKE_EXE_LINKER_FLAGS_<CONFIG>"

>> 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. :-)
>

I do not ensure any time line but since it's only "doc fix" it should
be relatively
easy to test & review.


-- 
Erk
Le gouvernement représentatif n'est pas la démocratie --
http://www.le-message.org