From 9eecdc7ab7141e6bbd3289ed0172e942e20ace05 Mon Sep 17 00:00:00 2001 From: "FeRD (Frank Dana)" Date: Fri, 1 Sep 2023 21:23:34 +1000 Subject: Help: Use signature directive for cmake_policy() --- Help/command/cmake_policy.rst | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index d7880bc..dff6c3c 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 [...]) +.. signature:: cmake_policy(VERSION [...]) + :target: VERSION .. versionadded:: 3.12 The optional ```` version. @@ -57,10 +56,8 @@ command implicitly calls ``cmake_policy(VERSION)`` too. Setting Policies Explicitly ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - - cmake_policy(SET CMP NEW) - cmake_policy(SET CMP OLD) +.. signature:: cmake_policy(SET CMP 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 ) +.. signature:: cmake_policy(GET CMP ) + :target: GET Check whether a given policy is set to ``OLD`` or ``NEW`` behavior. The output ```` value will be ``OLD`` or ``NEW`` if the @@ -94,15 +90,20 @@ 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 -- cgit v0.12 From 2f319c6484a997ca957b9ca25dd69ca52ba97de5 Mon Sep 17 00:00:00 2001 From: "FeRD (Frank Dana)" Date: Wed, 30 Aug 2023 14:35:04 -0400 Subject: Help: Remove "this command" ambiguity in set() docs --- Help/command/set.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) 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)` -- cgit v0.12 From bbf3ed54229719c363f39eebf0deadecb775d3ee Mon Sep 17 00:00:00 2001 From: "FeRD (Frank Dana)" Date: Wed, 30 Aug 2023 14:37:13 -0400 Subject: Help: Explain block() policy-scope rules more clearly --- Help/command/block.rst | 3 ++- Help/command/cmake_policy.rst | 7 +++---- 2 files changed, 5 insertions(+), 5 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 dff6c3c..4a08c01 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -107,11 +107,10 @@ Calls to the :command:`cmake_minimum_required(VERSION)`, 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 -- cgit v0.12