diff options
| -rw-r--r-- | Help/command/UNSET_NOTE.txt | 9 | ||||
| -rw-r--r-- | Help/command/set.rst | 13 | ||||
| -rw-r--r-- | Help/command/unset.rst | 11 |
3 files changed, 21 insertions, 12 deletions
diff --git a/Help/command/UNSET_NOTE.txt b/Help/command/UNSET_NOTE.txt new file mode 100644 index 0000000..8dc9125 --- /dev/null +++ b/Help/command/UNSET_NOTE.txt @@ -0,0 +1,9 @@ +.. note:: + + When evaluating :ref:`Variable References` of the form ``${VAR}``, CMake + first searches for a normal variable with that name. If no such normal + variable exists, CMake will then search for a cache entry with that name. + Because of this, **unsetting a normal variable can expose a cache variable + that was previously hidden**. To force a variable reference of the form + ``${VAR}`` to return an empty string, use ``set(<variable> "")``, which + clears the normal variable but leaves it defined. diff --git a/Help/command/set.rst b/Help/command/set.rst index ee677c9..aeb88b3 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -8,9 +8,8 @@ and cache entries. Signatures of this command that specify a ``<value>...`` placeholder expect zero or more arguments. Multiple arguments will be joined as -a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable -value to be set. Zero arguments will cause normal variables to be -unset. See the :command:`unset` command to unset variables explicitly. +a :ref:`semicolon-separated list <CMake Language Lists>` to form the +actual variable value to be set. Set Normal Variable ^^^^^^^^^^^^^^^^^^^ @@ -19,7 +18,11 @@ Set Normal Variable set(<variable> <value>... [PARENT_SCOPE]) :target: normal - Sets the given ``<variable>`` in the current function or directory scope. + Set or unset ``<variable>`` in the current function or directory scope: + + * If at least one ``<value>...`` is given, set the variable to that value. + * If no value is given, unset the variable. This is equivalent to + :command:`unset(<variable>) <unset>`. If the ``PARENT_SCOPE`` option is given the variable will be set in the scope above the current scope. Each new directory or :command:`function` @@ -34,6 +37,8 @@ Set Normal Variable can be used as an alternate method to the :command:`set(PARENT_SCOPE)` and :command:`unset(PARENT_SCOPE)` commands to update the parent scope. +.. include:: UNSET_NOTE.txt + Set Cache Entry ^^^^^^^^^^^^^^^ diff --git a/Help/command/unset.rst b/Help/command/unset.rst index 1cd1398..522be89 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -12,19 +12,14 @@ Unset Normal Variable or Cache Entry Removes a normal variable from the current scope, causing it to become undefined. If ``CACHE`` is present, then a cache variable -is removed instead of a normal variable. Note that when evaluating -:ref:`Variable References` of the form ``${VAR}``, CMake first searches -for a normal variable with that name. If no such normal variable exists, -CMake will then search for a cache entry with that name. Because of this -unsetting a normal variable can expose a cache variable that was previously -hidden. To force a variable reference of the form ``${VAR}`` to return an -empty string, use ``set(<variable> "")``, which clears the normal variable -but leaves it defined. +is removed instead of a normal variable. 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. +.. include:: UNSET_NOTE.txt + Unset Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^^^ |