Help: Document that the CHECK_* macros create cache variables

Otherwise callers may expect to be able to re-use result variables.

16 files changed, 18 insertions, 1 deletions

diff --git a/Modules/CheckCCompilerFlag.cmake b/Modules/CheckCCompilerFlag.cmake
index efdac20087..53f3454734 100644
--- a/Modules/CheckCCompilerFlag.cmake
+++ b/Modules/CheckCCompilerFlag.cmake
@@ -10,6 +10,7 @@
 #
 #   <flag> - the compiler flag
 #   <var>  - variable to store the result
+#            Will be created as an internal cache variable.
 #
 # This internally calls the check_c_source_compiles macro and sets
 # CMAKE_REQUIRED_DEFINITIONS to <flag>.  See help for
diff --git a/Modules/CheckCSourceCompiles.cmake b/Modules/CheckCSourceCompiles.cmake
index 7523446720..6e80fb535c 100644
--- a/Modules/CheckCSourceCompiles.cmake
+++ b/Modules/CheckCSourceCompiles.cmake
@@ -10,6 +10,7 @@
 #
 #   <code>       - source code to try to compile, must define 'main'
 #   <var>        - variable to store whether the source code compiled
+#                  Will be created as an internal cache variable.
 #   <fail-regex> - fail if test output matches this regex
 #
 # The following variables may be set before calling this macro to modify
diff --git a/Modules/CheckCSourceRuns.cmake b/Modules/CheckCSourceRuns.cmake
index 0fb0f23c0c..0ce423c1f6 100644
--- a/Modules/CheckCSourceRuns.cmake
+++ b/Modules/CheckCSourceRuns.cmake
@@ -11,6 +11,7 @@
 #   <code>   - source code to try to compile
 #   <var>    - variable to store the result
 #              (1 for success, empty for failure)
+#              Will be created as an internal cache variable.
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
diff --git a/Modules/CheckCXXSourceCompiles.cmake b/Modules/CheckCXXSourceCompiles.cmake
index edd62a6d4d..6d52ec6b8d 100644
--- a/Modules/CheckCXXSourceCompiles.cmake
+++ b/Modules/CheckCXXSourceCompiles.cmake
@@ -10,6 +10,7 @@
 #
 #   <code>       - source code to try to compile, must define 'main'
 #   <var>        - variable to store whether the source code compiled
+#                  Will be created as an internal cache variable.
 #   <fail-regex> - fail if test output matches this regex
 #
 # The following variables may be set before calling this macro to modify
diff --git a/Modules/CheckCXXSourceRuns.cmake b/Modules/CheckCXXSourceRuns.cmake
index 02731f858c..3c06d75403 100644
--- a/Modules/CheckCXXSourceRuns.cmake
+++ b/Modules/CheckCXXSourceRuns.cmake
@@ -11,6 +11,7 @@
 #   <code>   - source code to try to compile
 #   <var>    - variable to store the result
 #              (1 for success, empty for failure)
+#              Will be created as an internal cache variable.
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
diff --git a/Modules/CheckFortranFunctionExists.cmake b/Modules/CheckFortranFunctionExists.cmake
index 0b12289098..bd52f61b65 100644
--- a/Modules/CheckFortranFunctionExists.cmake
+++ b/Modules/CheckFortranFunctionExists.cmake
@@ -10,6 +10,7 @@
 #
 #   FUNCTION - the name of the Fortran function
 #   VARIABLE - variable to store the result
+#              Will be created as an internal cache variable.
 #
 #
 #
diff --git a/Modules/CheckFortranSourceCompiles.cmake b/Modules/CheckFortranSourceCompiles.cmake
index 63e4539029..f90d05bd6f 100644
--- a/Modules/CheckFortranSourceCompiles.cmake
+++ b/Modules/CheckFortranSourceCompiles.cmake
@@ -12,6 +12,7 @@
 #   Source code to try to compile.  It must define a PROGRAM entry point.
 # ``<var>``
 #   Variable to store whether the source code compiled.
+#   Will be created as an internal cache variable.
 # ``<fail-regex>``
 #   Fail if test output matches this regex.
 #
diff --git a/Modules/CheckFunctionExists.cmake b/Modules/CheckFunctionExists.cmake
index 4c4334ff8c..d277c32822 100644
--- a/Modules/CheckFunctionExists.cmake
+++ b/Modules/CheckFunctionExists.cmake
@@ -10,6 +10,7 @@
 # store the result in a <variable>.  This does not verify that any
 # system header file declares the function, only that it can be found at
 # link time (consider using CheckSymbolExists).
