[CMake] How to list user-definable CMake variables

[Eric Noulard]

2010/9/28 Marcel Loose <loose at astron.nl>:
>
> On 28. Sep, 2010, at 9:33 , Marcel Loose wrote:
>
>> > Hi all,
>> >
>> > I was wondering how I could generate a list of user-definable CMake
>> > variables. This list, with a brief help per variable, would be
> *very*
>> > useful for the end-user. It's a bit like the well-known "configure
>> > --help" which gives you a overview of all variables that can be set.
>> >
>> > Best regards,
>> > Marcel Loose.
>>
>> Is "cmake -LAH" what you want?
>>
>> Michael
>
> Hi Michael,
>
> Well this is sort of what I was looking for, though I was hoping that it
> would be possible to list any useful variable *before* running CMake.

Before running cmake... I don't know but keep reading.

> Is there some kind of hook, e.g. 'cmake --custom-help', that can be used
> to display project-specific help. The help text should be provided by
> the developer, of course.

You may do the following:

Write an "HelpMe.cmake" file which contains CMake comments
just like plain CMake do (see e.g. CPackRPM.cmake which contains many
variable descriptions)

then add the following custom target to your project:
add_custom_target(HelpMe
  COMMAND  ${CMAKE_COMMAND}
-DCMAKE_MODULE_PATH=${CMAKE_CURRENT_SOURCE_DIR} --help-module HelpMe
  COMMENT "Display User defined help")

this will use the "--help-module" option of cmake to display your custom help.

user can call the target

make HelpMe

and the help will be display.

You may want to call your target "help" but it would conflict/override
the cmake builtin "help" target
(at least for makefile generator) which display the list of available target.

This work AFTER cmake has been run. It could be run before as well using:

cmake -DCMAKE_MODULE_PATH=/path/to/source --help-module HelpMe

but this is awkward :-(

-- 
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org