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

[Eric Noulard]

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.

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

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

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



-- 
Erk
Le gouvernement représentatif n'est pas la démocratie --
http://www.le-message.org