Merge topic 'doc-cmake-developer'
e0ce6f0cmRST: Cross-reference cmake-developer.7 manual and cmRST Doxygenc1c239bHelp: Add documentation format to cmake-developer.7 manuala06a90fHelp: Organize cmake-developer.7 manual Modules section28f08baHelp: Fix module documentation markup in cmake-developer.7 manualbaaab06Help: Move Modules/readme.txt content into cmake-developer.7 manual80a311eHelp: Add cmake-developer.7 manual
This commit is contained in:
Brad King
CMake Topic Stage
commit
a8cfc21843
|
|
@ -20,6 +20,7 @@ CMake Reference Documentation
|
|||
/manual/cmake-properties.7
|
||||
/manual/cmake-variables.7
|
||||
/manual/cmake-generator-expressions.7
|
||||
/manual/cmake-developer.7
|
||||
|
||||
.. only:: html
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,497 @@
|
|||
cmake-developer(7)
|
||||
******************
|
||||
|
||||
.. only:: html or latex
|
||||
|
||||
.. contents::
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
This manual is intended for reference by developers modifying the CMake
|
||||
source tree itself.
|
||||
|
||||
Help
|
||||
====
|
||||
|
||||
The ``Help`` directory contains CMake help manual source files.
|
||||
They are written using the `reStructuredText`_ markup syntax and
|
||||
processed by `Sphinx`_ to generate the CMake help manuals.
|
||||
|
||||
.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
|
||||
.. _`Sphinx`: http://sphinx-doc.org
|
||||
|
||||
Markup Constructs
|
||||
-----------------
|
||||
|
||||
In addition to using Sphinx to generate the CMake help manuals, we
|
||||
also use a C++-implemented document processor to print documents for
|
||||
the ``--help-*`` command-line help options. It supports a subset of
|
||||
reStructuredText markup. When authoring or modifying documents,
|
||||
please verify that the command-line help looks good in addition to the
|
||||
Sphinx-generated html and man pages.
|
||||
|
||||
The command-line help processor supports the following constructs
|
||||
defined by reStructuredText, Sphinx, and a CMake extension to Sphinx.
|
||||
|
||||
..
|
||||
Note: This list must be kept consistent with the cmRST implementation.
|
||||
|
||||
CMake Domain directives
|
||||
Directives defined in the `CMake Domain`_ for defining CMake
|
||||
documentation objects are printed in command-line help output as
|
||||
if the lines were normal paragraph text with interpretation.
|
||||
|
||||
CMake Domain interpreted text roles
|
||||
Interpreted text roles defined in the `CMake Domain`_ for
|
||||
cross-referencing CMake documentation objects are replaced by their
|
||||
link text in command-line help output. Other roles are printed
|
||||
literally and not processed.
|
||||
|
||||
``code-block`` directive
|
||||
Add a literal code block without interpretation. The command-line
|
||||
help processor prints the block content without the leading directive
|
||||
line and with common indentation replaced by one space.
|
||||
|
||||
``include`` directive
|
||||
Include another document source file. The command-line help
|
||||
processor prints the included document inline with the referencing
|
||||
document.
|
||||
|
||||
literal block after ``::``
|
||||
A paragraph ending in ``::`` followed by a blank line treats
|
||||
the following indented block as literal text without interpretation.
|
||||
The command-line help processor prints the ``::`` literally and
|
||||
prints the block content with common indentation replaced by one
|
||||
space. We prefer the ``::`` to appear at the end of a paragraph
|
||||
line instead of as its own line.
|
||||
|
||||
``parsed-literal`` directive
|
||||
Add a literal block with markup interpretation. The command-line
|
||||
help processor prints the block content without the leading
|
||||
directive line and with common indentation replaced by one space.
|
||||
|
||||
``replace`` directive
|
||||
Define a ``|substitution|`` replacement.
|
||||
The command-line help processor requires a substitution replacement
|
||||
to be defined before it is referenced.
|
||||
|
||||
``|substitution|`` reference
|
||||
Reference a substitution replacement previously defined by
|
||||
the ``replace`` directive. The command-line help processor
|
||||
performs the substitution and replaces all newlines in the
|
||||
replacement text with spaces.
|
||||
|
||||
``toctree`` directive
|
||||
Include other document sources in the Table-of-Contents
|
||||
document tree. The command-line help processor prints
|
||||
the referenced documents inline as part of the referencing
|
||||
document.
|
||||
|
||||
Inline markup constructs not listed above are printed literally in the
|
||||
command-line help output. We prefer to use inline markup constructs that
|
||||
look correct in source form, so avoid use of \\-escapes in favor of inline
|
||||
literals when possible.
|
||||
|
||||
Explicit markup blocks not matching directives listed above are removed from
|
||||
command-line help output. Do not use them, except for plain ``..`` comments
|
||||
that are removed by Sphinx too.
|
||||
|
||||
Note that nested indentation of blocks is not recognized by the
|
||||
command-line help processor. Therefore:
|
||||
|
||||
* Explicit markup blocks are recognized only when not indented
|
||||
inside other blocks.
|
||||
|
||||
* Literal blocks after paragraphs ending in ``::`` but not
|
||||
at the top indentation level may consume all indented lines
|
||||
following them.
|
||||
|
||||
Try to avoid these cases in practice.
|
||||
|
||||
CMake Domain
|
||||
------------
|
||||
|
||||
CMake adds a `Sphinx Domain`_ called ``cmake``, also called the
|
||||
"CMake Domain". It defines several "object" types for CMake
|
||||
documentation:
|
||||
|
||||
``command``
|
||||
A CMake language command.
|
||||
|
||||
``generator``
|
||||
A CMake native build system generator.
|
||||
See the :manual:`cmake(1)` command-line tool's ``-G`` option.
|
||||
|
||||
``manual``
|
||||
A CMake manual page, like this :manual:`cmake-developer(7)` manual.
|
||||
|
||||
``module``
|
||||
A CMake module.
|
||||
See the :manual:`cmake-modules(7)` manual
|
||||
and the :command:`include` command.
|
||||
|
||||
``policy``
|
||||
A CMake policy.
|
||||
See the :manual:`cmake-policies(7)` manual
|
||||
and the :command:`cmake_policy` command.
|
||||
|
||||
``prop_cache, prop_dir, prop_gbl, prop_sf, prop_test, prop_tgt``
|
||||
A CMake cache, directory, global, source file, test, or target
|
||||
property, respectively. See the :manual:`cmake-properties(7)` manual
|
||||
and the :command:`set_property` command.
|
||||
|
||||
``variable``
|
||||
A CMake language variable.
|
||||
See the :manual:`cmake-variables(7)` manual
|
||||
and the :command:`set` command.
|
||||
|
||||
Documentation objects in the CMake Domain come from two sources.
|
||||
First, the CMake extension to Sphinx transforms every document named
|
||||
with the form ``Help/<type>/<file-name>.rst`` to a domain object with
|
||||
type ``<type>``. The object name is extracted from the document title,
|
||||
which is expected to be of the form::
|
||||
|
||||
<object-name>
|
||||
-------------
|
||||
|
||||
and to appear at or near the top of the ``.rst`` file before any other
|
||||
lines starting in a letter, digit, or ``<``. If no such title appears
|
||||
literally in the ``.rst`` file, the object name is the ``<file-name>``.
|
||||
If a title does appear, it is expected that ``<file-name>`` is equal
|
||||
to ``<object-name>`` with any ``<`` and ``>`` characters removed.
|
||||
|
||||
Second, the CMake Domain provides directives to define objects inside
|
||||
other documents:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. command:: <command-name>
|
||||
|
||||
This indented block documents <command-name>.
|
||||
|
||||
.. variable:: <variable-name>
|
||||
|
||||
This indented block documents <variable-name>.
|
||||
|
||||
Object types for which no directive is available must be defined using
|
||||
the first approach above.
|
||||
|
||||
.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
|
||||
|
||||
Cross-References
|
||||
----------------
|
||||
|
||||
Sphinx uses reStructuredText interpreted text roles to provide
|
||||
cross-reference syntax. The `CMake Domain`_ provides for each
|
||||
domain object type a role of the same name to cross-reference it.
|
||||
CMake Domain roles are inline markup of the forms::
|
||||
|
||||
:type:`name`
|
||||
:type:`text <name>`
|
||||
|
||||
where ``type`` is the domain object type and ``name`` is the
|
||||
domain object name. In the first form the link text will be
|
||||
``name`` (or ``name()`` if the type is ``command``) and in
|
||||
the second form the link text will be the explicit ``text``.
|
||||
For example, the code:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
* The :command:`list` command.
|
||||
* The :command:`list(APPEND)` sub-command.
|
||||
* The :command:`list() command <list>`.
|
||||
* The :command:`list(APPEND) sub-command <list>`.
|
||||
* The :variable:`CMAKE_VERSION` variable.
|
||||
* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.
|
||||
|
||||
produces:
|
||||
|
||||
* The :command:`list` command.
|
||||
* The :command:`list(APPEND)` sub-command.
|
||||
* The :command:`list() command <list>`.
|
||||
* The :command:`list(APPEND) sub-command <list>`.
|
||||
* The :variable:`CMAKE_VERSION` variable.
|
||||
* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property.
|
||||
|
||||
Note that CMake Domain roles differ from Sphinx and reStructuredText
|
||||
convention in that the form ``a<b>``, without a space preceding ``<``,
|
||||
is interpreted as a name instead of link text with an explicit target.
|
||||
This is necessary because we use ``<placeholders>`` frequently in
|
||||
object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``,
|
||||
with a space preceding ``<``, is still interpreted as a link text
|
||||
with an explicit target.
|
||||
|
||||
Modules
|
||||
=======
|
||||
|
||||
The ``Modules`` directory contains CMake-language ``.cmake`` module files.
|
||||
|
||||
Module Documentation
|
||||
--------------------
|
||||
|
||||
To add a module to the CMake documentation, follow these steps:
|
||||
|
||||
1. Add file ``Help/module/<module-name>.rst`` containing just the line::
|
||||
|
||||
.. cmake-module:: ../../Modules/<module-name>.cmake
|
||||
|
||||
2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the
|
||||
toctree directive as::
|
||||
|
||||
/module/<module-name>
|
||||
|
||||
Keep the toctree in sorted order!
|
||||
|
||||
3. Add to the top of ``Modules/<module-name>.cmake`` a #-comment of the form::
|
||||
|
||||
#.rst:
|
||||
# <module-name>
|
||||
# -------------
|
||||
#
|
||||
# ...reStructuredText documentation of module...
|
||||
|
||||
Comment blocks starting with the line ``#.rst:`` may appear anywhere
|
||||
in the file. The ``cmake-module`` directive used above will scan the
|
||||
file to extract reStructuredText markup from such comments.
|
||||
|
||||
For example, a ``Modules/Findxxx.cmake`` module may contain:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
#.rst:
|
||||
# FindXxx
|
||||
# -------
|
||||
#
|
||||
# This is a cool module.
|
||||
# This module does really cool stuff.
|
||||
# It can do even more than you think.
|
||||
#
|
||||
# It even needs two paragraphs to tell you about it.
|
||||
# And it defines the following variables:
|
||||
#
|
||||
# * VAR_COOL: this is great isn't it?
|
||||
# * VAR_REALLY_COOL: cool right?
|
||||
|
||||
<code>
|
||||
|
||||
#.rst:
|
||||
# .. command:: xxx_do_something
|
||||
#
|
||||
# This command does something for Xxx::
|
||||
#
|
||||
# xxx_do_something(some arguments)
|
||||
macro(xxx_do_something)
|
||||
<code>
|
||||
endmacro()
|
||||
|
||||
Find Modules
|
||||
------------
|
||||
|
||||
A "find module" is a ``Modules/Find<package>.cmake`` file to be loaded
|
||||
by the :command:`find_package` command when invoked for ``<package>``.
|
||||
|
||||
We would like all ``FindXxx.cmake`` files to produce consistent variable
|
||||
names. Please use the following consistent variable names for general use.
|
||||
|
||||
Xxx_INCLUDE_DIRS
|
||||
The final set of include directories listed in one variable for use by client
|
||||
code. This should not be a cache entry.
|
||||
|
||||
Xxx_LIBRARIES
|
||||
The libraries to link against to use Xxx. These should include full paths.
|
||||
This should not be a cache entry.
|
||||
|
||||
Xxx_DEFINITIONS
|
||||
Definitions to use when compiling code that uses Xxx. This really shouldn't
|
||||
include options such as (-DHAS_JPEG)that a client source-code file uses to
|
||||
decide whether to #include <jpeg.h>
|
||||
|
||||
Xxx_EXECUTABLE
|
||||
Where to find the Xxx tool.
|
||||
|
||||
Xxx_Yyy_EXECUTABLE
|
||||
Where to find the Yyy tool that comes with Xxx.
|
||||
|
||||
Xxx_LIBRARY_DIRS
|
||||
Optionally, the final set of library directories listed in one variable for
|
||||
use by client code. This should not be a cache entry.
|
||||
|
||||
Xxx_ROOT_DIR
|
||||
Where to find the base directory of Xxx.
|
||||
|
||||
Xxx_VERSION_Yy
|
||||
Expect Version Yy if true. Make sure at most one of these is ever true.
|
||||
|
||||
Xxx_WRAP_Yy
|
||||
If False, do not try to use the relevant CMake wrapping command.
|
||||
|
||||
Xxx_Yy_FOUND
|
||||
If False, optional Yy part of Xxx sytem is not available.
|
||||
|
||||
Xxx_FOUND
|
||||
Set to false, or undefined, if we haven't found, or don't want to use Xxx.
|
||||
|
||||
Xxx_NOT_FOUND_MESSAGE
|
||||
Should be set by config-files in the case that it has set Xxx_FOUND to FALSE.
|
||||
The contained message will be printed by the find_package() command and by
|
||||
find_package_handle_standard_args() to inform the user about the problem.
|
||||
|
||||
Xxx_RUNTIME_LIBRARY_DIRS
|
||||
Optionally, the runtime library search path for use when running an
|
||||
executable linked to shared libraries. The list should be used by user code
|
||||
to create the PATH on windows or LD_LIBRARY_PATH on unix. This should not be
|
||||
a cache entry.
|
||||
|
||||
Xxx_VERSION_STRING
|
||||
A human-readable string containing the version of the package found, if any.
|
||||
|
||||
Xxx_VERSION_MAJOR
|
||||
The major version of the package found, if any.
|
||||
|
||||
Xxx_VERSION_MINOR
|
||||
The minor version of the package found, if any.
|
||||
|
||||
Xxx_VERSION_PATCH
|
||||
The patch version of the package found, if any.
|
||||
|
||||
You do not have to provide all of the above variables. You should provide
|
||||
Xxx_FOUND under most circumstances. If Xxx is a library, then Xxx_LIBRARIES,
|
||||
should also be defined, and Xxx_INCLUDE_DIRS should usually be defined (I
|
||||
guess libm.a might be an exception)
|
||||
|
||||
The following names should not usually be used in CMakeLists.txt files, but
|
||||
they may be usefully modified in users' CMake Caches to control stuff.
|
||||
|
||||
Xxx_LIBRARY
|
||||
Name of Xxx Library. A User may set this and Xxx_INCLUDE_DIR to ignore to
|
||||
force non-use of Xxx.
|
||||
|
||||
Xxx_Yy_LIBRARY
|
||||
Name of Yy library that is part of the Xxx system. It may or may not be
|
||||
required to use Xxx.
|
||||
|
||||
Xxx_INCLUDE_DIR
|
||||
Where to find xxx.h, etc. (Xxx_INCLUDE_PATH was considered bad because a path
|
||||
includes an actual filename.)
|
||||
|
||||
Xxx_Yy_INCLUDE_DIR
|
||||
Where to find xxx_yy.h, etc.
|
||||
|
||||
For tidiness's sake, try to keep as many options as possible out of the cache,
|
||||
leaving at least one option which can be used to disable use of the module, or
|
||||
locate a not-found library (e.g. Xxx_ROOT_DIR). For the same reason, mark
|
||||
most cache options as advanced.
|
||||
|
||||
If you need other commands to do special things then it should still begin
|
||||
with ``Xxx_``. This gives a sort of namespace effect and keeps things tidy for the
|
||||
user. You should put comments describing all the exported settings, plus
|
||||
descriptions of any the users can use to control stuff.
|
||||
|
||||
You really should also provide backwards compatibility any old settings that
|
||||
were actually in use. Make sure you comment them as deprecated, so that
|
||||
no-one starts using them.
|
||||
|
||||
To add a module to the CMake documentation, follow the steps in the
|
||||
`Module Documentation`_ section above. Test the documentation formatting
|
||||
by running ``cmake --help-module FindXxx``, and also by enabling the
|
||||
``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation.
|
||||
Edit the comments until generated documentation looks satisfactory.
|
||||
To have a .cmake file in this directory NOT show up in the modules
|
||||
documentation, simply leave out the ``Help/module/<module-name>.rst`` file
|
||||
and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
|
||||
|
||||
After the documentation, leave a *BLANK* line, and then add a
|
||||
copyright and licence notice block like this one::
|
||||
|
||||
#=============================================================================
|
||||
# Copyright 2009-2011 Your Name
|
||||
#
|
||||
# Distributed under the OSI-approved BSD License (the "License");
|
||||
# see accompanying file Copyright.txt for details.
|
||||
#
|
||||
# This software is distributed WITHOUT ANY WARRANTY; without even the
|
||||
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||
# See the License for more information.
|
||||
#=============================================================================
|
||||
# (To distribute this file outside of CMake, substitute the full
|
||||
# License text for the above reference.)
|
||||
|
||||
The layout of the notice block is strictly enforced by the ``ModuleNotices``
|
||||
test. Only the year range and name may be changed freely.
|
||||
|
||||
A FindXxx.cmake module will typically be loaded by the command::
|
||||
|
||||
FIND_PACKAGE(Xxx [major[.minor[.patch[.tweak]]]] [EXACT]
|
||||
[QUIET] [[REQUIRED|COMPONENTS] [components...]])
|
||||
|
||||
If any version numbers are given to the command it will set the following
|
||||
variables before loading the module:
|
||||
|
||||
Xxx_FIND_VERSION
|
||||
full requested version string
|
||||
|
||||
Xxx_FIND_VERSION_MAJOR
|
||||
major version if requested, else 0
|
||||
|
||||
Xxx_FIND_VERSION_MINOR
|
||||
minor version if requested, else 0
|
||||
|
||||
Xxx_FIND_VERSION_PATCH
|
||||
patch version if requested, else 0
|
||||
|
||||
Xxx_FIND_VERSION_TWEAK
|
||||
tweak version if requested, else 0
|
||||
|
||||
Xxx_FIND_VERSION_COUNT
|
||||
number of version components, 0 to 4
|
||||
|
||||
Xxx_FIND_VERSION_EXACT
|
||||
true if EXACT option was given
|
||||
|
||||
If the find module supports versioning it should locate a version of
|
||||
the package that is compatible with the version requested. If a
|
||||
compatible version of the package cannot be found the module should
|
||||
not report success. The version of the package found should be stored
|
||||
in "Xxx_VERSION..." version variables documented by the module.
|
||||
|
||||
If the QUIET option is given to the command it will set the variable
|
||||
Xxx_FIND_QUIETLY to true before loading the FindXxx.cmake module. If
|
||||
this variable is set the module should not complain about not being
|
||||
able to find the package. If the
|
||||
REQUIRED option is given to the command it will set the variable
|
||||
Xxx_FIND_REQUIRED to true before loading the FindXxx.cmake module. If
|
||||
this variable is set the module should issue a FATAL_ERROR if the
|
||||
package cannot be found.
|
||||
If neither the QUIET nor REQUIRED options are given then the
|
||||
FindXxx.cmake module should look for the package and complain without
|
||||
error if the module is not found.
|
||||
|
||||
FIND_PACKAGE() will set the variable CMAKE_FIND_PACKAGE_NAME to
|
||||
contain the actual name of the package.
|
||||
|
||||
A package can provide sub-components.
|
||||
Those components can be listed after the COMPONENTS (or REQUIRED) or
|
||||
OPTIONAL_COMPONENTS keywords. The set of all listed components will be
|
||||
specified in a Xxx_FIND_COMPONENTS variable.
|
||||
For each package-specific component, say Yyy, a variable Xxx_FIND_REQUIRED_Yyy
|
||||
will be set to true if it listed after COMPONENTS and it will be set to false
|
||||
if it was listed after OPTIONAL_COMPONENTS.
|
||||
Using those variables a FindXxx.cmake module and also a XxxConfig.cmake
|
||||
package configuration file can determine whether and which components have
|
||||
been requested, and whether they were requested as required or as optional.
|
||||
For each of the requested components a Xxx_Yyy_FOUND variable should be set
|
||||
accordingly.
|
||||
The per-package Xxx_FOUND variable should be only set to true if all requested
|
||||
required components have been found. A missing optional component should not
|
||||
keep the Xxx_FOUND variable from being set to true.
|
||||
If the package provides Xxx_INCLUDE_DIRS and Xxx_LIBRARIES variables, the
|
||||
include dirs and libraries for all components which were requested and which
|
||||
have been found should be added to those two variables.
|
||||
|
||||
To get this behaviour you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS()
|
||||
macro, as an example see FindJPEG.cmake.
|
||||
|
||||
For internal implementation, it's a generally accepted convention that
|
||||
variables starting with underscore are for temporary use only. (variable
|
||||
starting with an underscore are not intended as a reserved prefix).
|
||||
|
|
@ -1,190 +1,4 @@
|
|||
See the "Find Modules" section of the cmake-developer(7) manual page.
|
||||
|
||||
For more information about how to contribute modules to CMake, see this page:
|
||||
http://www.itk.org/Wiki/CMake:Module_Maintainers
|
||||
|
||||
Note to authors of FindXxx.cmake files
|
||||
|
||||
We would like all FindXxx.cmake files to produce consistent variable names.
|
||||
|
||||
Please use the following consistent variable names for general use.
|
||||
|
||||
Xxx_INCLUDE_DIRS The final set of include directories listed in one variable for use by client code.
|
||||
This should not be a cache entry.
|
||||
Xxx_LIBRARIES The libraries to link against to use Xxx. These should include full paths.
|
||||
This should not be a cache entry.
|
||||
Xxx_DEFINITIONS Definitions to use when compiling code that uses Xxx. This really shouldn't include options such
|
||||
as (-DHAS_JPEG)that a client source-code file uses to decide whether to #include <jpeg.h>
|
||||
Xxx_EXECUTABLE Where to find the Xxx tool.
|
||||
Xxx_Yyy_EXECUTABLE Where to find the Yyy tool that comes with Xxx.
|
||||
Xxx_LIBRARY_DIRS Optionally, the final set of library directories listed in one variable for use by client code.
|
||||
This should not be a cache entry.
|
||||
Xxx_ROOT_DIR Where to find the base directory of Xxx.
|
||||
Xxx_VERSION_Yy Expect Version Yy if true. Make sure at most one of these is ever true.
|
||||
Xxx_WRAP_Yy If False, do not try to use the relevant CMake wrapping command.
|
||||
Xxx_Yy_FOUND If False, optional Yy part of Xxx sytem is not available.
|
||||
Xxx_FOUND Set to false, or undefined, if we haven't found, or don't want to use Xxx.
|
||||
Xxx_NOT_FOUND_MESSAGE Should be set by config-files in the case that it has set Xxx_FOUND to FALSE.
|
||||
The contained message will be printed by the find_package() command and by
|
||||
find_package_handle_standard_args() to inform the user about the problem.
|
||||
Xxx_RUNTIME_LIBRARY_DIRS Optionally, the runtime library search path for use when running an executable linked to
|
||||
shared libraries.
|
||||
The list should be used by user code to create the PATH on windows or LD_LIBRARY_PATH on unix.
|
||||
This should not be a cache entry.
|
||||
Xxx_VERSION_STRING A human-readable string containing the version of the package found, if any.
|
||||
Xxx_VERSION_MAJOR The major version of the package found, if any.
|
||||
Xxx_VERSION_MINOR The minor version of the package found, if any.
|
||||
Xxx_VERSION_PATCH The patch version of the package found, if any.
|
||||
|
||||
You do not have to provide all of the above variables. You should provide Xxx_FOUND under most circumstances.
|
||||
If Xxx is a library, then Xxx_LIBRARIES, should also be defined, and Xxx_INCLUDE_DIRS should usually be
|
||||
defined (I guess libm.a might be an exception)
|
||||
|
||||
The following names should not usually be used in CMakeLists.txt files, but they may be usefully modified in
|
||||
users' CMake Caches to control stuff.
|
||||
|
||||
Xxx_LIBRARY Name of Xxx Library. A User may set this and Xxx_INCLUDE_DIR to ignore to force non-use of Xxx.
|
||||
Xxx_Yy_LIBRARY Name of Yy library that is part of the Xxx system. It may or may not be required to use Xxx.
|
||||
Xxx_INCLUDE_DIR Where to find xxx.h, etc. (Xxx_INCLUDE_PATH was considered bad because a path includes an
|
||||
actual filename.)
|
||||
Xxx_Yy_INCLUDE_DIR Where to find xxx_yy.h, etc.
|
||||
|
||||
For tidiness's sake, try to keep as many options as possible out of the cache, leaving at least one option which can be
|
||||
used to disable use of the module, or locate a not-found library (e.g. Xxx_ROOT_DIR).
|
||||
For the same reason, mark most cache options as advanced.
|
||||
|
||||
If you need other commands to do special things then it should still begin with Xxx_. This gives a sort of namespace
|
||||
effect and keeps things tidy for the user. You should put comments describing all the exported settings, plus
|
||||
descriptions of any the users can use to control stuff.
|
||||
|
||||
You really should also provide backwards compatibility any old settings that were actually in use.
|
||||
Make sure you comment them as deprecated, so that no-one starts using them.
|
||||
|
||||
To add a module to the CMake documentation, follow these steps:
|
||||
|
||||
1. Add file ``Help/module/FindXxx.rst`` containing just the line::
|
||||
|
||||
.. cmake-module:: ../../Modules/FindXxx.cmake
|
||||
|
||||
2. Modify ``Help/manual/cmake-modules.7.rst`` to reference the module in the
|
||||
toctree directive as::
|
||||
|
||||
/module/FindXxx
|
||||
|
||||
Keep the toctree in sorted order!
|
||||
|
||||
3. Add to the top of ``Modules/FindXxx.cmake`` a #-comment of the form::
|
||||
|
||||
#.rst:
|
||||
# FindXxx
|
||||
# -------
|
||||
#
|
||||
# ...reStructuredText documentation of module...
|
||||
|
||||
Comment blocks starting with the line ``#.rst:`` may appear anywhere
|
||||
in the file.
|
||||
|
||||
For example::
|
||||
|
||||
#.rst
|
||||
# FindXxx
|
||||
# -------
|
||||
#
|
||||
# This is a cool module.
|
||||
# This module does really cool stuff.
|
||||
# It can do even more than you think.
|
||||
#
|
||||
# It even needs two paragraphs to tell you about it.
|
||||
# And it defines the following variables:
|
||||
#
|
||||
# * VAR_COOL: this is great isn't it?
|
||||
# * VAR_REALLY_COOL: cool right?
|
||||
|
||||
Test the documentation formatting by running "cmake --help-module FindXxx",
|
||||
and ideally by enabling the SPHINX_HTML and SPHINX_MAN options to build the
|
||||
documentation. Edit the comments until generated documentation looks
|
||||
satisfactory.
|
||||
|
||||
To have a .cmake file in this directory NOT show up in the modules
|
||||
documentation, simply leave out the ``Help/module/<module>.rst`` file and the
|
||||
``Help/manual/cmake-modules.7.rst`` toctree entry.
|
||||
|
||||
After the documentation, leave a *BLANK* line, and then add a
|
||||
copyright and licence notice block like this one:
|
||||
|
||||
#=============================================================================
|
||||
# Copyright 2009-2011 Your Name
|
||||
#
|
||||
# Distributed under the OSI-approved BSD License (the "License");
|
||||
# see accompanying file Copyright.txt for details.
|
||||
#
|
||||
# This software is distributed WITHOUT ANY WARRANTY; without even the
|
||||
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||
# See the License for more information.
|
||||
#=============================================================================
|
||||
# (To distribute this file outside of CMake, substitute the full
|
||||
# License text for the above reference.)
|
||||
|
||||
The layout of the notice block is strictly enforced by the ModuleNotices test.
|
||||
Only the year range and name may be changed freely.
|
||||
|
||||
A FindXxx.cmake module will typically be loaded by the command
|
||||
|
||||
FIND_PACKAGE(Xxx [major[.minor[.patch[.tweak]]]] [EXACT]
|
||||
[QUIET] [[REQUIRED|COMPONENTS] [components...]])
|
||||
|
||||
If any version numbers are given to the command it will set the
|
||||
following variables before loading the module:
|
||||
|
||||
Xxx_FIND_VERSION = full requested version string
|
||||
Xxx_FIND_VERSION_MAJOR = major version if requested, else 0
|
||||
Xxx_FIND_VERSION_MINOR = minor version if requested, else 0
|
||||
Xxx_FIND_VERSION_PATCH = patch version if requested, else 0
|
||||
Xxx_FIND_VERSION_TWEAK = tweak version if requested, else 0
|
||||
Xxx_FIND_VERSION_COUNT = number of version components, 0 to 4
|
||||
Xxx_FIND_VERSION_EXACT = true if EXACT option was given
|
||||
|
||||
If the find module supports versioning it should locate a version of
|
||||
the package that is compatible with the version requested. If a
|
||||
compatible version of the package cannot be found the module should
|
||||
not report success. The version of the package found should be stored
|
||||
in "Xxx_VERSION..." version variables documented by the module.
|
||||
|
||||
If the QUIET option is given to the command it will set the variable
|
||||
Xxx_FIND_QUIETLY to true before loading the FindXxx.cmake module. If
|
||||
this variable is set the module should not complain about not being
|
||||
able to find the package. If the
|
||||
REQUIRED option is given to the command it will set the variable
|
||||
Xxx_FIND_REQUIRED to true before loading the FindXxx.cmake module. If
|
||||
this variable is set the module should issue a FATAL_ERROR if the
|
||||
package cannot be found.
|
||||
If neither the QUIET nor REQUIRED options are given then the
|
||||
FindXxx.cmake module should look for the package and complain without
|
||||
error if the module is not found.
|
||||
|
||||
FIND_PACKAGE() will set the variable CMAKE_FIND_PACKAGE_NAME to
|
||||
contain the actual name of the package.
|
||||
|
||||
A package can provide sub-components.
|
||||
Those components can be listed after the COMPONENTS (or REQUIRED)
|
||||
or OPTIONAL_COMPONENTS keywords. The set of all listed components will be
|
||||
specified in a Xxx_FIND_COMPONENTS variable.
|
||||
For each package-specific component, say Yyy, a variable Xxx_FIND_REQUIRED_Yyy
|
||||
will be set to true if it listed after COMPONENTS and it will be set to false
|
||||
if it was listed after OPTIONAL_COMPONENTS.
|
||||
Using those variables a FindXxx.cmake module and also a XxxConfig.cmake package
|
||||
configuration file can determine whether and which components have been requested,
|
||||
and whether they were requested as required or as optional.
|
||||
For each of the requested components a Xxx_Yyy_FOUND variable should be set
|
||||
accordingly.
|
||||
The per-package Xxx_FOUND variable should be only set to true if all requested
|
||||
required components have been found. A missing optional component should not
|
||||
keep the Xxx_FOUND variable from being set to true.
|
||||
If the package provides Xxx_INCLUDE_DIRS and Xxx_LIBRARIES variables, the include
|
||||
dirs and libraries for all components which were requested and which have been
|
||||
found should be added to those two variables.
|
||||
|
||||
To get this behaviour you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS()
|
||||
macro, as an example see FindJPEG.cmake.
|
||||
|
||||
For internal implementation, it's a generally accepted convention that variables starting with
|
||||
underscore are for temporary use only. (variable starting with an underscore
|
||||
are not intended as a reserved prefix).
|
||||
http://www.cmake.org/Wiki/CMake:Module_Maintainers
|
||||
|
|
|
|||
|
|
@ -16,6 +16,16 @@
|
|||
|
||||
#include <cmsys/RegularExpression.hxx>
|
||||
|
||||
/** \class cmRST
|
||||
* \brief Perform basic .rst processing for command-line help
|
||||
*
|
||||
* This class implements a subset of reStructuredText and Sphinx
|
||||
* document processing. It is used to print command-line help.
|
||||
*
|
||||
* If you modify the capabilities of this class, be sure to update
|
||||
* the Help/manual/cmake-developer.7.rst documentation and to update
|
||||
* the Tests/CMakeLib/testRST.(rst|expect) test input and output.
|
||||
*/
|
||||
class cmRST
|
||||
{
|
||||
public:
|
||||
|
|
|
|||
|
|
@ -40,6 +40,7 @@ man_pages = [
|
|||
('manual/cmake-properties.7', 'cmake-properties', 'CMake Properties Reference', [], 7),
|
||||
('manual/cmake-variables.7', 'cmake-variables', 'CMake Variables Reference', [], 7),
|
||||
('manual/cmake-generator-expressions.7', 'cmake-generator-expressions', 'CMake Generator Expressions', [], 7),
|
||||
('manual/cmake-developer.7', 'cmake-developer', 'CMake Developer Reference', [], 7),
|
||||
]
|
||||
man_show_urls = False
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue