[cmake-developers] Improving CPack Documentation (and may be others as well)
Eric Noulard
eric.noulard at gmail.com
Mon Jan 2 19:43:36 EST 2012
Hi All,
I try to push forward the feature request:
http://public.kitware.com/Bug/view.php?id=10067
I have something working for
cpack --help-command
and
cpack --help-variables
for which the documentation are automatically extracted from concerned
*.cmake files,
namely;
CPack.cmake
CPackComponent.cmake
CPackRPM.cmake
CPackDeb.cmake
The needed modifications are minor, you "just" have to add extra markup, like:
##variable
# CPACK_PACKAGE_FILE_NAME - The name of the package file to generate,
# not including the extension. For example, cmake-2.6.1-Linux-i686.
##end
and then you can ask
cpack --help-variable CPACK_PACKAGE_FILE_NAME
and you get the corresponding doc.
This is far less painful than adding extra static string vars in the C++ code
with the drawback that some files are parsed at run time
(just like when you do cmake --help-module CPack).
The great advantage being that the technique could be used to document
macros, functions and variables directly in CMake script files.
Currently the *.cmake files which are parsed are specified directly in
cpack.cxx code but we can easily design a scheme which would make
this more flexible.
The very same technique could then be used for CMake or CTest and even
for user-written CMake scripts as well.
My proposal does not solve the problem of having more markup
(like bold, cross-reference/link etc...) but is ease the creation
of doc structure by creating cmDocumentationEntry
[(name, brief, full description) string triplet] from the new markup.
Anybody have some time to try this?
I'd like to have some feedback before going on.
The branch is stage/ImproveCPackDoc.
--
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org
More information about the cmake-developers
mailing list