[CMake] How to list user-definable CMake variables

[Marcel Loose]

On Tue, 2010-09-28 at 10:42 +0200, Eric Noulard wrote:
> 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 :-(
> 
Thanks Erk,

I'll give it a thought. Your solution uses some nice CMake features, but
I find it a bit awkward. It suffers from separation of code and
documentation, though. That's always risky, since the two are likely to
diverge.

Best regards,
Marcel Loose.