Notes
(0021691) Eric NOULARD (developer) 2010-08-08 11:44	The explanation given here, deserve to be put in CPack.cmake http://www.cmake.org/pipermail/cmake/2010-August/038831.html [^]

(0021822) Mike McQuaid (reporter) 2010-08-19 03:54	I don't think 'cpack --help-module' would be transparent enough at all. Compare: http://www.cmake.org/cmake/help/cmake-2-8-docs.html [^] To: http://www.cmake.org/cmake/help/cpack-2-8-docs.html [^] There's basically nothing there. I'd like to see a comprehensive list of all the variables and what they do, the information from the CPack.cmake module, a description of what variables affect what modules, a description of the component-based install system, as a start. Again, look at: http://www.cmake.org/Wiki/CMake:CPackConfiguration [^] http://www.cmake.org/Wiki/CMake:CPackPackageGenerators [^] http://www.cmake.org/Wiki/CMake:Component_Install_With_CPack [^] Wikis are great but they aren't easily findable from the application or as easily findable as the actual documentation in Google. They also aren't always authoritative or correct. I really think this should have a higher priority than normal. I've done several talks at open-source conferences where I've promoted CPack (e.g. the Gran Canaria Desktop Summit) but no-one is interested in it when they look at the documentation and find out how lacking it is. I've resorted to telling people to just email me if they want help using it, as so much of CPack is inaccessible. If you want people to actually use CPack and attract more contributors to improve it, I think this documentation needs to match or exceed that of CMake. At the moment, the documentation is so sparse as to be basically useless.

(0021823) Mike McQuaid (reporter) 2010-08-19 03:56	Just so I don't come off as whining here, if there's a way to improve CPack's documentation generation to include some of the above information, let me know what I should do and I'll try and write a patch to help out. I really want CPack to be more popular, it's great and there seems to be nothing else quite like it.

(0021827) Eric NOULARD (developer) 2010-08-19 04:59	Mike, I'm basically OK with you when you say that CPack is lacking documentation. I'm ok too to say that Wiki is not "enough" because - they may not be easily findable - THEY tend to go outdated very fast when source code evolve. Thus my proposal to first put documentation inside the source. In CMake/CPack there is two "usual" places for that: - inside C++ source for the "builtin" - inside .cmake files for module like extension I'd rather begin with the second because it seems easier to maintain (because anyone can write doc without C++ knowledge) and well suited for CPack because we can have 1 file per generator. You said that 'cpack --help-module' won't be "transparent" at all. What do you mean by that? My proposal was to mimic the cmake --help-module for cpack with cpack --help-generator. cpack --help-generator CPack would give you the "generic help" cpack --help-generator RPM would give you the RPM specific help Do you think this wouldn't be "transparent" enough, what have you in mind? Did you try cmake --help-module CPack and cmake --help-module CPackRPM What do you think of the output you get? (besides the fact that CPack give you both generic and specific informations)

(0021828) Mike McQuaid (reporter) 2010-08-19 05:01	The --help-module documentation is great, I just mean that --help and the manpage and the website should included all that information rather than the empty version we have now. I think we both agree here :)

(0021829) Eric NOULARD (developer) 2010-08-19 05:22	Ok then, I'm not in charge of this bug (and don't want to be for now) but I think that if you want to contribute you could begin by collecting all valuable information about CPack and put: Generic information into CPack.cmake Specific information into CPack<GEN>.cmake I think we may even create some CPackTutorial.cmake or CPackComponent.cmake which are not related to any specific CPack generator. Then immediately (with current cmake executable) cmake --help-module CPackXXX.cmake will give you the doc. Afterwards (or at the same time) you can work on a patch for CPack executable itself that may handle more "doc related" options: --help-generator XXX which would give the same infos as cmake --help-module CPackXXX.cmake --help-generator-list would give the list of available XXXX --help-full option which would which would collate all CPackXXX.cmake documentation. May be David can give its point of view regarding those proposal?

(0021830) Eric NOULARD (developer) 2010-08-19 05:24	Concerning the improvement of the http://www.cmake.org/cmake/help/cpack-2-8-docs.html [^] it could be replaced with the output of --help-full or some --help-full-html (if it is doable to implement this).

