echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Clarify that set(VAR) unsets VAR

Browse Source 
Also call out possible exposure of an existing cache entry of the same
name, as we have for the `unset` command since commit 1a0f1a25a4 (Help:
Clarify the unset command, 2018-08-17, v3.13.0-rc1~199^2).

Issue: #24633
This commit is contained in:
Brad King 2023-03-24 14:39:48 -04:00
parent 3a9613d28f
commit 512f64289a
3 changed files with 21 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Help/command/UNSET_NOTE.txt Normal file
View File

@ -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.

13
Help/command/set.rst
View File

@ -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
^^^^^^^^^^^^^^^

11
Help/command/unset.rst
View File

@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^