Difference between revisions of "CMake builtin documentation handling"

From KitwarePublic
Jump to navigationJump to search
(Replace content with link to new CMake community wiki)
 
(5 intermediate revisions by 3 users not shown)
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].
 
 
  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
 
 
 
for the detail see:
 
 
 
  cmake --help
 
  cpack --help
 
  ctest --help
 
 
 
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:
 
cmake --help-module
 
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
 
  --help-variable[s|-list]
 
  --help-command[s|-list]
 
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 '##' (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 ##end markup line.
 
 
 
=== Variable ===
 
 
 
=== Command ===
 
 
 
=== Section ===
 

Latest revision as of 10:41, 30 April 2018


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

This page has moved here.