MantisBT - CMake
View Issue Details
0010067CMakeCPackpublic2009-12-18 15:182012-04-06 10:42
Eric NOULARD 
Eric NOULARD 
normalfeaturealways
closedfixed 
All
CMake-2-8 
CMake 2.8.8CMake 2.8.8 
0010067: Improve CPack documentation
CPack documentation is currently relatively sparse and incomplete.
We should find a way to improve it.

Somes ideas are:

put documentation for each CPack XXX generator in a
CPackXXX.cmake file.
This way documentation could be seen with:

cmake --help-module CPackXXX
in fact this is currently done for

CPack
CPackRPM
CPackDeb

we may generalize this way of documenting CPack.
moreover It would be easier to find the doc if some cpack command option
like

cpack --help-generator XXX would give the same information as
corresponding
cmake --help-module CPackXXX
No tags attached.
related to 0010134closed Eric NOULARD cpack -V command line argument not documented 
related to 0010392closed Zach Mullen CTest variables are not documented 
related to 0010751closed Kitware Robot CPack.cmake confused when used twice 
Issue History
2009-12-18 15:18Eric NOULARDNew Issue
2009-12-18 15:34David ColeStatusnew => assigned
2009-12-18 15:34David ColeAssigned To => David Cole
2010-08-08 11:44Eric NOULARDNote Added: 0021691
2010-08-19 03:54Mike McQuaidNote Added: 0021822
2010-08-19 03:56Mike McQuaidNote Added: 0021823
2010-08-19 04:59Eric NOULARDNote Added: 0021827
2010-08-19 05:01Mike McQuaidNote Added: 0021828
2010-08-19 05:22Eric NOULARDNote Added: 0021829
2010-08-19 05:24Eric NOULARDNote Added: 0021830
2010-08-19 06:59David ColeNote Added: 0021831
2010-08-19 07:07Mike McQuaidNote Added: 0021832
2010-12-14 19:03David ColeRelationship addedrelated to 0010134
2011-01-18 14:12David ColeRelationship addedrelated to 0010392
2011-02-27 17:31Eric NOULARDRelationship addedrelated to 0010751
2011-04-14 14:29David ColeTarget Version => CMake 2.8.5
2011-04-29 09:14Oliver BuchtalaNote Added: 0026285
2011-05-25 16:46David ColeNote Added: 0026585
2011-05-25 16:46David ColeTarget VersionCMake 2.8.5 =>
2011-10-26 00:00David ColeAssigned ToDavid Cole =>
2011-10-26 00:00David ColeStatusassigned => backlog
2011-11-05 16:36Eric NOULARDAssigned To => Eric NOULARD
2011-11-05 16:36Eric NOULARDStatusbacklog => assigned
2011-11-05 16:50Eric NOULARDNote Added: 0027732
2011-11-13 16:56Eric NOULARDNote Added: 0027793
2011-11-13 17:05Eric NOULARDNote Added: 0027794
2011-11-15 16:53Eric NOULARDNote Added: 0027803
2012-01-02 19:01Eric NOULARDPlatform => All
2012-01-02 19:01Eric NOULARDTarget Version => CMake 2.8.8
2012-01-02 19:09Eric NOULARDNote Added: 0028138
2012-01-22 07:51Eric NOULARDNote Added: 0028388
2012-01-31 10:17Eric NOULARDNote Added: 0028433
2012-02-05 18:32Eric NOULARDNote Added: 0028484
2012-02-25 17:45Eric NOULARDNote Added: 0028722
2012-04-06 10:42Eric NOULARDNote Added: 0029088
2012-04-06 10:42Eric NOULARDStatusassigned => closed
2012-04-06 10:42Eric NOULARDResolutionopen => fixed
2012-04-06 10:42Eric NOULARDFixed in Version => CMake 2.8.8

Notes
(0021691)
Eric NOULARD   
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   
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   
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   
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   
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   
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   
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   
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   
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   
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   
2011-05-25 16:46   
Not for 2.8.5 - postponing until a future release
(0027732)
Eric NOULARD   
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   
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   
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   
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   
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   
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   
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   
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   
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   
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.