mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-05-01 20:00:51 -05:00
Code Issues Packages Projects Releases Wiki Activity

Help: Clarify role and importance of penv{} preset macro

Browse Source 
Preset environment variables are always set to the exact value
specified.  The `$penv{}` macro can be used to refer to the parent
environment value to append or prepend to it.

Fixes: #26216
This commit is contained in:
Benjamin Buch
2024-08-15 05:38:59 -04:00
committed by Brad King
parent 3e072b018a
commit bc5cddbea7
1 changed files with 33 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/manual/cmake-presets.7.rst
+33 -17
View File
@@ -323,10 +323,14 @@ that may contain the following fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports `macro expansion`_, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, This field supports `macro expansion`_, and environment variables in this map
if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` and the preset's environment will be the union of its own ``environment`` and
@@ -508,10 +512,14 @@ that may contain the following fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if This field supports `macro expansion`_, and environment variables in this map
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` the preset's environment will be the union of its own ``environment``
@@ -669,10 +677,14 @@ that may contain the following fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if This field supports `macro expansion`_, and environment variables in this map
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` the preset's environment will be the union of its own ``environment``
@@ -1010,10 +1022,14 @@ fields:
(which may not be an empty string), and the value is either ``null`` or (which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment environment.
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if This field supports `macro expansion`_, and environment variables in this map
``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) may reference each other, and may be listed in any order, as long as such
references do not cause a cycle (for example, if ``ENV_1`` is
``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``). ``$penv{NAME}``
allows one to prepend or append values to existing environment variables by
accessing only values from the parent environment.
Environment variables are inherited through the ``inherits`` field, and Environment variables are inherited through the ``inherits`` field, and
the preset's environment will be the union of its own ``environment`` the preset's environment will be the union of its own ``environment``
@@ -1280,7 +1296,7 @@ Recognized macros include:
``$penv{<variable-name>}`` ``$penv{<variable-name>}``
Similar to ``$env{<variable-name>}``, except that the value only comes from Similar to ``$env{<variable-name>}``, except that the value only comes from
the parent environment, and never from the ``environment`` field. This the parent environment, and never from the ``environment`` field. This
allows you to prepend or append values to existing environment variables. allows one to prepend or append values to existing environment variables.
For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
is needed because ``$env{<variable-name>}`` does not allow circular is needed because ``$env{<variable-name>}`` does not allow circular