|
Notes |
|
|
(0021691)
|
|
Eric NOULARD
|
|
2010-08-08 11:44
|
|
|
|
|
(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
|
|
|
|
|
(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
|
|
|
|
|
(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. |
|