diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 263 |
1 files changed, 161 insertions, 102 deletions
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 8052e27..90d8d82 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -19,60 +19,108 @@ Modules Note to authors of FindXxx.cmake files -We would like all FindXxx.cmake files to produce consistent variable names. +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 +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. +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: @@ -100,7 +148,7 @@ To add a module to the CMake documentation, follow these steps: For example:: - #.rst + #.rst: # FindXxx # ------- # @@ -114,49 +162,60 @@ For example:: # * 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. +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 +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 @@ -180,27 +239,27 @@ 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 +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. +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. +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). +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). |