From 512f64289a94c334269a546d86f095b1fac17cc5 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 24 Mar 2023 14:39:48 -0400 Subject: Help: Clarify that set(VAR) unsets VAR 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 --- Help/command/UNSET_NOTE.txt | 9 +++++++++ Help/command/set.rst | 13 +++++++++---- Help/command/unset.rst | 11 +++-------- 3 files changed, 21 insertions(+), 12 deletions(-) create mode 100644 Help/command/UNSET_NOTE.txt 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( "")``, 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 ``...`` placeholder expect zero or more arguments. Multiple arguments will be joined as -a :ref:`semicolon-separated list ` 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 ` to form the +actual variable value to be set. Set Normal Variable ^^^^^^^^^^^^^^^^^^^ @@ -19,7 +18,11 @@ Set Normal Variable set( ... [PARENT_SCOPE]) :target: normal - Sets the given ```` in the current function or directory scope. + Set or unset ```` in the current function or directory scope: + + * If at least one ``...`` is given, set the variable to that value. + * If no value is given, unset the variable. This is equivalent to + :command:`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( "")``, 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v0.12