(0021831) David Cole (manager) 2010-08-19 06:59	I agree with everything you guys are discussing in the notes here... Furthermore, cpack and ctest are both woefully behind w.r.t. official built-in documentation when compared to cmake. CMake's --help output includes all of these: --help-command cmd [file] = Print help for a single command and exit. --help-command-list [file] = List available listfile commands and exit. --help-commands [file] = Print help for all commands and exit. --help-module module [file] = Print help for a single module and exit. --help-module-list [file] = List available modules and exit. --help-modules [file] = Print help for all modules and exit. --help-property prop [file] = Print help for a single property and exit. --help-property-list [file] = List available properties and exit. --help-properties [file] = Print help for all properties and exit. --help-variable var [file] = Print help for a single variable and exit. --help-variable-list [file] = List documented variables and exit. --help-variables [file] = Print help for all variables and exit. CPack and CTest should follow suit, especially w.r.t. cpack and ctest-specific commands, modules, variables, and properties. It's a very large task, and one that should be undertaken with the understanding that it's going to take a fair bit of effort to bring cpack and ctest up to par. The vision/goal should be this (in my opinion): All 12 of the above --help-* command line switches should be implemented equally and uniformly in cmake, ctest, cpack, ccmake and cmake-gui. And if we add a --help-generator option to cpack, we should do the same in CMake. :-)

(0021832) Mike McQuaid (reporter) 2010-08-19 07:07	I agree totally David. I think this is something that, if there are stubs, you can probably get volunteers to help. Also, I could help generate some stubs for this. However, I'd imagine this is going to be mostly up to Kitware to sort out. As I said, I think better documentation could massively increase the CPack usebase.

(0026285) Oliver Buchtala (reporter) 2011-04-29 09:14	I agree too - especially about uniform solution. Has a decision been taken about generating documentation from source-code or from cmake files? IMO, first is better for built-ins as it is local. But, latter has the advantage that it is only one mechanism.

(0026585) David Cole (manager) 2011-05-25 16:46	Not for 2.8.5 - postponing until a future release

(0027732) Eric NOULARD (developer) 2011-11-05 16:50	I'm currently working on this. As a start I intend to provide --help-command cmd [file] = Print help for a single command and exit. --help-command-list [file] = List available listfile commands and exit. --help-commands [file] = Print help for all commands and exit. and --help-variable var [file] = Print help for a single variable and exit. --help-variable-list [file] = List documented variables and exit. --help-variables [file] = Print help for all variables and exit. I have something locally but I'm wondering how to get cmake.[h\|cxx] a little less CMake-ish or better to separate common part for ctest/cmake/cpack. For example the variables documentation predefined section which are builting privately from this->InitializeProperties are too CMake-oriented. Moreover the corresponding section are builtin cmDocumentation constructor: this->VariableSections.push_back("Variables that Provide Information"); this->VariableSections.push_back("Variables That Change Behavior"); this->VariableSections.push_back("Variables That Describe the System"); this->VariableSections.push_back("Variables that Control the Build"); this->VariableSections.push_back("Variables for Languages"); I'd like to re-use cmDocumentation with less CMake-oriented doc section. Any advise along that line?

(0027793) Eric NOULARD (developer) 2011-11-13 16:56	Just merged my proposal to next: Fetching upstream next Merge topic 'ImproveCPackDoc' into next ab6c9c0 Update cmake bash completion file. 1e38d6d CPack begin the implementation of --help-command* and --help-variables* 893ac5c Document undocumented (but existing) cpack options (fix 0010134) The documentation is far from complete but this initial patch set should makes it easier to get doc contrib since the files: cmCPackDocumentMacros.cxx cmCPackDocumentVariables.cxx contains two examples for variables (one for common var, one for generator specific var) and one example for a cpack "command", which is in fact a macro. Adding more should now be matter of patience and time for anybody. For this reason I think this could be merged to master.

(0027794) Eric NOULARD (developer) 2011-11-13 17:05	In CPack most "command" are in fact macros defined in CPack.cmake CPackComponent.cmake or other CPack.cmake files. It will be painful to re-type the documentation from this modules inside the C++ code. Moreover once it's done the documentation may diverge which is bad. May be we can add some markup in those cmake script file in order to extract documentation of those macros from the actual cmake script file. Then most CPack documentation could be extracted from CPack.cmake files and stay up to date. This parsing technique could be used to parse user macro file as well.

(0027803) Eric NOULARD (developer) 2011-11-15 16:53	I did describe a proposal for markup addition here http://public.kitware.com/pipermail/cmake-developers/2011-November/002536.html [^] This is very basic but may already be useful. Feedback wanted.

(0028138) Eric NOULARD (developer) 2012-01-02 19:09	Hi all, Just updated my proposal for enhancing CPack (and other) documentation. The documentation of variables, macros and functions may be extracted from a CMake script using a primitive builtin parser, which creates documentation entries directly from the file. The branch is stage/ImproveCPackDoc. [This branch cannot currently be merged to next because it started before the 2.8.7 release.] Please checkout the branch and try cpack --help-variable-list cpack --help-command-list and e.g. cpack --help-command cpack_add_component or cpack --help-variable CPACK_RPM_CHANGELOG_FILE cpack --help-variable CPACK_PACKAGE_VENDOR

