2012/4/20 David Cole <david.c...@kitware.com>: > 2012/4/20 Nicolas Desprès <nicolas.desp...@gmail.com>: >> 2012/4/20 David Cole <david.c...@kitware.com>: >>> 2012/4/20 Nicolas Desprès <nicolas.desp...@gmail.com>: >>>> 2012/4/20 Eric Noulard <eric.noul...@gmail.com>: >>>>> Le 20 avril 2012 13:40, Nicolas Desprès <nicolas.desp...@gmail.com> a >>>>> écrit : >>>>>> 2012/4/20 Eric Noulard <eric.noul...@gmail.com>: >>>>>>> Le 20 avril 2012 10:44, Nicolas Desprès <nicolas.desp...@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. >
That's what I already do actually, but I wanted something more user friendly. Anyway, I give up. Now I'm convinced that only a static approach as you and Eric suggested that generate the part of the README I don't want to see duplicated would work. Cheers, -- 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