summaryrefslogtreecommitdiffstats
path: root/Modules/readme.txt
diff options
context:
space:
mode:
authorKitware Robot <kwrobot@kitware.com>2013-10-22 13:51:51 (GMT)
committerBrad King <brad.king@kitware.com>2013-10-22 13:51:51 (GMT)
commitbaaab068f2fa9e736ed85f3ba9b75d96e9339f89 (patch)
tree96ce3444cdd16a0d7d55cd20391ffa9b16e1a6a4 /Modules/readme.txt
parent80a311ed6a8363563c33ea515602b8fa4eedd651 (diff)
downloadCMake-baaab068f2fa9e736ed85f3ba9b75d96e9339f89.zip
CMake-baaab068f2fa9e736ed85f3ba9b75d96e9339f89.tar.gz
CMake-baaab068f2fa9e736ed85f3ba9b75d96e9339f89.tar.bz2
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.
Diffstat (limited to 'Modules/readme.txt')
-rw-r--r--Modules/readme.txt188
1 files changed, 0 insertions, 188 deletions
diff --git a/Modules/readme.txt b/Modules/readme.txt
index 2593b4f..7d7d397 100644
--- a/Modules/readme.txt
+++ b/Modules/readme.txt
@@ -1,190 +1,2 @@
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).