[cmake-developers] Documentation for CMAKE_*_FLAGS_* not homogenous
Eric Noulard
eric.noulard at gmail.com
Mon Nov 12 11:31:44 EST 2012
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
More information about the cmake-developers
mailing list