+# <variable> will be created as an internal cache variable.
 #
 # The following variables may be set before calling this macro to modify
 # the way the check is run:
diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake
index c217bd4693..402b37c6aa 100644
--- a/Modules/CheckIncludeFile.cmake
+++ b/Modules/CheckIncludeFile.cmake
@@ -10,6 +10,7 @@
 #
 #   INCLUDE  - name of include file
 #   VARIABLE - variable to return result
+#              Will be created as an internal cache variable.
 #
 #
 #
diff --git a/Modules/CheckIncludeFileCXX.cmake b/Modules/CheckIncludeFileCXX.cmake
index eff982cc10..eae1730fb8 100644
--- a/Modules/CheckIncludeFileCXX.cmake
+++ b/Modules/CheckIncludeFileCXX.cmake
@@ -14,6 +14,7 @@
 #
 #   INCLUDE  - name of include file
 #   VARIABLE - variable to return result
+#              Will be created as an internal cache variable.
 #
 #
 #
diff --git a/Modules/CheckIncludeFiles.cmake b/Modules/CheckIncludeFiles.cmake
index f8378c0e01..2494862457 100644
--- a/Modules/CheckIncludeFiles.cmake
+++ b/Modules/CheckIncludeFiles.cmake
@@ -12,6 +12,7 @@
 #
 #   INCLUDE  - list of files to include
 #   VARIABLE - variable to return result
+#              Will be created as an internal cache variable.
 #
 #
 #
diff --git a/Modules/CheckLibraryExists.cmake b/Modules/CheckLibraryExists.cmake
index fac5dd160c..95c595a21d 100644
--- a/Modules/CheckLibraryExists.cmake
+++ b/Modules/CheckLibraryExists.cmake
@@ -12,6 +12,7 @@
 #   FUNCTION - the name of the function
 #   LOCATION - location where the library should be found
 #   VARIABLE - variable to store the result
+#              Will be created as an internal cache variable.
 #
 #
 #
diff --git a/Modules/CheckPrototypeDefinition.cmake b/Modules/CheckPrototypeDefinition.cmake
index fe000744cc..dfa54d8ec2 100644
--- a/Modules/CheckPrototypeDefinition.cmake
+++ b/Modules/CheckPrototypeDefinition.cmake
@@ -13,6 +13,7 @@
 #   RETURN - The return value of the function.
 #   HEADER - The header files required.
 #   VARIABLE - The variable to store the result.
+#              Will be created as an internal cache variable.
 #
 # Example:
 #
diff --git a/Modules/CheckSymbolExists.cmake b/Modules/CheckSymbolExists.cmake
index c31f6b6e37..79c5ba78ee 100644
--- a/Modules/CheckSymbolExists.cmake
+++ b/Modules/CheckSymbolExists.cmake
@@ -9,6 +9,7 @@
 # Check that the <symbol> is available after including given header
 # <files> and store the result in a <variable>.  Specify the list of
 # files in one argument as a semicolon-separated list.
+# <variable> will be created as an internal cache variable.
 #
 # If the header files define the symbol as a macro it is considered
 # available and assumed to work.  If the header files declare the symbol
diff --git a/Modules/CheckTypeSize.cmake b/Modules/CheckTypeSize.cmake
index 8ce6b88c55..73ad86ebb2 100644
--- a/Modules/CheckTypeSize.cmake
+++ b/Modules/CheckTypeSize.cmake
@@ -19,6 +19,9 @@
 #    "0"    = type has arch-dependent size (see below)
 #    ""     = type does not exist
 #
+# Both ``HAVE_${VARIABLE}`` and ``${VARIABLE}`` will be created as internal
+# cache variables.
+#
 # Furthermore, the variable "${VARIABLE}_CODE" holds C preprocessor code
 # to define the macro "${VARIABLE}" to the size of the type, or leave
 # the macro undefined if the type does not exist.
diff --git a/Modules/CheckVariableExists.cmake b/Modules/CheckVariableExists.cmake
index 9e8e984146..f3e05e41b3 100644
--- a/Modules/CheckVariableExists.cmake
+++ b/Modules/CheckVariableExists.cmake
@@ -14,7 +14,7 @@
 #
 #   VAR      - the name of the variable
 #   VARIABLE - variable to store the result
-#
+#              Will be created as an internal cache variable.
 #
 #
 # This macro is only for C variables.