2012/4/20 Nicolas Desprès <[email protected]>: > 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. >
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 -- 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
