Help: Move Modules/readme.txt content into cmake-developer.7 manual
Move all content from Modules/readme.txt except for the link to the module maintainers wiki page into "Help/manual/cmake-developer.7.rst". This produces some invalid reStructuredText markup to be fixed in a future commit.
This commit is contained in:
Kitware Robot
Brad King
parent
80a311ed6a
commit
baaab068f2
|
|
@ -16,3 +16,191 @@ Help
|
||||||
|
|
||||||
Modules
|
Modules
|
||||||
=======
|
=======
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
|
||||||
|
|
@ -1,190 +1,2 @@
|
||||||
For more information about how to contribute modules to CMake, see this page:
|
For more information about how to contribute modules to CMake, see this page:
|
||||||
http://www.itk.org/Wiki/CMake:Module_Maintainers
|
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).
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue