Difference between revisions of "CMake builtin documentation handling"

From KitwarePublic
Jump to navigationJump to search
(Remove leading space rectangles from preformatted blocks)
(Replace content with link to new CMake community wiki)
 
Line 1: Line 1:
== CMake, CPack, CTest builtin documentation ==
+
{{CMake/Template/Moved}}
  
All CMake tools command line do have some builtin documentation support. The tools (cmake, cpack, ctest) supports a variable subset of:
+
This page has moved [https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/builtin-documentation-handling here].
 
 
<pre>
 
ctool --help-command[-list]
 
ctool --help-module[-list]
 
ctool --help-variable[-list]
 
ctool --help-policy[-list]
 
ctool --help-property[-list]
 
ctool --help-full
 
ctool --help-html
 
</pre>
 
 
 
for the detail see:
 
 
 
<pre>
 
cmake --help
 
cpack --help
 
ctest --help
 
</pre>
 
 
 
This builtin documentation comes from 2 different places:
 
# static variables in C++ sources
 
# text surrounded by markup in CMake script files
 
 
 
== Documentation in C++ sources ==
 
 
 
This is the primary source of builtin documentation.
 
 
 
== Documentation markup in CMake script files ==
 
 
 
This source is available since CMake 2.8.8 and is currently only used by CPack.
 
The idea behind CMake script markup is to be able to document CMake scripts. Documenting a script means being able to put in structured documentation using some comments.
 
 
 
Before 2.8.8, this was available through:
 
<pre>
 
cmake --help-module
 
</pre>
 
which was basically extracting the first block of comments stripping out the comment character ('#').
 
 
 
From 2.8.8 and up we may be able to do more by using a basic markup language which may be used to document:
 
* variable
 
* command
 
* section/module
 
 
 
The markup may then be automatically extracted by ctool (cmake, cpack, ctest) in order to feed their
 
<pre>
 
--help-variable[s|-list]
 
--help-command[s|-list]
 
</pre>
 
command lines options.
 
 
 
A comment in a CMake script is a line which begin by a '#' character. A markup line is a special line which begin with a '<code>##</code>' (double '#') followed by a markup word. The list of currently supported markup words is:
 
* section
 
* module
 
* variable
 
* macro
 
* end
 
A documentation block must always begins with a non-end markup line and finishes with a <code>##end</code> markup line.
 
 
 
=== Variable ===
 
 
 
=== Command ===
 
 
 
=== Section ===
 
 
 
{{CMake/Template/Footer}}
 

Latest revision as of 11:41, 30 April 2018


The CMake community Wiki has moved to the Kitware GitLab Instance.

This page has moved here.