[CMake] Add --help-option command line option.

[Nicolas Desprès]

2012/4/20 Eric Noulard <eric.noulard at gmail.com>:
> Le 20 avril 2012 10:44, Nicolas Desprès <nicolas.despres at gmail.com> a écrit :
>> Hi,
>>
>> I would like to have your opinion before to start to implement it.
>>
>> I would like to add the following options to the cmake command line interface:
>> --help-option opt [file]   = Print help for a given option and exit.
>> --help-option-list [file]  = List available options and exit.
>> --help-options [file]      = Print help for all options and exit.
>>
>> The goal is to have access to the project build options from the
>> command line interface like you can see them in ccmake and cmake-gui.
>> Advanced variable will be marked as such, of course. The output will
>> be similar to --help-variable* options.
>>
>> I have noticed that most cmake based projects document their options
>> in their README file whereas the documentation is already included in
>> cmake when you call the option() and set() commands. I hope this
>> feature will help to remove this duplication and people will just
>> write in their README file a "see cmake --help-options for available
>> build options".
>>
>> Comments?
>
> I think that Enabling/Designing some way to document user written CMake scripts
> is a very interesting goal.
>

Thanks.

> I started doing something along that line using basic markup, which has been
> used to improve CPack documentation (--help-variable and
> --help-command) in 2.8.8.
> see: http://www.cmake.org/Bug/bug_relationship_graph.php?bug_id=10067
Thanks for the pointer. Indeed, it is nice piece of work.
>
> My approach does not need to actually "parse" CMake script but only to
> catch comment line blocks.
> I say that because the problem with options is that
> you may need to parse **AND EVALUATE** some CMake script code
> in order to know whether if the OPTION is active or not.
>
> See e.g.
> cmake --help-module CMakeDependentOption

Thanks for the pointer. I was not aware of this module.

>
> So how would grab the documentation from OPTION or CMAKE_DEPENDENT_OPTION?
>
> 1a) Read out the provided CMake [file]  and custom parse  OPTION  and
> CMAKE_DEPENDENT_OPTION ?
> (possibly disregarding the control flow like OPTION inside IF(WIN32),
> IF(APPLE) etc...) ?
>
> 1b) Evaluate the CMakeLists.txt as ccmake and make-gui do?
>
> 2) Would you also handle "INCLUDE" and handle OPTION find in there as well?
>
> I think that a full parse (as done by ccmake and/or cmake-gui) is not
> easy at all.
> I'd suggest to parse OPTION (and CMAKE_DEPENDENT_OPTION) found in any
> CMakeLists.txt recursively, beginning with the one given on the command line,
> i.e. 1a) + recursion without 2).
>
> The main problem with this approach (be it recursive or not) is that you may
> list options which are platform dependent and/or conditionally evaluated.
>
> Another way to go is to require an extra ##option markup (in any
> script including CMakeLists.txt)
> that could be placed anywhere but ideally just before the real
> "OPTION/CMAKE_DEPENDENT_OPTION" statement.
> That way you can parse it the way I did for CPack doc without the need
> for any kind of CMake
> script evaluation.
> I know this duplicate the "comment" somehow, but it would give to the
> developer a mean to
> have more control concerning what is shown and what is not shown in
> terms of documentation.
>
> Using this scheme we can imagine some "unified" way to get user doc
> from user file (CMakeLists.txt or any *.cmake):
>
> --help-user-list <file>  --> list any user documented item from file
> (variable, command/macro, option, property etc...)
> --help-user <file>       --> dump all user doc whatever the category
>
> we can imagine some way to filter out the category we want
>
> --help-user-list <file> option
> --help-user <file> option <optionname>
> --help-user <file> variable <varname>
>
> etc...
>

First of all thanks for replying. Although, that's an interesting
approach, I find it quite complex. Actually, I haven't dug into the
source code yet but what I had in mind was to basically/naively do the
same job that is done by ccmake and cmake-gui. I think (I haven't
checked yet) the code is already factored in some way, so I could just
call the right functions.

That's said. Maybe ccmake and cmake-gui have some issues I am not
aware of and your approach try to address them.

One thing I forgot to mention in my first email is the handling of
variables marked as red in cmake-gui and with a * in ccmake. Honestly,
I have never really understood the logic behind this feature, but
again I think all that code is factored.

Cheers,

-- 
Nicolas Desprès