Merge topic 'env'

860338491e Help: Describe $CACHE and $ENV as operators
e855bd5248 Help: Document if(DEFINED ENV{name})
8ba2a8d4a4 Help: short/long variable reference in if command
85498fccd8 Help: Provide backreferences.
e24ef96942 Help: New section on Environment Variables in cmake-language.7
e4554149c4 Help: Remove over-precise clause.
3de551cc22 Help: Clarify effect of set(ENV{..} ..) and unset(ENV{..})

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2538

8 files changed, 104 insertions, 23 deletions

diff --git a/Help/command/if.rst b/Help/command/if.rst
index 4781f35..1cd9965 100644
--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@@ -187,10 +187,11 @@ Possible conditions are:
 ``if(<variable|string> IN_LIST <variable>)``
  True if the given element is contained in the named list variable.
 
-``if(DEFINED <variable>)``
- True if the given variable is defined.  It does not matter if the
- variable is true or false just if it has been set.  (Note macro
- arguments are not variables.)
+``if(DEFINED <name>|ENV{<name>})``
+ True if a variable or environment variable
+ with given ``<name>`` is defined.
+ The value of the variable does not matter.
+ Note that macro arguments are not variables.
 
 ``if((condition) AND (condition OR (condition)))``
  The conditions inside the parenthesis are evaluated first and then
@@ -231,7 +232,7 @@ which is true because ``var2`` is defined to "var1" which is not a false
 constant.
 
 Automatic evaluation applies in the other cases whenever the
-above-documented signature accepts ``<variable|string>``:
+above-documented condition syntax accepts ``<variable|string>``:
 
 * The left hand argument to ``MATCHES`` is first checked to see if it is
   a defined variable, if so the variable's value is used, otherwise the
