From 3de551cc22bf80f63ec9f05e3e934f42f79b8965 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sat, 27 Oct 2018 15:08:43 +0200 Subject: Help: Clarify effect of set(ENV{..} ..) and unset(ENV{..}) Explain that the commands affect 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. --- Help/command/set.rst | 8 +++++++- Help/command/unset.rst | 17 +++++++++++++---- 2 files changed, 20 insertions(+), 5 deletions(-) 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{} ...) -Sets the current process environment ```` to the given value. +Sets an :manual:`Environment Variable ` +to the given value. +Subsequent calls of ``$ENV{}`` 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( [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. -```` can be an environment variable such as: +Unset Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: cmake - unset(ENV{LD_LIBRARY_PATH}) + unset(ENV{}) + +Removes ```` from the currently available +:manual:`Environment Variables `. +Subsequent calls of ``$ENV{}`` 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. -- cgit v0.12 From e4554149c476e9eb9fe00368b2ac1ac7ac9ffe5c Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sat, 27 Oct 2018 15:27:31 +0200 Subject: Help: Remove over-precise clause. Section "Variables References" said that environment and cache variables are "evaluated in the same contexts as a normal variable reference". The reader has to guess what "contexts" means in this context. Probably "inside a Quoted Argument or an Unquoted Argument", exactly as for ordinary variable references. But this is exactly what the reader would tacitly assume anyway. Therefore I think the removed clause was unnecessary, and possibly more confusing than helpful. --- Help/manual/cmake-language.7.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 630a86b..0283232 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -405,12 +405,10 @@ 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. +An *environment variable reference* has the form ``$ENV{VAR}``. 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. +A *cache variable reference* has the form ``$CACHE{VAR}``. See :variable:`CACHE` for more information. Comments -- cgit v0.12 From e24ef9694275b9345bf08cf46ca1cf064b34813b Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sat, 27 Oct 2018 15:53:05 +0200 Subject: Help: New section on Environment Variables in cmake-language.7 --- Help/manual/cmake-language.7.rst | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 0283232..ef5bb50 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -406,7 +406,7 @@ The `Variables`_ section documents the scope of variable names and how their values are set. An *environment variable reference* has the form ``$ENV{VAR}``. -See :variable:`ENV` for more information. +See the `Environment Variables`_ section for more information. A *cache variable reference* has the form ``$CACHE{VAR}``. See :variable:`CACHE` for more information. @@ -563,6 +563,33 @@ by project code. .. _`CMake Language Lists`: +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{}``. + +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. + + Lists ===== -- cgit v0.12 From 85498fccd8ac1dd7345d995e52e1bf63d663071e Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sat, 27 Oct 2018 16:04:15 +0200 Subject: Help: Provide backreferences. Short intro to pages cmake-variables.7 and cmake-env-variables.7, with backlinks to cmake-language.7. --- Help/manual/cmake-env-variables.7.rst | 8 ++++++++ Help/manual/cmake-language.7.rst | 5 +++-- Help/manual/cmake-variables.7.rst | 8 ++++++++ 3 files changed, 19 insertions(+), 2 deletions(-) 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 ` +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 ef5bb50..1b5281a 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -557,11 +557,11 @@ 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 Lists`: +.. _`CMake Language Environment Variables`: Environment Variables ===================== @@ -589,6 +589,7 @@ Initialization 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..efb217d 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 ` +section in the cmake-language manual. + + Variables that Provide Information ================================== -- cgit v0.12 From 8ba2a8d4a415d2288786a0d56e90b3d7693ad32e Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 1 Nov 2018 11:13:03 +0100 Subject: Help: short/long variable reference in if command Explain that the short form of variable references in the if command does not apply to ENV and CACHE vars. --- Help/command/if.rst | 6 +++++- Help/manual/cmake-language.7.rst | 12 +++++++++--- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/Help/command/if.rst b/Help/command/if.rst index 4781f35..ea5de7f 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -231,7 +231,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 ````: +above-documented condition syntax accepts ````: * 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 +269,7 @@ 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 short form for environment or cache :ref:`Variable References`. +They can be referenced as ``$ENV{}`` or ``$CACHE{}`` +wherever the above-documented condition syntax accepts . diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 1b5281a..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 ``${}`` 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,12 +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}``. +An *environment variable reference* has the form ``$ENV{}``. See the `Environment Variables`_ section for more information. -A *cache variable reference* has the form ``$CACHE{VAR}``. +A *cache variable reference* has the form ``$CACHE{}``. See :variable:`CACHE` for more information. +The :command:`if` command has a special condition syntax that +allows for variable references in the short form ```` +instead of ``${}``. +However, environment and cache variables always need to be +referenced as ``$ENV{}`` or ``$CACHE{}``. + Comments -------- -- cgit v0.12 From e855bd5248bbb7b77b45e269e4fa098b29c9e889 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Thu, 1 Nov 2018 22:26:32 +0100 Subject: Help: Document if(DEFINED ENV{name}) --- Help/command/if.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Help/command/if.rst b/Help/command/if.rst index ea5de7f..1cd9965 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -187,10 +187,11 @@ Possible conditions are: ``if( IN_LIST )`` True if the given element is contained in the named list variable. -``if(DEFINED )`` - 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 |ENV{})`` + True if a variable or environment variable + with given ```` 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 @@ -270,6 +271,7 @@ 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 short form for environment or cache :ref:`Variable References`. -They can be referenced as ``$ENV{}`` or ``$CACHE{}`` -wherever the above-documented condition syntax accepts . +There is no automatic evaluation for environment or cache +:ref:`Variable References`. Their values must be referenced as +``$ENV{}`` or ``$CACHE{}`` wherever the above-documented +condition syntax accepts ````. -- cgit v0.12 From 860338491ee96274ac110459b3b316149d4585f7 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 1 Nov 2018 11:18:15 +0100 Subject: Help: Describe $CACHE and $ENV as operators This resolves issue #18514 Also add a cross-reference to if(DEFINED ENV{var}). --- Help/manual/cmake-variables.7.rst | 11 +++++++++-- Help/variable/CACHE.rst | 5 +++-- Help/variable/ENV.rst | 8 ++++++-- 3 files changed, 18 insertions(+), 6 deletions(-) diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index efb217d..7a7f0b8 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -241,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 @@ -260,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 @@ -599,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 ` @@ -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{})`` of the :command:`if` command. + +See the :command:`set` and :command:`unset` commands to see how to +write or remove environment variables. -- cgit v0.12