diff options
Diffstat (limited to 'Help')
60 files changed, 989 insertions, 155 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 ^^^^^^^^^^^^^^^ diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index 69f6748..3dac68a 100644 --- a/Help/guide/tutorial/A Basic Starting Point.rst +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -160,7 +160,7 @@ The last command to call for a basic project is :name: CMakeLists.txt-add_executable :language: cmake :start-after: # add the executable - :end-before: # add the binary tree to the search path for include files + :end-before: # TODO 9: .. raw:: html @@ -240,7 +240,7 @@ the following: :name: tutorial.cxx-cxx11 :language: c++ :start-after: // convert input to double - :end-before: // calculate square root + :end-before: // TODO 12: .. raw:: html @@ -265,7 +265,7 @@ add the :variable:`CMAKE_CXX_STANDARD` declarations above the call to :name: CMakeLists.txt-CXX_STANDARD :language: cmake :start-after: # specify the C++ standard - :end-before: # configure a header file to pass some of the CMake settings + :end-before: # TODO 7: .. raw:: html @@ -345,7 +345,7 @@ lets us maintain a single source of data for the version number. First, we modify the ``CMakeLists.txt`` file to use the :command:`project` command to set both the project name and version number. -When the command:`project` command is called, CMake defines +When the :command:`project` command is called, CMake defines ``Tutorial_VERSION_MAJOR`` and ``Tutorial_VERSION_MINOR`` behind the scenes. .. raw:: html @@ -375,7 +375,7 @@ specified CMake variables replaced: :name: CMakeLists.txt-configure_file :language: cmake :start-after: # to the source code - :end-before: # add the executable + :end-before: # TODO 8: .. raw:: html @@ -420,6 +420,7 @@ be replaced with the corresponding version numbers from the project in :caption: TODO 10: TutorialConfig.h.in :name: TutorialConfig.h.in :language: c++ + :end-before: // TODO 13: .. raw:: html diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst index a8e914e..b521896 100644 --- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -1,52 +1,142 @@ Step 3: Adding Usage Requirements for a Library =============================================== -Usage requirements allow for far better control over a library or executable's -link and include line while also giving more control over the transitive -property of targets inside CMake. The primary commands that leverage usage -requirements are: - - - :command:`target_compile_definitions` - - :command:`target_compile_options` - - :command:`target_include_directories` - - :command:`target_link_libraries` - -Let's refactor our code from :guide:`tutorial/Adding a Library` to use the -modern CMake approach of usage requirements. We first state that anybody -linking to ``MathFunctions`` needs to include the current source directory, -while ``MathFunctions`` itself doesn't. So this can become an ``INTERFACE`` -usage requirement. - -Remember ``INTERFACE`` means things that consumers require but the producer -doesn't. Add the following lines to the end of -``MathFunctions/CMakeLists.txt``: +Exercise 1 - Adding Usage Requirements for a Library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Usage requirements allow for far better control over a library or +executable's link and include line while also giving more control over the +transitive property of targets inside CMake. The primary commands that +leverage usage requirements are: + +* :command:`target_compile_definitions` +* :command:`target_compile_options` +* :command:`target_include_directories` +* :command:`target_link_libraries` + +Goal +---- + +Add usage requirements for a library. + +Helpful Materials +----------------- + +* :command:`target_include_directories` +* :variable:`CMAKE_CURRENT_SOURCE_DIR` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` +* ``CMakeLists.txt`` + +Getting Started +--------------- + +In this exercise, we will refactor our code from +:guide:`tutorial/Adding a Library` to use the modern CMake approach. We will +let our library define its own usage requirements so they are passed +transitively to other targets as necessary. In this case, ``MathFunctions`` +will specify any needed include directories itself. Then, the consuming target +``Tutorial`` simply needs to link to ``MathFunctions`` and not worry about +any additional include directories. + +The starting source code is provided in the ``Step3`` directory. In this +exercise, complete ``TODO 1`` through ``TODO 3``. + +First, add a call to :command:`target_include_directories` in +``MathFunctions/CMakeLists``. Remember that +:variable:`CMAKE_CURRENT_SOURCE_DIR` is the path to the source directory +currently being processed. + +Then, update (and simplify!) the call to +:command:`target_include_directories` in the top-level ``CMakeLists.txt``. + +Build and Run +------------- + +Make a new directory called ``Step3_build``, run the :manual:`cmake +<cmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>` to +configure the project and then build it with your chosen build tool or by +using ``cmake --build .`` from the build directory. Here's a refresher of +what that looks like from the command line: + +.. code-block:: console + + mkdir Step3_build + cd Step3_build + cmake ../Step3 + cmake --build . + +Next, use the newly built ``Tutorial`` and verify that it is working as +expected. + +Solution +-------- + +Let's update the code from the previous step to use the modern CMake +approach of usage requirements. + +We want to state that anybody linking to ``MathFunctions`` needs to include +the current source directory, while ``MathFunctions`` itself doesn't. This +can be expressed with an ``INTERFACE`` usage requirement. Remember +``INTERFACE`` means things that consumers require but the producer doesn't. + +At the end of ``MathFunctions/CMakeLists.txt``, use +:command:`target_include_directories` with the ``INTERFACE`` keyword, as +follows: + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> .. literalinclude:: Step4/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt + :caption: TODO 1: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE :language: cmake :start-after: # to find MathFunctions.h -Now that we've specified usage requirements for ``MathFunctions`` we can safely -remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level +.. raw:: html + + </details> + +Now that we've specified usage requirements for ``MathFunctions`` we can +safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level ``CMakeLists.txt``, here: +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + .. literalinclude:: Step4/CMakeLists.txt - :caption: CMakeLists.txt + :caption: TODO 2: CMakeLists.txt :name: CMakeLists.txt-remove-EXTRA_INCLUDES :language: cmake :start-after: # add the MathFunctions library :end-before: # add the executable +.. raw:: html + + </details> + And here: +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + .. literalinclude:: Step4/CMakeLists.txt - :caption: CMakeLists.txt + :caption: TODO 3: CMakeLists.txt :name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES :language: cmake :start-after: # so that we will find TutorialConfig.h -Once this is done, run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool or by using ``cmake --build .`` from the build -directory. +.. raw:: html + + </details> + +Notice that with this technique, the only thing our executable target does to +use our library is call :command:`target_link_libraries` with the name +of the library target. In larger projects, the classic method of specifying +library dependencies manually becomes very complicated very quickly. diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index 71755be..46a8909 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst @@ -1,136 +1,458 @@ Step 2: Adding a Library ======================== -Now we will add a library to our project. This library will contain our own +At this point, we have seen how to create a basic project using CMake. In this +step, we will learn how to create and use a library in our project. We will +also see how to make the use of our library optional. + +Exercise 1 - Creating a Library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add a library in CMake, use the :command:`add_library` command and specify +which source files should make up the library. + +Rather than placing all of the source files in one directory, we can organize +our project with one or more subdirectories. In this case, we will create a +subdirectory specifically for our library. Here, we can add a new +``CMakeLists.txt`` file and one or more source files. In the top level +``CMakeLists.txt`` file, we will use the :command:`add_subdirectory` command +to add the subdirectory to the build. + +Once the library is created, it is connected to our executable target with +:command:`target_include_directories` and :command:`target_link_libraries`. + +Goal +---- + +Add and use a library. + +Helpful Resources +----------------- + +* :command:`add_library` +* :command:`add_subdirectory` +* :command:`target_include_directories` +* :command:`target_link_libraries` +* :variable:`PROJECT_SOURCE_DIR` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``tutorial.cxx`` +* ``MathFunctions/CMakeLists.txt`` + +Getting Started +--------------- + +In this exercise, we will add a library to our project that contains our own implementation for computing the square root of a number. The executable can then use this library instead of the standard square root function provided by the compiler. -For this tutorial we will put the library into a subdirectory -called ``MathFunctions``. This directory already contains a header file, -``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one -function called ``mysqrt`` that provides similar functionality to the -compiler's ``sqrt`` function. +For this tutorial we will put the library into a subdirectory called +``MathFunctions``. This directory already contains a header file, +``MathFunctions.h``, and a source file ``mysqrt.cxx``. We will not need to +modify either of these files. The source file has one function called +``mysqrt`` that provides similar functionality to the compiler's ``sqrt`` +function. + +From the ``Help/guide/tutorial/Step2`` directory, start with ``TODO 1`` and +complete through ``TODO 6``. + +First, fill in the one line ``CMakeLists.txt`` in the ``MathFunctions`` +subdirectory. + +Next, edit the top level ``CMakeLists.txt``. + +Finally, use the newly created ``MathFunctions`` library in ``tutorial.cxx`` + +Build and Run +------------- + +Run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. + +Below is a refresher of what that looks like from the command line: + +.. code-block:: console + + mkdir Step2_build + cd Step2_build + cmake ../Step2 + cmake --build . + +Try to use the newly built ``Tutorial`` and ensure that it is still +producing accurate square root values. + +Solution +-------- + +In the ``CMakeLists.txt`` file in the ``MathFunctions`` directory, we create +a library target called ``MathFunctions`` with :command:`add_library`. The +source file for the library is passed as an argument to +:command:`add_library`. This looks like the following line: -Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` -directory: +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> .. literalinclude:: Step3/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt + :caption: TODO 1: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library :language: cmake + :end-before: # TODO 1 + +.. raw:: html + + </details> To make use of the new library we will add an :command:`add_subdirectory` call in the top-level ``CMakeLists.txt`` file so that the library will get -built. We add the new library to the executable, and add ``MathFunctions`` as -an include directory so that the ``MathFunctions.h`` header file can be found. -The last few lines of the top-level ``CMakeLists.txt`` file should now look -like: +built. + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-add_subdirectory + + add_subdirectory(MathFunctions) + +.. raw:: html + + </details> + +Next, the new library target is linked to the executable target using +:command:`target_link_libraries`. + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 3: CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries + + target_link_libraries(Tutorial PUBLIC MathFunctions) + +.. raw:: html + + </details> + +Finally we need to specify the library's header file location. Modify +:command:`target_include_directories` to add the ``MathFunctions`` subdirectory +as an include directory so that the ``MathFunctions.h`` header file can be +found. + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> .. code-block:: cmake - :caption: CMakeLists.txt - :name: CMakeLists.txt-add_subdirectory + :caption: TODO 4: CMakeLists.txt + :name: CMakeLists.txt-target_include_directories-step2 + + target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + "${PROJECT_SOURCE_DIR}/MathFunctions" + ) + +.. raw:: html + + </details> + +Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``: + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> - # add the MathFunctions library - add_subdirectory(MathFunctions) +.. code-block:: c++ + :caption: TODO 5 : tutorial.cxx + :name: tutorial.cxx-include_MathFunctions.h - # add the executable - add_executable(Tutorial tutorial.cxx) + #include "MathFunctions.h" - target_link_libraries(Tutorial PUBLIC MathFunctions) +.. raw:: html - # add the binary tree to the search path for include files - # so that we will find TutorialConfig.h - target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - "${PROJECT_SOURCE_DIR}/MathFunctions" - ) + </details> -Now let us make the ``MathFunctions`` library optional. While for the tutorial +Lastly, replace ``sqrt`` with our library function ``mysqrt``. + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. code-block:: c++ + :caption: TODO 6 : tutorial.cxx + :name: tutorial.cxx-call_mysqrt + + const double outputValue = mysqrt(inputValue); + +.. raw:: html + + </details> + +Exercise 2 - Making Our Library Optional +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Now let us make the MathFunctions library optional. While for the tutorial there really isn't any need to do so, for larger projects this is a common -occurrence. The first step is to add an option to the top-level -``CMakeLists.txt`` file. +occurrence. + +CMake can do this using the :command:`option` command. This gives users a +variable which they can change when configuring their cmake build. This +setting will be stored in the cache so that the user does not need to set +the value each time they run CMake on a build directory. + +Goal +---- + +Add the option to build without ``MathFunctions``. + + +Helpful Resources +----------------- + +* :command:`if` +* :command:`list` +* :command:`option` +* :command:`cmakedefine <configure_file>` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``tutorial.cxx`` +* ``TutorialConfig.h.in`` + +Getting Started +--------------- + +Start with the resulting files from Exercise 1. Complete ``TODO 7`` through +``TODO 13``. + +First create a variable ``MY_MATH`` using the :command:`option` command +in the top-level ``CMakeLists.txt`` file. In that same file, use that option +to determine whether to build and use the ``MathFunctions`` library. + +Then, update ``tutorial.cxx`` and ``TutorialConfig.h.in`` to use ``MY_MATH``. + +Build and Run +------------- + +Since we have our build directory already configured from Exercise 1, we can +rebuild by simply calling the following: + +.. code-block:: console + + cd ../Step2_build + cmake --build . + +Next, run the ``Tutorial`` executable on a few numbers to verify that it's +still correct. + +Now let's update the value of ``USE_MYMATH`` to ``OFF``. The easiest way is to +use the :manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>` +if you're in the terminal. Or, alternatively, if you want to change the +option from the command-line, try: + +.. code-block:: console + + cmake ../Step2 -DUSE_MYMATH=OFF + +Now, rebuild the code with the following: + +.. code-block:: console + + cmake --build . + +Then, run the executable again to ensure that it still works with +``USE_MYMATH`` set to ``OFF``. Which function gives better results, ``sqrt`` +or ``mysqrt``? + +Solution +-------- + +The first step is to add an option to the top-level ``CMakeLists.txt`` file. +This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and +:manual:`ccmake <ccmake(1)>` with a default value of ``ON`` that can be +changed by the user. + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> .. literalinclude:: Step3/CMakeLists.txt - :caption: CMakeLists.txt + :caption: TODO 7: CMakeLists.txt :name: CMakeLists.txt-option :language: cmake :start-after: # should we use our own math functions - :end-before: # add the MathFunctions library + :end-before: # configure a header file to pass some of the CMake settings -This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and -:manual:`ccmake <ccmake(1)>` -with a default value of ``ON`` that can be changed by the user. This setting -will be stored in the cache so that the user does not need to set the value -each time they run CMake on a build directory. - -The next change is to make building and linking the ``MathFunctions`` library -conditional. To do this, we will create an ``if`` statement which checks the -value of the option. Inside the ``if`` block, put the -:command:`add_subdirectory` command from above with some additional list -commands to store information needed to link to the library and add the -subdirectory as an include directory in the ``Tutorial`` target. -The end of the top-level ``CMakeLists.txt`` file will now look like the -following: +.. raw:: html + + </details> + +Next, make building and linking the ``MathFunctions`` library +conditional. + +Start by creating a :command:`list` of the optional library targets for our +project. At the moment, it is just ``MathFunctions``. Let's name our list +``EXTRA_LIBS``. + +Similarly, we need to make a :command:`list` for the optional includes which +we will call ``EXTRA_INCLUDES``. In this list, we will ``APPEND`` the path of +the header file needed for our library. + +Next, create an :command:`if` statement which checks the value of +``USE_MYMATH``. Inside the :command:`if` block, put the +:command:`add_subdirectory` command from Exercise 1 with the additional +:command:`list` commands. + +When ``MY_MATH`` is ``ON``, the lists will be generated and will be added to +our project. When ``MY_MATH`` is ``OFF``, the lists stay empty. With this +strategy, we allow users to toggle ``MY_MATH`` to manipulate what library is +used in the build. + +The top-level CMakeLists.txt file will now look like the following: + +.. raw:: html + + <details><summary>TODO 8: Click to show/hide answer</summary> .. literalinclude:: Step3/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS + :caption: TODO 8: CMakeLists.txt + :name: CMakeLists.txt-USE_MYMATH :language: cmake :start-after: # add the MathFunctions library + :end-before: # add the executable + +.. raw:: html + + </details> -Note the use of the variable ``EXTRA_LIBS`` to collect up any optional -libraries to later be linked into the executable. The variable -``EXTRA_INCLUDES`` is used similarly for optional header files. This is a -classic approach when dealing with many optional components, we will cover -the modern approach in the next step. +Now that we have these two lists, we need to update +:command:`target_link_libraries` and :command:`target_include_directories` to +use them. Changing them is fairly straightforward. + +For :command:`target_link_libraries`, we replace the written out +library names with ``EXTRA_LIBS``. This looks like the following: + +.. raw:: html + + <details><summary>TODO 9: Click to show/hide answer</summary> + +.. literalinclude:: Step3/CMakeLists.txt + :caption: TODO 9: CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS + :language: cmake + :start-after: add_executable(Tutorial tutorial.cxx) + :end-before: # TODO 3 + +.. raw:: html + + </details> + +Then, we do the same thing with :command:`target_include_directories` and +``EXTRA_INCLUDES``. + +.. raw:: html + + <details><summary>TODO 10: Click to show/hide answer</summary> + +.. literalinclude:: Step3/CMakeLists.txt + :caption: TODO 10 : CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries-EXTRA_INCLUDES + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +.. raw:: html + + </details> + +Note that this is a classic approach when dealing with many components. We +will cover the modern approach in the Step 3 of the tutorial. The corresponding changes to the source code are fairly straightforward. -First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we -need it: +First, in ``tutorial.cxx``, we include the ``MathFunctions.h`` header if +``MY_MATH`` is defined. + +.. raw:: html + + <details><summary>TODO 11: Click to show/hide answer</summary> .. literalinclude:: Step3/tutorial.cxx - :caption: tutorial.cxx + :caption: TODO 11 : tutorial.cxx :name: tutorial.cxx-ifdef-include :language: c++ :start-after: // should we include the MathFunctions header :end-before: int main -Then, in the same file, make ``USE_MYMATH`` control which square root +.. raw:: html + + </details> + +Then, in the same file, we make ``USE_MYMATH`` control which square root function is used: +.. raw:: html + + <details><summary>TODO 12: Click to show/hide answer</summary> + .. literalinclude:: Step3/tutorial.cxx - :caption: tutorial.cxx + :caption: TODO 12 : tutorial.cxx :name: tutorial.cxx-ifdef-const :language: c++ :start-after: // which square root function should we use? :end-before: std::cout << "The square root of +.. raw:: html + + </details> + Since the source code now requires ``USE_MYMATH`` we can add it to ``TutorialConfig.h.in`` with the following line: +.. raw:: html + + <details><summary>TODO 13: Click to show/hide answer</summary> + .. literalinclude:: Step3/TutorialConfig.h.in - :caption: TutorialConfig.h.in + :caption: TODO 13 : TutorialConfig.h.in :name: TutorialConfig.h.in-cmakedefine :language: c++ :lines: 4 -**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` +.. raw:: html + + </details> + +With these changes, our library is now completely optional to whoever is +building and using it. + +Bonus Question +-------------- + +Why is it important that we configure ``TutorialConfig.h.in`` after the option for ``USE_MYMATH``? What would happen if we inverted the two? -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. Then run the built Tutorial executable. +Answer +------ -Now let's update the value of ``USE_MYMATH``. The easiest way is to use the -:manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>` if you're -in the terminal. Or, alternatively, if you want to change the option from the -command-line, try: +.. raw:: html -.. code-block:: console + <details><summary>Click to show/hide answer</summary> - cmake ../Step2 -DUSE_MYMATH=OFF +We configure after because ``TutorialConfig.h.in`` uses the value of +``USE_MYMATH``. If we configure the file before +calling :command:`option`, we won't be using the expected value of +``USE_MYMATH``. -Rebuild and run the tutorial again. +.. raw:: html -Which function gives better results, ``sqrt`` or ``mysqrt``? + </details> diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt index 7aa59e9..2f7d56e 100644 --- a/Help/guide/tutorial/Step2/CMakeLists.txt +++ b/Help/guide/tutorial/Step2/CMakeLists.txt @@ -7,13 +7,36 @@ project(Tutorial VERSION 1.0) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) +# TODO 7: Create a variable MY_MATH using option and set default to ON + # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) +# TODO 8: Use list() and APPEND to create a list of optional libraries +# called EXTRA_LIBS and a list of optional include directories called +# EXTRA_INCLUDES. Add the MathFunctions library and source directory to +# the appropriate lists. +# +# Only call add_subdirectory and only add MathFunctions specific values +# to EXTRA_LIBS and EXTRA_INCLUDES if USE_MYMATH is true. + +# TODO 2: Use add_subdirectory() to add MathFunctions to this project + # add the executable add_executable(Tutorial tutorial.cxx) +# TODO 9: Use EXTRA_LIBS instead of the MathFunctions specific values +# in target_link_libraries. + +# TODO 3: Use target_link_libraries to link the library to our executable + +# TODO 4: Add MathFunctions to Tutorial's target_include_directories() +# Hint: ${PROJECT_SOURCE_DIR} is a path to the project source. AKA This folder! + +# TODO 10: Use EXTRA_INCLUDES instead of the MathFunctions specific values +# in target_include_directories. + # add the binary tree to the search path for include files # so that we will find TutorialConfig.h target_include_directories(Tutorial PUBLIC diff --git a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..b7779b7 --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt @@ -0,0 +1,2 @@ +# TODO 1: Add a library called MathFunctions +# Hint: You will need the add_library command diff --git a/Help/guide/tutorial/Step2/TutorialConfig.h.in b/Help/guide/tutorial/Step2/TutorialConfig.h.in index 7e4d7fa..adb4c55 100644 --- a/Help/guide/tutorial/Step2/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step2/TutorialConfig.h.in @@ -1,3 +1,5 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ + +// TODO 13: use cmakedefine to define MY_MATH diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx index 53b0810..f83aa7e 100644 --- a/Help/guide/tutorial/Step2/tutorial.cxx +++ b/Help/guide/tutorial/Step2/tutorial.cxx @@ -5,6 +5,10 @@ #include "TutorialConfig.h" +// TODO 11: Only include MathFunctions if MY_MATH is defined + +// TODO 5: Include MathFunctions.h + int main(int argc, char* argv[]) { if (argc < 2) { @@ -18,6 +22,10 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); + // TODO 12: Use mysqrt if MY_MATH is defined and sqrt otherwise + + // TODO 6: Replace sqrt with mysqrt + // calculate square root const double outputValue = sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt index 1c12816..007770a 100644 --- a/Help/guide/tutorial/Step3/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -14,6 +14,8 @@ option(USE_MYMATH "Use tutorial provided math implementation" ON) # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) +# TODO 2: Remove EXTRA_INCLUDES list + # add the MathFunctions library if(USE_MYMATH) add_subdirectory(MathFunctions) @@ -26,6 +28,8 @@ add_executable(Tutorial tutorial.cxx) target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) +# TODO 3: Remove use of EXTRA_INCLUDES + # add the binary tree to the search path for include files # so that we will find TutorialConfig.h target_include_directories(Tutorial PUBLIC diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt index 8b443a6..7bf05e0 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt @@ -1 +1,5 @@ add_library(MathFunctions mysqrt.cxx) + +# TODO 1: State that anybody linking to MathFunctions needs to include the +# current source directory, while MathFunctions itself doesn't. +# Hint: Use target_include_directories with the INTERFACE keyword diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 4220dc0..94adac8 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -45,6 +45,25 @@ This option may also be given as a single argument: ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. + It's important to note that the order of ``-C`` and ``-D`` arguments is + significant. They will be carried out in the order they are listed, with the + last argument taking precedence over the previous ones. For example, if you + specify ``-DCMAKE_BUILD_TYPE=Debug``, followed by a ``-C`` argument with a + file that calls: + + .. code-block:: cmake + + set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE) + + then the ``-C`` argument will take precedence, and ``CMAKE_BUILD_TYPE`` will + be set to ``Release``. However, if the ``-D`` argument comes after the ``-C`` + argument, it will be set to ``Debug``. + + If a ``set(... CACHE ...)`` call in the ``-C`` file does not use ``FORCE``, + and a ``-D`` argument sets the same variable, the ``-D`` argument will take + precedence regardless of order because of the nature of non-``FORCE`` + ``set(... CACHE ...)`` calls. + .. option:: -U <globbing_expr> Remove matching entries from CMake ``CACHE``. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 036fa8f..0f35632 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -15,6 +15,7 @@ These commands are always available. .. toctree:: :maxdepth: 1 + /command/block /command/break /command/cmake_host_system_information /command/cmake_language @@ -26,6 +27,7 @@ These commands are always available. /command/continue /command/else /command/elseif + /command/endblock /command/endforeach /command/endfunction /command/endif diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7a6188a..a8faa2a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -594,6 +594,10 @@ Configuration Expressions expression when it is evaluated on a property of an :prop_tgt:`IMPORTED` target. + .. versionchanged:: 3.19 + Multiple configurations can be specified for ``cfgs``. + CMake 3.18 and earlier only accepted a single configuration. + .. genex:: $<OUTPUT_CONFIG:...> .. versionadded:: 3.20 diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 02cfa7e..16917ff 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -391,8 +391,8 @@ Variable References A *variable reference* has the form ``${<variable>}`` and is evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_. -A variable reference is replaced by the value of the variable, -or by the empty string if the variable is not set. +A variable reference is replaced by the value of the specified +variable or cache entry, or if neither is set, by the empty string. Variable references can nest and are evaluated from the inside out, e.g. ``${outer_${inner_variable}_variable}``. @@ -408,14 +408,16 @@ and how their values are set. An *environment variable reference* has the form ``$ENV{<variable>}``. See the `Environment Variables`_ section for more information. -A *cache variable reference* has the form ``$CACHE{<variable>}``. +A *cache variable reference* has the form ``$CACHE{<variable>}``, +and is replaced by the value of the specified cache entry without +checking for a normal variable of the same name. If the cache +entry does not exist, it is replaced by the empty string. See :variable:`CACHE` for more information. The :command:`if` command has a special condition syntax that allows for variable references in the short form ``<variable>`` -instead of ``${<variable>}``. -However, environment and cache variables always need to be -referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``. +instead of ``${<variable>}``. However, environment variables +always need to be referenced as ``$ENV{<variable>}``. Comments -------- diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 9dd623a..d161a28 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -193,6 +193,7 @@ They are normally called through the :command:`find_package` command. /module/FindOpenGL /module/FindOpenMP /module/FindOpenSceneGraph + /module/FindOpenSP /module/FindOpenSSL /module/FindOpenThreads /module/Findosg diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 43eb200..f6ab0c7 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -63,7 +63,7 @@ Policies Introduced by CMake 3.24 CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137> CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136> CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135> - CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134> + CMP0134: Fallback to "HOST" Windows registry view when "TARGET" view is not usable. </policy/CMP0134> CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133> CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132> CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131> diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 9fb46be..d98f7cc 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -474,6 +474,9 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_ENABLE_GPU_API_VALIDATION + /prop_tgt/XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION + /prop_tgt/XCODE_SCHEME_LAUNCH_CONFIGURATION /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS /prop_tgt/XCODE_XCCONFIG diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9fc8a79..ad6bfbc 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -287,6 +287,9 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION + /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION + /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS /variable/CMAKE_XCODE_XCCONFIG @@ -301,6 +304,7 @@ Variables that Describe the System /variable/ANDROID /variable/APPLE /variable/BORLAND + /variable/BSD /variable/CMAKE_ANDROID_NDK_VERSION /variable/CMAKE_CL_64 /variable/CMAKE_COMPILER_2005 @@ -320,6 +324,8 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN + /variable/DRAGONFLYBSD + /variable/FREEBSD /variable/GHSMULTI /variable/IOS /variable/LINUX @@ -338,6 +344,8 @@ Variables that Describe the System /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION /variable/MSYS + /variable/NETBSD + /variable/OPENBSD /variable/UNIX /variable/WIN32 /variable/WINCE diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index dcea7f9..2c86299 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -537,7 +537,7 @@ following options: Lists the available build presets. The current working directory must contain CMake preset files. -.. option:: --parallel [<jobs>], -j [<jobs>] +.. option:: -j [<jobs>], --parallel [<jobs>] The maximum number of concurrent processes to use when building. If ``<jobs>`` is omitted the native build tool's default number is used. diff --git a/Help/module/FindOpenSP.rst b/Help/module/FindOpenSP.rst new file mode 100644 index 0000000..1a3da01 --- /dev/null +++ b/Help/module/FindOpenSP.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenSP.cmake diff --git a/Help/policy/CMP0134.rst b/Help/policy/CMP0134.rst index 2b562bc..a94012c 100644 --- a/Help/policy/CMP0134.rst +++ b/Help/policy/CMP0134.rst @@ -31,9 +31,6 @@ The ``NEW`` behavior for this policy is to use registry views ``TARGET`` and This policy was introduced in CMake version 3.24. Use the :command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly. Unlike many policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses ``OLD`` behavior. -See documentation of the -:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>` -variable to control the warning. +when this policy is not set and simply uses ``OLD`` behavior. .. include:: DEPRECATED.txt diff --git a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst index d93a9c1..a31ee3a 100644 --- a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -36,4 +36,9 @@ The features known to this version of CMake are: Compiler mode is at least CUDA/C++ 23. +``cuda_std_26`` + .. versionadded:: 3.25 + + Compiler mode is at least CUDA/C++ 26. + .. include:: CMAKE_LANG_STD_FLAGS.txt diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 6846850..3832f1a 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -46,6 +46,11 @@ but it does not necessarily imply complete conformance to that standard. Compiler mode is at least C++ 23. +``cxx_std_26`` + .. versionadded:: 3.25 + + Compiler mode is at least C++ 26. + .. include:: CMAKE_LANG_STD_FLAGS.txt Low level individual compile features diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst index 950ba12..ada69b9 100644 --- a/Help/prop_tgt/CUDA_STANDARD.rst +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -39,6 +39,12 @@ Supported values are: CUDA C++23 +``26`` + .. versionadded:: 3.25 + + CUDA C++26. CMake 3.25 and later *recognize* ``26`` as a valid value, + no version has support for any compiler. + If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This means that using: diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index b10d201..9b381e4 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -37,6 +37,12 @@ Supported values are: C++23 +``26`` + .. versionadded:: 3.25 + + C++26. CMake 3.25 and later *recognize* ``26`` as a valid value, + no version has support for any compiler. + If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This means that using: diff --git a/Help/prop_tgt/HIP_STANDARD.rst b/Help/prop_tgt/HIP_STANDARD.rst index 0c767c6..9de8730 100644 --- a/Help/prop_tgt/HIP_STANDARD.rst +++ b/Help/prop_tgt/HIP_STANDARD.rst @@ -25,6 +25,12 @@ Supported values are: ``23`` HIP C++23 +``26`` + .. versionadded:: 3.25 + + HIP C++26. CMake 3.25 and later *recognize* ``26`` as a valid value, + no version has support for any compiler. + If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This means that using: diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index cba8ac9..2e039bd 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -14,3 +14,8 @@ its arguments to the tool. Some example tools are distcc and ccache. This property is initialized by the value of the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable if it is set when a target is created. + +.. versionadded:: 3.25 + + The property value may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst index 654e687..6ac8216 100644 --- a/Help/prop_tgt/OBJCXX_STANDARD.rst +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -31,6 +31,12 @@ Supported values are: Objective C++23 +``26`` + .. versionadded:: 3.25 + + Objective C++26. CMake 3.25 and later *recognize* ``26`` as a valid value, + no version has support for any compiler. + If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This means that using: diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst index eceddc1..fa3c5bc 100644 --- a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -30,6 +30,9 @@ at target creation time. - :prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` - :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` - :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +- :prop_tgt:`XCODE_SCHEME_LAUNCH_CONFIGURATION` +- :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` +- :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` - :prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` The following target properties will be applied on the diff --git a/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst new file mode 100644 index 0000000..3b801c5 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_ENABLE_GPU_API_VALIDATION +-------------------------------------- + +.. versionadded:: 3.25 + +Property value for ``Metal: API Validation`` in the Options section of +the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst new file mode 100644 index 0000000..5358087 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst @@ -0,0 +1,14 @@ +XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION +----------------------------------------- + +.. versionadded:: 3.25 + +Property value for ``Metal: Shader Validation`` in the Options section of +the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_LAUNCH_CONFIGURATION.rst b/Help/prop_tgt/XCODE_SCHEME_LAUNCH_CONFIGURATION.rst new file mode 100644 index 0000000..9643322 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_LAUNCH_CONFIGURATION.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_LAUNCH_CONFIGURATION +--------------------------------- + +.. versionadded:: 3.25 + +Set the build configuration to run the target. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/release/dev/FindOpenSP-module.rst b/Help/release/dev/FindOpenSP-module.rst new file mode 100644 index 0000000..9df6815 --- /dev/null +++ b/Help/release/dev/FindOpenSP-module.rst @@ -0,0 +1,4 @@ +FindOpenSP-module +----------------- + +* The :module:`FindOpenSP` module was added to find the OpenSP library. diff --git a/Help/release/dev/block-command.rst b/Help/release/dev/block-command.rst new file mode 100644 index 0000000..a740c0b --- /dev/null +++ b/Help/release/dev/block-command.rst @@ -0,0 +1,5 @@ +block-command +------------- + +* CMake language gains the commands :command:`block` and :command:`endblock` to + manage specific scopes (policy or variable) for group of commands. diff --git a/Help/release/dev/bsd-variables.rst b/Help/release/dev/bsd-variables.rst new file mode 100644 index 0000000..9d59edc --- /dev/null +++ b/Help/release/dev/bsd-variables.rst @@ -0,0 +1,9 @@ +bsd-variables +------------- + +* The :variable:`BSD` variable is set to true when the target system + is BSD (DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD) +* The :variable:`DRAGONFLYBSD` variable is set to true when the target system is DragonFlyBSD. +* The :variable:`FREEBSD` variable is set to true when the target system is FreeBSD. +* The :variable:`NETBSD` variable is set to true when the target system is NetBSD. +* The :variable:`OPENBSD` variable is set to true when the target system is OpenBSD. diff --git a/Help/release/dev/compiler-launcher-genexp.rst b/Help/release/dev/compiler-launcher-genexp.rst new file mode 100644 index 0000000..0e79992 --- /dev/null +++ b/Help/release/dev/compiler-launcher-genexp.rst @@ -0,0 +1,5 @@ +compiler-launcher-genexp +------------------------ + +* The :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/cxx_std_26.rst b/Help/release/dev/cxx_std_26.rst new file mode 100644 index 0000000..831f567 --- /dev/null +++ b/Help/release/dev/cxx_std_26.rst @@ -0,0 +1,8 @@ +cxx_std_26 +---------- + +* C++26 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`, + :prop_tgt:`CUDA_STANDARD`, :prop_tgt:`HIP_STANDARD`, or + :prop_tgt:`OBJCXX_STANDARD` target properties, + or via the :manual:`Compile Features <cmake-compile-features(7)>` + functionality's ``cxx_std_26`` meta-feature. diff --git a/Help/release/dev/xcode-gpu-validation.rst b/Help/release/dev/xcode-gpu-validation.rst new file mode 100644 index 0000000..86f7e96 --- /dev/null +++ b/Help/release/dev/xcode-gpu-validation.rst @@ -0,0 +1,12 @@ +xcode-gpu-validation +-------------------- + +* The :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` variable and + corresponding :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` target + property were added to tell the :generator:`Xcode` generator what to put + in the scheme's ``Metal: API Validation`` setting. + +* The :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` variable and + corresponding :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` target + property were added to tell the :generator:`Xcode` generator what to put + in the scheme's ``Metal: Shader Validation`` setting. diff --git a/Help/release/dev/xcode-launch-mode.rst b/Help/release/dev/xcode-launch-mode.rst index 32b9ee6..701b502 100644 --- a/Help/release/dev/xcode-launch-mode.rst +++ b/Help/release/dev/xcode-launch-mode.rst @@ -5,3 +5,8 @@ xcode-launch-mode :prop_tgt:`XCODE_SCHEME_LAUNCH_MODE` target property were added to tell the :generator:`Xcode` generator what to put in the scheme's "Launch" mode setting. + +* The :variable:`CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION` variable and + corresponding :prop_tgt:`XCODE_SCHEME_LAUNCH_CONFIGURATION` target + property were added to tell the :generator:`Xcode` generator what + configuration to put in the scheme's Launch action. diff --git a/Help/variable/BSD.rst b/Help/variable/BSD.rst new file mode 100644 index 0000000..0b3e5dc --- /dev/null +++ b/Help/variable/BSD.rst @@ -0,0 +1,6 @@ +BSD +--- + +.. versionadded:: 3.25 + +Set to true when the target system is BSD (DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD) diff --git a/Help/variable/CMAKE_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst index 94f1891..f851a18 100644 --- a/Help/variable/CMAKE_CPACK_COMMAND.rst +++ b/Help/variable/CMAKE_CPACK_COMMAND.rst @@ -5,6 +5,6 @@ CMAKE_CPACK_COMMAND Full path to :manual:`cpack(1)` command installed with CMake. -This is the full path to the CPack executable :manual:`cpack(1)` which is -useful from custom commands that want to use the :option:`cmake -E <cmake_E -E>` -option for portable system commands. +This is the full path to the CPack executable :manual:`cpack(1)` +that can be used for custom commands or tests to invoke +CPack commands. diff --git a/Help/variable/CMAKE_CTEST_COMMAND.rst b/Help/variable/CMAKE_CTEST_COMMAND.rst index 7287998..a3b751f 100644 --- a/Help/variable/CMAKE_CTEST_COMMAND.rst +++ b/Help/variable/CMAKE_CTEST_COMMAND.rst @@ -3,6 +3,6 @@ CMAKE_CTEST_COMMAND Full path to :manual:`ctest(1)` command installed with CMake. -This is the full path to the CTest executable :manual:`ctest(1)` which is -useful from custom commands that want to use the :option:`cmake -E <cmake_E -E>` -option for portable system commands. +This is the full path to the CTest executable :manual:`ctest(1)` +that can be used for custom commands or tests to invoke +CTest commands. diff --git a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst index 53a19dc..a7e9029 100644 --- a/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst +++ b/Help/variable/CMAKE_EXPORT_COMPILE_COMMANDS.rst @@ -33,7 +33,7 @@ property for all targets. .. note:: This option is implemented only by :ref:`Makefile Generators` - and the :generator:`Ninja`. It is ignored on other generators. + and :ref:`Ninja Generators`. It is ignored on other generators. This option currently does not work well in combination with the :prop_tgt:`UNITY_BUILD` target property or the diff --git a/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst index 8494e95..d577a8a 100644 --- a/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst @@ -4,7 +4,8 @@ CMAKE_FIND_USE_INSTALL_PREFIX .. versionadded:: 3.24 Controls the default behavior of the following commands for whether or not to -search the install location: +search the locations in the :variable:`CMAKE_INSTALL_PREFIX` and +:variable:`CMAKE_STAGING_PREFIX` variables. * :command:`find_program` * :command:`find_library` diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst new file mode 100644 index 0000000..ce5c4b3 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION +-------------------------------------------- + +.. versionadded:: 3.25 + +Property value for ``Metal: API Validation`` in the Options section of +the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst new file mode 100644 index 0000000..073a6c9 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION +----------------------------------------------- + +.. versionadded:: 3.25 + +Property value for ``Metal: Shader Validation`` in the Options section of +the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION.rst b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION.rst new file mode 100644 index 0000000..e5b4d18 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION +--------------------------------------- + +.. versionadded:: 3.25 + +Set the build configuration to run the target. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_LAUNCH_CONFIGURATION` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/DRAGONFLYBSD.rst b/Help/variable/DRAGONFLYBSD.rst new file mode 100644 index 0000000..f006156 --- /dev/null +++ b/Help/variable/DRAGONFLYBSD.rst @@ -0,0 +1,6 @@ +DRAGONFLYBSD +------------ + +.. versionadded:: 3.25 + +Set to true when the target system is DragonFlyBSD. diff --git a/Help/variable/FREEBSD.rst b/Help/variable/FREEBSD.rst new file mode 100644 index 0000000..9990948 --- /dev/null +++ b/Help/variable/FREEBSD.rst @@ -0,0 +1,6 @@ +FREEBSD +------- + +.. versionadded:: 3.25 + +Set to true when the target system is FreeBSD. diff --git a/Help/variable/NETBSD.rst b/Help/variable/NETBSD.rst new file mode 100644 index 0000000..e7965f8 --- /dev/null +++ b/Help/variable/NETBSD.rst @@ -0,0 +1,6 @@ +NETBSD +------ + +.. versionadded:: 3.25 + +Set to true when the target system is NetBSD. diff --git a/Help/variable/OPENBSD.rst b/Help/variable/OPENBSD.rst new file mode 100644 index 0000000..dd9b23d --- /dev/null +++ b/Help/variable/OPENBSD.rst @@ -0,0 +1,6 @@ +OPENBSD +------- + +.. versionadded:: 3.25 + +Set to true when the target system is OpenBSD. |