@@ -269,3 +270,8 @@ specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`.
 A quoted or bracketed variable or keyword will be interpreted as a
 string and not dereferenced or interpreted.
 See policy :policy:`CMP0054`.
+
+There is no automatic evaluation for environment or cache
+:ref:`Variable References`.  Their values must be referenced as
+``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
+condition syntax accepts ``<variable|string>``.
diff --git a/Help/command/set.rst b/Help/command/set.rst
index e37e693..dd5ea13 100644
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@@ -88,4 +88,10 @@ Set Environment Variable
 
   set(ENV{<variable>} <value>...)
 
-Sets the current process environment ``<variable>`` to the given value.
+Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
+to the given value.
+Subsequent calls of ``$ENV{<variable>}`` will return this new value.
+
+This command affects only the current CMake process, not the process
+from which CMake was called, nor the system environment at large,
+nor the environment of subsequent build or test processes.
diff --git a/Help/command/unset.rst b/Help/command/unset.rst
index 1a5e49f..7521052 100644
--- a/Help/command/unset.rst
+++ b/Help/command/unset.rst
@@ -3,6 +3,9 @@ unset
 
 Unset a variable, cache variable, or environment variable.
 
+Unset Normal Variable or Cache Entry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. code-block:: cmake
 
   unset(<variable> [CACHE | PARENT_SCOPE])
@@ -22,11 +25,17 @@ If ``PARENT_SCOPE`` is present then the variable is removed from the scope
 above the current scope.  See the same option in the :command:`set` command
 for further details.
 
-``<variable>`` can be an environment variable such as:
+Unset Environment Variable
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: cmake
 
-  unset(ENV{LD_LIBRARY_PATH})
+  unset(ENV{<variable>})
+
+Removes ``<variable>`` from the currently available
+:manual:`Environment Variables <cmake-env-variables(7)>`.
+Subsequent calls of ``$ENV{<variable>}`` will return the empty string.
 
-in which case the variable will be removed from the current
-environment.
+This command affects only the current CMake process, not the process
+from which CMake was called, nor the system environment at large,
+nor the environment of subsequent build or test processes.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index 31aa723..edf80f4 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -7,6 +7,14 @@ cmake-env-variables(7)
 
    .. contents::
 
+This page lists environment variables that have special
+meaning to CMake.
+
+For general information on environment variables, see the
+:ref:`Environment Variables <CMake Language Environment Variables>`
+section in the cmake-language manual.
+
+
 Environment Variables that Control the Build
 ============================================
 
diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst
index 630a86b..5e5cfff 100644
--- a/Help/manual/cmake-language.7.rst
+++ b/Help/manual/cmake-language.7.rst
@@ -389,7 +389,7 @@ historical considerations.)
 Variable References
 -------------------
 
-A *variable reference* has the form ``${variable_name}`` and is
+A *variable reference* has the form ``${<variable>}`` and is
 evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_.
 A variable reference is replaced by the value of the variable,
 or by the empty string if the variable is not set.
@@ -405,14 +405,18 @@ the ``$`` is also technically permitted but is discouraged.
 The `Variables`_ section documents the scope of variable names
 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.
+An *environment variable reference* has the form ``$ENV{<variable>}``.
+See the `Environment Variables`_ section for more information.
 
-A *cache variable reference* has the form ``$CACHE{VAR}`` and
-is evaluated in the same contexts as a normal variable reference.
+A *cache variable reference* has the form ``$CACHE{<variable>}``.
 See :variable:`CACHE` for more information.
 
+The :command:`if` command has a special condition syntax that
+allows for variable references in the short form ``<variable>``
+instead of ``${<variable>}``.
+However, environment and cache variables always need to be
+referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``.
+
 Comments
 --------
 
@@ -559,10 +563,38 @@ 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
+The :manual:`cmake-variables(7)` manual documents the many variables
 that are provided by CMake or have meaning to CMake when set
 by project code.
 
+.. _`CMake Language Environment Variables`:
+
+Environment Variables
+=====================
+
+Environment Variables are like ordinary `Variables`_, with the
+following differences:
+
+Scope
+ Environment variables have global scope in a CMake process.
+ They are never cached.
+
+References
+ `Variable References`_ have the form ``$ENV{<variable>}``.
+
+Initialization
+ Initial values of the CMake environment variables are those of
+ the calling process.
+ Values can be changed using the :command:`set` and :command:`unset`
+ commands.
+ These commands only affect the running CMake process,
+ not the system environment at large.
+ Changed values are not written back to the calling process,
+ and they are not seen by subsequent build or test processes.
+
+The :manual:`cmake-env-variables(7)` manual documents environment
+variables that have special meaning to CMake.
+
 .. _`CMake Language Lists`:
 
 Lists
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 9b12fc5..7a7f0b8 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -7,6 +7,14 @@ cmake-variables(7)
 
    .. contents::
 
+This page  documents variables that are provided by CMake
+or have meaning to CMake when set by project code.
+
+For general information on variables, see the
+:ref:`Variables <CMake Language Variables>`
+section in the cmake-language manual.
+
+
 Variables that Provide Information
 ==================================
 
@@ -233,7 +241,6 @@ 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
@@ -252,7 +259,6 @@ Variables that Describe the System
    /variable/CMAKE_SYSTEM_PROCESSOR
    /variable/CMAKE_SYSTEM_VERSION
    /variable/CYGWIN
-   /variable/ENV
    /variable/GHS-MULTI
    /variable/MINGW
    /variable/MSVC
@@ -591,3 +597,12 @@ Variables for CPack
    /variable/CPACK_PACKAGING_INSTALL_PREFIX
    /variable/CPACK_SET_DESTDIR
    /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
+
+Variable Expansion Operators
+============================
+
+.. toctree::
+   :maxdepth: 1
+
+   /variable/CACHE
+   /variable/ENV
diff --git a/Help/variable/CACHE.rst b/Help/variable/CACHE.rst
index 230739a..2cef27e 100644
--- a/Help/variable/CACHE.rst
+++ b/Help/variable/CACHE.rst
@@ -1,7 +1,7 @@
 CACHE
 -----
 
-Read cache variables.
+Operator to read cache variables.
 
 Use the syntax ``$CACHE{VAR}`` to read cache entry ``VAR``.
 See the :ref:`cmake-language(7) variables <CMake Language Variables>`
@@ -14,4 +14,5 @@ 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.
+See the :command:`set` and :command:`unset` commands to see how to
+write or remove cache variables.
diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst
index 98677dd..2b43934 100644
--- a/Help/variable/ENV.rst
+++ b/Help/variable/ENV.rst
@@ -1,8 +1,12 @@
 ENV
 ---
 
-Read environment variables.
+Operator to read environment variables.
 
 Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``.
 
-See the :command:`set` command to see how to write environment variables.
+To test whether an environment variable is defined, use the signature
+``if(DEFINED ENV{<name>})`` of the :command:`if` command.
+
+See the :command:`set` and :command:`unset` commands to see how to
+write or remove environment variables.