2012/4/20 David Cole <[email protected]>: > 2012/4/20 Nicolas Desprès <[email protected]>: >> 2012/4/20 Eric Noulard <[email protected]>: >>> Le 20 avril 2012 13:40, Nicolas Desprès <[email protected]> a écrit >>> : >>>> 2012/4/20 Eric Noulard <[email protected]>: >>>>> Le 20 avril 2012 10:44, Nicolas Desprès <[email protected]> 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. Thank you for your feedback. -- 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
