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

[David Cole]

2012/4/20 Nicolas Desprès <nicolas.despres at gmail.com>:
> 2012/4/20 David Cole <david.cole at kitware.com>:
>> 2012/4/20 Nicolas Desprès <nicolas.despres at gmail.com>:
>>> 2012/4/20 Eric Noulard <eric.noulard at gmail.com>:
>>>> 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
>>>
>>> I would have say: cmake --help-option-list <builddir> like when you call ccmake.
>>>
>>>>
>>>> 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.
>>>>
>>>
>>> We can name the command line option differently if it is problem.
>>> --build-option-list for instance.
>>>
>>>>> 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...
>>>
>>> Ok. From my understanding, they all do the same job but with a
>>> different user interface:
>>> * cmake: command line
>>> * ccmake: curses
>>> * cmake-gui: gui
>>>
>>> As you have spotted below cmake differs from the others since it does
>>> the configuration and the generation each time it is called.
>>>
>>>>
>>>> at least ALL the default case CMakeLists.txt is interpreted.
>>>
>>> I agree.
>>>
>>>>
>>>> none of the current  cmake --help-xxxx have any side-effect.
>>>
>>> Ok. So, we can name the option differently.
>>>
>>>>
>>>>> 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.
>>>
>>> Ok. Thank you for the clarification. You have spotted interesting
>>> points I did not really think about and mentioned in my first email.
>>>
>>> My main goal is to add to cmake the same features you have in ccmake
>>> and cmake-gui and to ease the users to find out the interesting option
>>> they have to pass to cmake without duplicating the documentation which
>>> is already written in the CMakeLists.txt and the .cmake files. Also
>>> that will provide something more or less similar as what you get with
>>> configure --help when it is generated by autoconf.
>>>
>>> First, let's forget about naming the options --help-XXX since as you
>>> have said they have side effects and could not be used in completion
>>> scripts. Here the workflow, I have in mind:
>>>
>>> $ cd myproject
>>> $ mkdir _build
>>> $ cd _build
>>> $ cmake --build-options ..
>>> # The configuration and generation is performed.
>>> # All the options and their value (including the advanced one? maybe
>>> an extra argument would be necessary here?) are printed and marked
>>> with a * like in ccmake.
>>> $ cmake --build-options .
>>> # The configuration and generation is performed.
>>> # All the options and their value (including the advanced one? maybe
>>> an extra argument would be necessary here?) are printed without the *.
>>>
>>> Now the users know they have to at least set CMAKE_BUILD_TYPE and
>>> CMAKE_INSTALL_PREFIX for instance:
>>>
>>> $ cmake -DCMAKE_BUILD_TYPE=Release
>>> -DCMAKE_INSTALL_PREFIX="$HOME/usr/stow/myproject" .
>>> # The configuration and generation is performed.
>>>
>>> I think you get the idea. This approach does not change the current
>>> behavior of cmake.
>>>
>>> Another approach, if we want to mimic more ccmake and cmake-gui, would
>>> be to add --configure and --generate flags. They should be used only
>>> when one of the --build-option* flag is present, in order to keep the
>>> default current behavior. The behavior of --configure and --generate
>>> would be the same as pushing respectively the "configure" and
>>> "generate" button in cmake-gui. So, the workflow will look like:
>>>
>>> $ cd myproject
>>> $ mkdir _build
>>> $ cd _build
>>> $ cmake --build-options .
>>> CMake Error: The source directory "/home/despre_n/open-src/cmake/_b"
>>> does not appear to contain CMakeLists.txt.
>>> Specify --help for usage, or press the help button on the CMake GUI.
>>> $ cmake --build-options ..
>>> Empty cache.
>>> Please configure first by specifying --configure.
>>> $ cmake --build-options --configure ..
>>> [...]
>>> -- Configuring done
>>> Build options available in this project:
>>> (* mark newly created variables ; you can set this options using the -D flag)
>>>
>>> FOO*:BOOL=''
>>>       Foo documentation
>>> CMAKE_BUILD_TYPE*:STRING=''
>>>       Choose the type of build, options are: None(CMAKE_CXX_FLAGS or
>>> CMAKE_C_FLAGS are used)
>>>       Debug Release RelWithDebInfo MinSizeRel
>>> $ cmake -DCMAKE_BUILD_TYPE=Debug --build-options .
>>> Build options available in this project:
>>> (* mark newly created variables ; you can set this options using the -D flag)
>>>
>>> FOO*:BOOL=''
>>>       Foo documentation
>>> CMAKE_BUILD_TYPE*:STRING='Debug'
>>>       Choose the type of build, options are: None(CMAKE_CXX_FLAGS or
>>> CMAKE_C_FLAGS are used)
>>>       Debug Release RelWithDebInfo MinSizeRel
>>> $ cmake --configure .
>>> [...]
>>> -- Configuring done
>>> $ cmake --build-options .
>>> Build options available in this project:
>>> (* mark newly created variables ; you can set this options using the -D flag)
>>>
>>> FOO:BOOL=''
>>>       Foo documentation
>>> CMAKE_BUILD_TYPE:STRING='Debug'
>>>       Choose the type of build, options are: None(CMAKE_CXX_FLAGS or
>>> CMAKE_C_FLAGS are used)
>>>       Debug Release RelWithDebInfo MinSizeRel
>>> $ cmake --generate .
>>> -- Generating done
>>> -- Build files have been written to: <path to the build directory>
>>>
>>> What do you think of these approaches?
>>>
>>> --
>>> Nicolas Desprès
>>> --
>>>
>>> Powered by www.kitware.com
>>>
>>> Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
>>>
>>> Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ
>>>
>>> Follow this link to subscribe/unsubscribe:
>>> http://www.cmake.org/mailman/listinfo/cmake
>>
>>
>> Don't spend too much effort/time on this without gathering a good
>> consensus first, because I think we'll be unlikely to accept a patch
>> that simply documents every darn thing under the sun. Only the
>> project-specific things should be documented in project-specific help.
>>
>
> That's why I have posted this email before to start coding :-).
>
>> These are good ideas, but the problem that we've identified and never
>> figured out a good way around is that you'll end up with incomplete
>> project documentation in this manner. Think about how options and
>> variable set commands may be hidden inside if/else constructs that do
>> not get processed, or subdirectories that are completely optional and
>> do not get traversed. (We've had verbal discussions about this very
>> thing for YEARS now... not sure if there are any mailing list
>> discussions on archive about it.)
>>
>
> Are you suggesting that ccmake and cmake-gui do not do the "right" job?
>
>> In my opinion, it would be better to have a mode of processing the
>> CMakeLists files that gathers the relevant documentation strings from
>> ALL occurrences of set, option and any other commands that have doc
>> strings attached to them, for ALL POSSIBLE cmake code paths, and then
>> cache the documentation after doing such processing. That is a
>> completely different beast than the processor that we currently have
>> in place, but it would produce complete project documentation.
>>
>
> Sounds really interesting but very intrusive in the parser at the same
> time. Do the nodes of the abstract syntax tree accept a visitor? It
> could helps implementing such things in a non-intrusive way. Others
> languages like Emacs lisp or Python (I'm not sure about the last one)
> already provide documentation embedded into the code. Maybe we could
> have a look at how they deal with that issue.
>
>> Another alternative would be to have projects specify their own help
>> in a yet-to-be-invented form, and then be able to reference that help
>> from the various set and option commands throughout their CMakeLists
>> files. Perhaps a ProjectHelp.cmake file, with certain variables set in
>> it, those variables indicating what other variables to document, such
>> file to be included in the CMakeLists file? That would be better, in
>> my opinion, because it would allow project authors to filter out stuff
>> that they DON'T want documented.
>>
>
> Marking variables as internal or advanced isn't enough for saying "do
> not document me for the end-user"?
> Or do you mean something like: document(VAR1 VAR2 VAR3)?
>
> Actually, my goal is just to brought to the cmake command line
> interface exactly the same kind of features ccmake and cmake-gui
> already have. Do you think it is too ambitious and/or would never
> work? My coworkers and I are happy with the current behavior of ccmake
> and cmake-gui. I just want to have the same feature in cmake for being
> able to | grep things and scripts other stuff and also because I
> prefer the command line interface rather than any interactive
> interface for this task.
>

All of the stuff that is visible as documentation strings in the
cmake-gui and ccmake interfaces should be available after a configure
step in the CMakeCache.txt. Some grep-ping with a few lines of context
should prove to you that the documentation you seek for cache
variables is easily available after configure. A re-arrangement of
what's there (or a grep it out and re-display it in your desired
format) should be quite possible already.


> Thank you for your feedback.
>
> --
> Nicolas Desprès