From 4d384d290e2c873ad1f8d749e54b1b097df727dd Mon Sep 17 00:00:00 2001 From: Robert Maynard Date: Tue, 7 Aug 2018 08:43:22 -0400 Subject: Help: Document the $CACHE{} syntax Also add a test case for the behavior. --- Help/manual/cmake-language.7.rst | 7 +++++++ Help/manual/cmake-variables.7.rst | 1 + Help/variable/CACHE.rst | 17 +++++++++++++++++ Help/variable/ENV.rst | 7 ++++--- Tests/RunCMake/Syntax/QueryCache-stderr.txt | 2 ++ Tests/RunCMake/Syntax/QueryCache.cmake | 6 ++++++ Tests/RunCMake/Syntax/RunCMakeTest.cmake | 3 +++ 7 files changed, 40 insertions(+), 3 deletions(-) create mode 100644 Help/variable/CACHE.rst create mode 100644 Tests/RunCMake/Syntax/QueryCache-stderr.txt create mode 100644 Tests/RunCMake/Syntax/QueryCache.cmake 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 ` +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) -- cgit v0.12