(0028388) Eric NOULARD (developer) 2012-01-22 07:51	Hi everybody, I did just push "stage/ImproveCPackDoc-reloaded". I did rebased my previous work on current master. I did some enhancement. This is far from finished but if we agree on the principle this could enable others to work on documentation in parallel. Going on cmake-devel for discussion.

(0028433) Eric NOULARD (developer) 2012-01-31 10:17	From the discussion on the ML, this is worth a merge to next: Fetching upstream next Merge topic 'ImproveCPackDoc-reloaded' into next 62b589b Suppress unused var, beautify code, avoid 1 extra newline. 751713f Update bash completion file in order to handle new CPack doc options. 1629615 CPack Documentation extraction from CMake script begins to work 83e34dd Implement simple CMake script comment markup language. c6a0169 CPack begin the implementation of --help-command* and --help-variables* Auto-merging Source/cmake.cxx Pushing upstream next To git@cmake.org:cmake.git

(0028484) Eric NOULARD (developer) 2012-02-05 18:32	I did push the branch a little further. The CPack doc feature I want to put in is there I think. Once/if this is merged I'll work on a more complete doc of every CPack variables common or specific to a generator.

(0028722) Eric NOULARD (developer) 2012-02-25 17:45	Small messages for the listeners who monitor this bug. cpack --help-command-xxx cpack --help-variable-xxx are now in master. I am gradually updating the documentations for all cpack variables. Around 100+ CPack -(generic or generator specific variables) are already accessible. Most of them are now documented in CPack<GENNAME>.cmake scripts which are automatically parsed for documentation extraction by cpack --help-xxx invocation. Please review all the CPack variables you use for your favorite generators and report missing variables or errors and/or provide a patch for fixing/enhancing the documentation. Command/macro may be documented as well see examples in CPackComponent.cmake.

(0029088) Eric NOULARD (developer) 2012-04-06 10:42	The main work for CPack doc improvement is in latest 2.8.8rc Some more work will be done, but we can already close this bug.

Issue History
Date Modified	Username	Field	Change
2009-12-18 15:18	Eric NOULARD	New Issue
2009-12-18 15:34	David Cole	Status	new => assigned
2009-12-18 15:34	David Cole	Assigned To	=> David Cole
2010-08-08 11:44	Eric NOULARD	Note Added: 0021691
2010-08-19 03:54	Mike McQuaid	Note Added: 0021822
2010-08-19 03:56	Mike McQuaid	Note Added: 0021823
2010-08-19 04:59	Eric NOULARD	Note Added: 0021827
2010-08-19 05:01	Mike McQuaid	Note Added: 0021828
2010-08-19 05:22	Eric NOULARD	Note Added: 0021829
2010-08-19 05:24	Eric NOULARD	Note Added: 0021830
2010-08-19 06:59	David Cole	Note Added: 0021831
2010-08-19 07:07	Mike McQuaid	Note Added: 0021832
2010-12-14 19:03	David Cole	Relationship added	related to 0010134
2011-01-18 14:12	David Cole	Relationship added	related to 0010392
2011-02-27 17:31	Eric NOULARD	Relationship added	related to 0010751
2011-04-14 14:29	David Cole	Target Version	=> CMake 2.8.5
2011-04-29 09:14	Oliver Buchtala	Note Added: 0026285
2011-05-25 16:46	David Cole	Note Added: 0026585
2011-05-25 16:46	David Cole	Target Version	CMake 2.8.5 =>
2011-10-26 00:00	David Cole	Assigned To	David Cole =>
2011-10-26 00:00	David Cole	Status	assigned => backlog
2011-11-05 16:36	Eric NOULARD	Assigned To	=> Eric NOULARD
2011-11-05 16:36	Eric NOULARD	Status	backlog => assigned
2011-11-05 16:50	Eric NOULARD	Note Added: 0027732
2011-11-13 16:56	Eric NOULARD	Note Added: 0027793
2011-11-13 17:05	Eric NOULARD	Note Added: 0027794
2011-11-15 16:53	Eric NOULARD	Note Added: 0027803
2012-01-02 19:01	Eric NOULARD	Platform	=> All
2012-01-02 19:01	Eric NOULARD	Target Version	=> CMake 2.8.8
2012-01-02 19:09	Eric NOULARD	Note Added: 0028138
2012-01-22 07:51	Eric NOULARD	Note Added: 0028388
2012-01-31 10:17	Eric NOULARD	Note Added: 0028433
2012-02-05 18:32	Eric NOULARD	Note Added: 0028484
2012-02-25 17:45	Eric NOULARD	Note Added: 0028722
2012-04-06 10:42	Eric NOULARD	Note Added: 0029088
2012-04-06 10:42	Eric NOULARD	Status	assigned => closed
2012-04-06 10:42	Eric NOULARD	Resolution	open => fixed
2012-04-06 10:42	Eric NOULARD	Fixed in Version	=> CMake 2.8.8