diff options
Diffstat (limited to 'Help/command')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 3 | ||||
| -rw-r--r-- | Help/command/FIND_XXX_REGISTRY_VIEW.txt | 32 | ||||
| -rw-r--r-- | Help/command/block.rst | 74 | ||||
| -rw-r--r-- | Help/command/cmake_language.rst | 1 | ||||
| -rw-r--r-- | Help/command/cmake_policy.rst | 41 | ||||
| -rw-r--r-- | Help/command/ctest_test.rst | 8 | ||||
| -rw-r--r-- | Help/command/endblock.rst | 11 | ||||
| -rw-r--r-- | Help/command/file.rst | 7 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 9 | ||||
| -rw-r--r-- | Help/command/set.rst | 17 |
10 files changed, 172 insertions, 31 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index aa06d49..59a4e71 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -187,7 +187,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| 6. Search cmake variables defined in the Platform files - for the current system. The searching of ``CMAKE_INSTALL_PREFIX`` can be + for the current system. The searching of ``CMAKE_INSTALL_PREFIX`` and + ``CMAKE_STAGING_PREFIX`` can be skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the diff --git a/Help/command/FIND_XXX_REGISTRY_VIEW.txt b/Help/command/FIND_XXX_REGISTRY_VIEW.txt index 39b156f..6cab1d1 100644 --- a/Help/command/FIND_XXX_REGISTRY_VIEW.txt +++ b/Help/command/FIND_XXX_REGISTRY_VIEW.txt @@ -1,15 +1,15 @@ Specify which registry views must be queried. This option is only meaningful -on ``Windows`` platform and will be ignored on other ones. When not -specified, |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when :policy:`CMP0134` -policy is ``NEW``. Refer to :policy:`CMP0134` policy for default view when -policy is ``OLD`` or undefined. +on ``Windows`` platforms and will be ignored on other ones. When not +specified, the |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when the +:policy:`CMP0134` policy is ``NEW``. Refer to :policy:`CMP0134` for the +default view when the policy is ``OLD``. ``64`` - Query the 64bit registry. On ``32bit Windows``, returns always the string + Query the 64-bit registry. On 32-bit Windows, it always returns the string ``/REGISTRY-NOTFOUND``. ``32`` - Query the 32bit registry. + Query the 32-bit registry. ``64_32`` Query both views (``64`` and ``32``) and generate a path for each. @@ -18,24 +18,24 @@ policy is ``OLD`` or undefined. Query both views (``32`` and ``64``) and generate a path for each. ``HOST`` - Query the registry matching the architecture of the host: ``64`` on ``64bit - Windows`` and ``32`` on ``32bit Windows``. + Query the registry matching the architecture of the host: ``64`` on 64-bit + Windows and ``32`` on 32-bit Windows. ``TARGET`` - Query the registry matching the architecture specified by - :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to + Query the registry matching the architecture specified by the + :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fall back to ``HOST`` view. ``BOTH`` - Query both views (``32`` and ``64``). The order depends of the following - rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the - following view depending of the content of this variable: + Query both views (``32`` and ``64``). The order depends on the following + rules: If the :variable:`CMAKE_SIZEOF_VOID_P` variable is defined, use the + following view depending on the content of this variable: * ``8``: ``64_32`` * ``4``: ``32_64`` - If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on + If the :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on the architecture of the host: - * ``64bit``: ``64_32`` - * ``32bit``: ``32`` + * 64-bit: ``64_32`` + * 32-bit: ``32`` diff --git a/Help/command/block.rst b/Help/command/block.rst new file mode 100644 index 0000000..f9d85c8 --- /dev/null +++ b/Help/command/block.rst @@ -0,0 +1,74 @@ +block +----- + +.. versionadded:: 3.25 + +Evaluate a group of commands with a dedicated variable and/or policy scope. + +.. code-block:: cmake + + block([SCOPE_FOR (POLICIES|VARIABLES)] [PROPAGATE <var-name>...]) + <commands> + endblock() + +All commands between ``block()`` and the matching :command:`endblock` are +recorded without being invoked. Once the :command:`endblock` is evaluated, the +recorded list of commands is invoked inside the requested scopes, and, finally, +the scopes created by ``block()`` command are removed. + +``SCOPE_FOR`` + Specify which scopes must be created. + + ``POLICIES`` + Create a new policy scope. This is equivalent to + :command:`cmake_policy(PUSH)`. + + ``VARIABLES`` + Create a new variable scope. + + If ``SCOPE_FOR`` is not specified, this is equivalent to: + + .. code-block:: cmake + + block(SCOPE_FOR VARIABLES POLICIES) + +``PROPAGATE`` + When a variable scope is created by :command:`block` command, this option + set or unset the specified variables in the parent scope. This is equivalent + to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)` commands. + + .. code-block:: cmake + + set(VAR1 "INIT1") + set(VAR2 "INIT2") + + block(PROPAGATE VAR1 VAR2) + set(VAR1 "VALUE1") + unset(VAR2) + endblock() + + # here, VAR1 holds value VALUE1 and VAR2 is unset + + This option is only allowed when a variable scope is created. An error will + be raised in the other cases. + +When the ``block`` is local to a :command:`foreach` or :command:`while` +command, the commands :command:`break` and :command:`continue` can be used +inside this block. + +.. code-block:: cmake + + while(TRUE) + block() + ... + # the break() command will terminate the while() command + break() + endblock() + endwhile() + + +See Also +^^^^^^^^ + + * :command:`endblock` + * :command:`cmake_policy` diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index d0c7c19..8801a9f 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -51,6 +51,7 @@ is equivalent to To ensure consistency of the code, the following commands are not allowed: * ``if`` / ``elseif`` / ``else`` / ``endif`` + * ``block`` / ``endblock`` * ``while`` / ``endwhile`` * ``foreach`` / ``endforeach`` * ``function`` / ``endfunction`` diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index 94060d9..54fc548 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -103,6 +103,47 @@ Calls to the :command:`cmake_minimum_required(VERSION)`, ``cmake_policy(VERSION)``, or ``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 + 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. + + .. code-block:: cmake + + # stack management with cmake_policy() + function(my_func) + cmake_policy(PUSH) + cmake_policy(SET ...) + if (<cond1>) + ... + cmake_policy(POP) + return() + elseif(<cond2>) + ... + cmake_policy(POP) + return() + endif() + ... + cmake_policy(POP) + endfunction() + + # stack management with block()/endblock() + function(my_func) + block(SCOPE_FOR POLICIES) + cmake_policy(SET ...) + if (<cond1>) + ... + return() + elseif(<cond2>) + ... + return() + endif() + ... + endblock() + endfunction() + Commands created by the :command:`function` and :command:`macro` commands record policy settings when they are created and use the pre-record policies when they are invoked. If the function or diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index f058150..4f9f891 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -175,7 +175,11 @@ The options are: See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`, :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and -:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables. +:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their +corresponding :manual:`ctest(1)` command line options +:option:`--test-output-size-passed <ctest --test-output-size-passed>`, +:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and +:option:`--test-output-truncation <ctest --test-output-truncation>`. .. _`Additional Test Measurements`: @@ -237,7 +241,7 @@ The following example demonstrates how to upload test images to CDash. "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl; std::cout << - "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << + "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" << "/dir/to/img.png</CTestMeasurementFile>" << std::endl; diff --git a/Help/command/endblock.rst b/Help/command/endblock.rst new file mode 100644 index 0000000..3b21c12 --- /dev/null +++ b/Help/command/endblock.rst @@ -0,0 +1,11 @@ +endblock +-------- + +.. versionadded:: 3.25 + +Ends a list of commands in a :command:`block` and removes the scopes +created by the :command:`block` command. + +.. code-block:: cmake + + endblock() diff --git a/Help/command/file.rst b/Help/command/file.rst index 3374d2d..fbe2a81 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -1121,8 +1121,11 @@ Additional options to ``DOWNLOAD`` are: Verify that the downloaded content hash matches the expected value, where ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``. - If it does not match, the operation fails with an error. It is an error to - specify this if ``DOWNLOAD`` is not given a ``<file>``. + If the file already exists and matches the hash, the download is skipped. + If the file already exists and does not match the hash, the file is + downloaded again. If after download the file does not match the hash, the + operation fails with an error. It is an error to specify this option if + ``DOWNLOAD`` is not given a ``<file>``. ``EXPECTED_MD5 <value>`` Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 717f822..7f076f9 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -142,9 +142,9 @@ should find all components, no components or some well-defined subset of the available components. .. versionadded:: 3.24 - The ``REGISTRY_VIEW`` keyword enables to specify which registry views must be - queried. This keyword is only meaningful on ``Windows`` platform and will be - ignored on all other ones. Formally, it is up to the target package how to + The ``REGISTRY_VIEW`` keyword specifies which registry views should be + queried. This keyword is only meaningful on ``Windows`` platforms and will + be ignored on all others. Formally, it is up to the target package how to interpret the registry view information given to it. .. versionadded:: 3.24 @@ -413,7 +413,8 @@ enabled. package registry. 7. Search cmake variables defined in the Platform files for the - current system. The searching of :variable:`CMAKE_INSTALL_PREFIX` can be + current system. The searching of :variable:`CMAKE_INSTALL_PREFIX` and + :variable:`CMAKE_STAGING_PREFIX` can be skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the diff --git a/Help/command/set.rst b/Help/command/set.rst index af862e4..aa2ea55 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -22,12 +22,17 @@ Set Normal Variable Sets the given ``<variable>`` in the current function or directory scope. If the ``PARENT_SCOPE`` option is given the variable will be set in -the scope above the current scope. Each new directory or function -creates a new scope. This command will set the value of a variable -into the parent directory or calling function (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 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). + +The :command:`block(PROPAGATE)` command can be used as an alternate method to +:command:`set(PARENT_SCOPE)` and :command:`unset(PARENT_SCOPE)` commands to +update the parent scope. Set Cache Entry ^^^^^^^^^^^^^^^ |