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

[Eric Noulard]

Le 20 avril 2012 13:40, Nicolas Desprès <nicolas.despres at gmail.com> a écrit :
> 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.

If you go this way then calling:
cmake --help-option-list CMakeLists.txt

will begin the configuration work which does not seem wise if you
simply want to list some help.

I wouldn't personally expect to get some side effect from --help-xxxx.

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

They don't have issue they do not do the same task.
ccmake and cmake-gui (just like cmake) do **PROCESS**
the CMakeLists.txt scripts so that when you push 'c' or 'configure'
cache **file** gets populatedd, any configure_file is done etc...

at least ALL the default case CMakeLists.txt is interpreted.

none of the current  cmake --help-xxxx have any side-effect.

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

ccmake and cmake-gui do a "one time" evaluation of all CMakeLists.txt hierarchy
but do not generate (unlike cmake command) the generator files
(Makefile, project files etc...).
Before that they offer you a chance to further chose "option" or set values for
some variables (CMAKE_INSTALL_PREFIX) etc...

Then if you do mmodify something using the GUI/TUI you can hit
'c/configure' again.
Each time you "configure" ccmake or cmake-gui shows you the "newly
created variables",
which is useful to know because for example after the first run you
ticked an extra option
which triggers the discovery of some program or file etc...which
translates into a new
CMake variable you can spot easily.

As you already guess on the "configure" when you start ccmake/cmake-gui from
an empty cache/build dir you get an "all red/all starred" var on subsequent call
only new vars get displayed this way.

I personally think you cannot implement some "--help-whatever" option
that could possibly
populate (even partially) the build tree, so that building
"--help-whatever" on top on
current functions implemented for ccmake or cmake-gui is a clear no GO.

(as an explanation why it would be bad, for example bash completion
 for cmake uses --help-xxx a lot in order to offer completion
 see: http://www.cmake.org/Bug/view.php?id=13056)

That's my own point of view, but I expect others will give their
opinion as well.
-- 
Erk
Le gouvernement représentatif n'est pas la démocratie --
http://www.le-message.org