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.

1 files changed, 188 insertions, 0 deletions

diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 37e4e3f..8052e27 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -16,3 +16,191 @@ Help
 
 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).