Help: Document the $CACHE{} syntax

Also add a test case for the behavior.

7 files changed, 40 insertions, 3 deletions

diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst
index 87f8f9d..591f73d 100644
--- a/Help/manual/cmake-language.7.rst
+++ b/Help/manual/cmake-language.7.rst
@@ -399,6 +399,11 @@ and how their values are set.
 
 An *environment variable reference* has the form ``$ENV{VAR}`` and
 is evaluated in the same contexts as a normal variable reference.
+See :variable:`ENV` for more information.
+
+A *cache variable reference* has the form ``$CACHE{VAR}`` and
+is evaluated in the same contexts as a normal variable reference.
+See :variable:`CACHE` for more information.
 
 Comments
 --------
@@ -543,6 +548,8 @@ to the binding in the current directory scope, if any.  If a
 is found, or no binding is found, CMake then searches for a
 cache entry.  If a cache entry is found, its value is used.
 Otherwise, the variable reference evaluates to an empty string.
+The ``$CACHE{VAR}`` syntax can be used to do direct cache entry
+lookups.
 
 The :manual:`cmake-variables(7)` manual documents many variables
 that are provided by CMake or have meaning to CMake when set
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 5a3cd81..4ddbfe5 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -230,6 +230,7 @@ Variables that Describe the System
    /variable/ANDROID
    /variable/APPLE
    /variable/BORLAND
+   /variable/CACHE
    /variable/CMAKE_CL_64
    /variable/CMAKE_COMPILER_2005
    /variable/CMAKE_HOST_APPLE
diff --git a/Help/variable/CACHE.rst b/Help/variable/CACHE.rst
new file mode 100644
index 0000000..230739a
--- /dev/null
+++ b/Help/variable/CACHE.rst
@@ -0,0 +1,17 @@
+CACHE
+-----
+
+Read cache variables.
+
+Use the syntax ``$CACHE{VAR}`` to read cache entry ``VAR``.
+See the :ref:`cmake-language(7) variables <CMake Language Variables>`
+documentation for more complete documentation of the interaction of
+normal variables and cache entries.
+
+When evaluating :ref:`Variable References` of the form ``${VAR}``,
+CMake first searches for a normal variable with that name, and if not
+found CMake will search for a cache entry with that name.
+The ``$CACHE{VAR}`` syntax can be used to do direct cache lookup and
+ignore any existing normal variable.
+
+See the :command:`set` command to see how to write cache variables.
diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst
index 368152a..98677dd 100644
--- a/Help/variable/ENV.rst
+++ b/Help/variable/ENV.rst
@@ -1,7 +1,8 @@
 ENV
 ---
 
-Access environment variables.
+Read environment variables.
 
-Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``.  See also
-the :command:`set` command to set ``ENV{VAR}``.
+Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``.
+
+See the :command:`set` command to see how to write environment variables.
diff --git a/Tests/RunCMake/Syntax/QueryCache-stderr.txt b/Tests/RunCMake/Syntax/QueryCache-stderr.txt
new file mode 100644
index 0000000..db6b2b7
--- /dev/null
+++ b/Tests/RunCMake/Syntax/QueryCache-stderr.txt
@@ -0,0 +1,2 @@
+-->cache value<--
+-->local value<--
diff --git a/Tests/RunCMake/Syntax/QueryCache.cmake b/Tests/RunCMake/Syntax/QueryCache.cmake
new file mode 100644
index 0000000..20c648e
--- /dev/null
+++ b/Tests/RunCMake/Syntax/QueryCache.cmake
@@ -0,0 +1,6 @@
+
+set(query_var "cache value" CACHE STRING "")
+set(query_var "local value")
+
+message("-->$CACHE{query_var}<--")
+message("-->${query_var}<--")
diff --git a/Tests/RunCMake/Syntax/RunCMakeTest.cmake b/Tests/RunCMake/Syntax/RunCMakeTest.cmake
index b8f5fd0..a397620 100644
--- a/Tests/RunCMake/Syntax/RunCMakeTest.cmake
+++ b/Tests/RunCMake/Syntax/RunCMakeTest.cmake
@@ -112,6 +112,9 @@ run_cmake(CMP0053-NameWithCarriageReturnQuoted)
 run_cmake(CMP0053-NameWithEscapedSpacesQuoted)
 run_cmake(CMP0053-NameWithEscapedTabsQuoted)
 
+# Variable special types
+run_cmake(QueryCache)
+
 # Function and macro tests.
 run_cmake(FunctionUnmatched)
 run_cmake(FunctionUnmatchedForeach)