diff options
| -rw-r--r-- | Help/command/block.rst | 3 | ||||
| -rw-r--r-- | Help/command/cmake_policy.rst | 36 | ||||
| -rw-r--r-- | Help/command/set.rst | 11 |
3 files changed, 26 insertions, 24 deletions
diff --git a/Help/command/block.rst b/Help/command/block.rst index a352e83..4c6e111 100644 --- a/Help/command/block.rst +++ b/Help/command/block.rst @@ -21,7 +21,8 @@ scopes created by the ``block()`` command are removed. ``POLICIES`` Create a new policy scope. This is equivalent to - :command:`cmake_policy(PUSH)`. + :command:`cmake_policy(PUSH)` with an automatic + :command:`cmake_policy(POP)` when leaving the block scope. ``VARIABLES`` Create a new variable scope. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index d7880bc..4a08c01 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -24,9 +24,8 @@ The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` behavior. While setting policies individually is supported, we encourage projects to set policies based on CMake versions: -.. code-block:: cmake - - cmake_policy(VERSION <min>[...<max>]) +.. signature:: cmake_policy(VERSION <min>[...<max>]) + :target: VERSION .. versionadded:: 3.12 The optional ``<max>`` version. @@ -57,10 +56,8 @@ command implicitly calls ``cmake_policy(VERSION)`` too. Setting Policies Explicitly ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - - cmake_policy(SET CMP<NNNN> NEW) - cmake_policy(SET CMP<NNNN> OLD) +.. signature:: cmake_policy(SET CMP<NNNN> NEW|OLD) + :target: SET Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy. Projects depending on the old behavior of a given policy may silence a @@ -73,9 +70,8 @@ policy state to ``NEW``. Checking Policy Settings ^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - - cmake_policy(GET CMP<NNNN> <variable>) +.. signature:: cmake_policy(GET CMP<NNNN> <variable>) + :target: GET Check whether a given policy is set to ``OLD`` or ``NEW`` behavior. The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the @@ -94,23 +90,27 @@ except when invoked with the ``NO_POLICY_SCOPE`` option The ``cmake_policy`` command provides an interface to manage custom entries on the policy stack: -.. code-block:: cmake +.. signature:: cmake_policy(PUSH) + :target: PUSH + + Create a new entry on the policy stack. + +.. signature:: cmake_policy(POP) + :target: POP - cmake_policy(PUSH) - cmake_policy(POP) + Remove the last policy stack entry created with ``cmake_policy(PUSH)``. Each ``PUSH`` must have a matching ``POP`` to erase any changes. This is useful to make temporary changes to policy settings. Calls to the :command:`cmake_minimum_required(VERSION)`, -``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands +:command:`cmake_policy(VERSION)`, or :command:`cmake_policy(SET)` commands influence only the current top of the policy stack. .. versionadded:: 3.25 - The :command:`block` and :command:`endblock` commands offer a more flexible + The :command:`block(SCOPE_FOR POLICIES)` command offers a more flexible and more secure way to manage the policy stack. The pop action is done - automatically when the :command:`endblock` command is executed, so it avoid - to call the :command:`cmake_policy(POP)` command before each - :command:`return` command. + automatically when leaving the block scope, so there is no need to + precede each :command:`return` with a call to :command:`cmake_policy(POP)`. .. code-block:: cmake diff --git a/Help/command/set.rst b/Help/command/set.rst index aeb88b3..fa635c6 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -27,11 +27,12 @@ Set Normal Variable 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` command creates a new scope. A scope can also be created with the - :command:`block` command. This command will set the value of a variable into - the parent directory, calling function or encompassing scope (whichever is - applicable to the case at hand). The previous state of the variable's value - stays the same in the current scope (e.g., if it was undefined before, it is - still undefined and if it had a value, it is still that value). + :command:`block` command. ``set(PARENT_SCOPE)`` will set the value + of a variable into the parent directory, calling function, or + encompassing scope (whichever is applicable to the case at hand). + The previous state of the variable's value stays the same in the + current scope (e.g., if it was undefined before, it is still undefined + and if it had a value, it is still that value). The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can be used as an alternate method to the :command:`set(PARENT_SCOPE)` |