diff options
Diffstat (limited to 'Help')
49 files changed, 1204 insertions, 209 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/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/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index a77b615..9df3cc4 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -57,6 +57,12 @@ Variables specific to CPack Archive generator .. versionadded:: 3.9 Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables. +.. variable:: CPACK_ARCHIVE_FILE_EXTENSION + + .. versionadded:: 3.25 + + Package file extension. Default values are given in the list above. + .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL Enable component packaging. If enabled (ON), then the archive generator 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/Packaging Debug and Release.rst b/Help/guide/tutorial/Packaging Debug and Release.rst index 91b46a7..fc2050e 100644 --- a/Help/guide/tutorial/Packaging Debug and Release.rst +++ b/Help/guide/tutorial/Packaging Debug and Release.rst @@ -10,8 +10,8 @@ possible, however, to setup CPack to bundle multiple build directories and construct a package that contains multiple configurations of the same project. First, we want to ensure that the debug and release builds use different names -for the executables and libraries that will be installed. Let's use `d` as the -postfix for the debug executable and libraries. +for the libraries that will be installed. Let's use `d` as the +postfix for the debug libraries. Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level ``CMakeLists.txt`` file: @@ -44,7 +44,7 @@ Let's also add version numbering to the ``MathFunctions`` library. In :end-before: # install rules From the ``Step12`` directory, create ``debug`` and ``release`` -subbdirectories. The layout will look like: +subdirectories. The layout will look like: .. code-block:: none 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/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst index 1c60d2d..9cc5816 100644 --- a/Help/guide/user-interaction/index.rst +++ b/Help/guide/user-interaction/index.rst @@ -675,7 +675,7 @@ and use it as the :variable:`CMAKE_MAKE_PROGRAM`. For completeness, ``nmake`` is an alternative tool which can process the output of the :generator:`NMake Makefiles JOM` generator, but doing -so would be a pessimisation. +so would be a pessimization. Software Installation ===================== diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 2c6cd96..0f3c30a 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -18,6 +18,85 @@ See https://cmake.org/get-involved/ to get involved in development of CMake upstream. It includes links to contribution instructions, which in turn link to developer guides for CMake itself. +Accessing Windows Registry +========================== + +CMake offers some facilities to access the registry on ``Windows`` platforms. + +Query Windows Registry +---------------------- + +.. versionadded:: 3.24 + +The :command:`cmake_host_system_information` command offers the possibility to +query the registry on the local computer. See +:ref:`cmake_host_system(QUERY_WINDOWS_REGISTRY) <Query Windows registry>` for +more information. + +.. _`Find Using Windows Registry`: + +Find Using Windows Registry +--------------------------- + +.. versionchanged:: 3.24 + +Options ``HINTS`` and ``PATHS`` of :command:`find_file`, +:command:`find_library`, :command:`find_path`, :command:`find_program`, and +:command:`find_package` commands offer the possibility, on ``Windows`` +platform, to query the registry. + +The formal syntax, as specified using +`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with +the regular extensions, for registry query is the following: + +.. raw:: latex + + \begin{small} + +.. productionlist:: + registry_query: '[' `sep_definition`? `root_key` + : ((`key_separator` `sub_key`)? (`value_separator` `value_name`_)?)? ']' + sep_definition: '{' `value_separator` '}' + root_key: 'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' | + : 'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' | + : 'HKU' | 'HKEY_USERS' + sub_key: `element` (`key_separator` `element`)* + key_separator: '/' | '\\' + value_separator: `element` | ';' + value_name: `element` | '(default)' + element: `character`\+ + character: <any character except `key_separator` and `value_separator`> + +.. raw:: latex + + \end{small} + +The :token:`sep_definition` optional item offers the possibility to specify +the string used to separate the :token:`sub_key` from the :token:`value_name` +item. If not specified, the character ``;`` is used. Multiple +:token:`registry_query` items can be specified as part of a path. + +.. code-block:: cmake + + # example using default separator + find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]") + + # example using different specified separators + find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]") + +If the :token:`value_name` item is not specified or has the special name +``(default)``, the content of the default value, if any, will be returned. The +supported types for the :token:`value_name` are: + +* ``REG_SZ``. +* ``REG_EXPAND_SZ``. The returned data is expanded. +* ``REG_DWORD``. +* ``REG_QWORD``. + +When the registry query failed, typically because the key does not exist or +the data type is not supported, the string ``/REGISTRY-NOTFOUND`` is substituted +to the ``[]`` query expression. + .. _`Find Modules`: Find Modules @@ -242,70 +321,6 @@ backwards compatibility for any old names that were actually in use. Make sure you comment them as deprecated, so that no-one starts using them. -.. _`Find Using Windows Registry`: - -Find Using Windows Registry ---------------------------- - -.. versionchanged:: 3.24 - -Options ``HINTS`` and ``PATHS`` of :command:`find_file`, -:command:`find_library`, :command:`find_path`, :command:`find_program`, and -:command:`find_package` commands offer the possibility, on ``Windows`` -platform, to query the registry. - -The formal syntax, as specified using -`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with -the regular extensions, for registry query is the following: - -.. raw:: latex - - \begin{small} - -.. productionlist:: - registry_query: '[' `sep_definition`? `root_key` - : ((`key_separator` `sub_key`)? (`value_separator` `value_name`_)?)? ']' - sep_definition: '{' `value_separator` '}' - root_key: 'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' | - : 'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' | - : 'HKU' | 'HKEY_USERS' - sub_key: `element` (`key_separator` `element`)* - key_separator: '/' | '\\' - value_separator: `element` | ';' - value_name: `element` | '(default)' - element: `character`\+ - character: <any character except `key_separator` and `value_separator`> - -.. raw:: latex - - \end{small} - -The :token:`sep_definition` optional item offers the possibility to specify -the string used to separate the :token:`sub_key` from the :token:`value_name` -item. If not specified, the character ``;`` is used. Multiple -:token:`registry_query` items can be specified as part of a path. - -.. code-block:: cmake - - # example using default separator - find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]") - - # example using different specified separators - find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]") - -If the :token:`value_name` item is not specified or has the special name -``(default)``, the content of the default value, if any, will be returned. The -supported types for the :token:`value_name` are: - -* ``REG_SZ``. -* ``REG_EXPAND_SZ``. The returned data is expanded. -* ``REG_DWORD``. -* ``REG_QWORD``. - -When the registry query failed, typically because the key does not exist or -the data type is not supported, the string ``/REGISTRY-NOTFOUND`` is substituted -to the ``[]`` query expression. - A Sample Find Module -------------------- 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-presets.7.rst b/Help/manual/cmake-presets.7.rst index 16cd54e..35dac76 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -58,6 +58,9 @@ The root object recognizes the following fields: ``5`` .. versionadded:: 3.24 + ``6`` + .. versionadded:: 3.25 + ``cmakeMinimumRequired`` An optional object representing the minimum version of CMake needed to build this project. This object consists of the following fields: @@ -128,7 +131,8 @@ that may contain the following fields: This identifier is used in the :ref:`cmake --preset <CMake Options>` option. There must not be two configure presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a configure preset may have the same name as a build or test preset. + However, a configure preset may have the same name as a build, test, or + package preset. ``hidden`` An optional boolean specifying whether or not a preset should be hidden. @@ -350,7 +354,8 @@ that may contain the following fields: :ref:`cmake --build --preset <Build Tool Mode>` option. There must not be two build presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a build preset may have the same name as a configure or test preset. + However, a build preset may have the same name as a configure, test, or + package preset. ``hidden`` An optional boolean specifying whether or not a preset should be hidden. @@ -510,7 +515,8 @@ that may contain the following fields: This identifier is used in the :option:`ctest --preset` option. There must not be two test presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a test preset may have the same name as a configure or build preset. + However, a test preset may have the same name as a configure, build, or + package preset. ``hidden`` An optional boolean specifying whether or not a preset should be hidden. @@ -833,6 +839,134 @@ that may contain the following fields: Equivalent to passing :option:`--no-tests=ignore <ctest --no-tests>` on the command line. +Package Preset +^^^^^^^^^^^^^^ + +Package presets may be used in schema version ``6`` or above. Each entry of +the ``packagePresets`` array is a JSON object that may contain the following +fields: + +``name`` + A required string representing the machine-friendly name of the preset. + This identifier is used in the :option:`cpack --preset` option. + There must not be two package presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a package preset may have the same name as a configure, build, or + test preset. + +``hidden`` + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the + :option:`--preset <cpack --preset>` argument + and does not have to have a valid ``configurePreset``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. + +``inherits`` + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the + ``inherits`` presets by default (except ``name``, ``hidden``, + ``inherits``, ``description``, and ``displayName``), but can override + them as desired. If multiple ``inherits`` presets provide conflicting + values for the same field, the earlier preset in the ``inherits`` list + will be preferred. + + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +``condition`` + An optional `Condition`_ object. + +``vendor`` + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. + +``displayName`` + An optional string with a human-friendly name of the preset. + +``description`` + An optional string with a human-friendly description of the preset. + +``environment`` + An optional map of environment variables. The key is the variable name + (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 + regardless of whether or not a value was given to it by the process's + environment. This field supports macro expansion, and 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 + ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` + and the ``environment`` from all its parents. If multiple presets in + this union define the same variable, the standard rules of ``inherits`` + are applied. Setting a variable to ``null`` causes it to not be set, + even if a value was inherited from another preset. + +``configurePreset`` + An optional string specifying the name of a configure preset to + associate with this package preset. If ``configurePreset`` is not + specified, it must be inherited from the inherits preset (unless this + preset is hidden). The build directory is inferred from the configure + preset, so packaging will run in the same ``binaryDir`` that the + configuration did and build did. + +``inheritConfigureEnvironment`` + An optional boolean that defaults to true. If true, the environment + variables from the associated configure preset are inherited after all + inherited package preset environments, but before environment variables + explicitly specified in this package preset. + +``generators`` + An optional list of strings representing generators for CPack to use. + +``configurations`` + An optional list of strings representing build configurations for CPack to + package. + +``variables`` + An optional map of variables to pass to CPack, equivalent to + :option:`-D <cpack -D>` arguments. Each key is the name of a variable, and + the value is the string to assign to that variable. + +``configFile`` + An optional string representing the config file for CPack to use. + +``output`` + An optional object specifying output options. Valid keys are: + + ``debug`` + An optional boolean specifying whether or not to print debug information. + A value of ``true`` is equivalent to passing + :option:`--debug <cpack --debug>` on the command line. + + ``verbose`` + An optional boolean specifying whether or not to print verbosely. A value + of ``true`` is equivalent to passing :option:`--verbose <cpack --verbose>` + on the command line. + +``packageName`` + An optional string representing the package name. + +``packageVersion`` + An optional string representing the package version. + +``packageDirectory`` + An optional string representing the directory in which to place the package. + +``vendorName`` + An optional string representing the vendor name. + Condition ^^^^^^^^^ 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 1380a179..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 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 8cec9d4..98655e5 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -500,9 +500,9 @@ Options .. option:: --list-presets[=<type>] Lists the available presets of the specified ``<type>``. Valid values for - ``<type>`` are ``configure``, ``build``, ``test``, or ``all``. If ``<type>`` - is omitted, ``configure`` is assumed. The current working directory must - contain CMake preset files. + ``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``. + If ``<type>`` is omitted, ``configure`` is assumed. The current working + directory must contain CMake preset files. .. _`Build Tool Mode`: @@ -773,6 +773,11 @@ Available commands are: ``true`` if cmake supports server-mode and ``false`` otherwise. Always false since CMake 3.20. + ``tls`` + .. versionadded:: 3.25 + + ``true`` if TLS support is enabled and ``false`` otherwise. + .. option:: cat [--] <files>... .. versionadded:: 3.18 diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index a95df8b..3f26d72 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -119,6 +119,14 @@ Options Override/define :variable:`CPACK_PACKAGE_VENDOR`. +.. option:: --preset <presetName> + + Use a preset from :manual:`cmake-presets(7)`. + +.. option:: --list-presets + + List presets from :manual:`cmake-presets(7)`. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index c96405c..f3a7532 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -72,6 +72,22 @@ "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 6, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV5"}, + "packagePresets": { "$ref": "#/definitions/packagePresetsV6"}, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false } ], "required": [ @@ -476,12 +492,12 @@ "properties": { "name": { "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, or package) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument, will not show up in the CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ @@ -728,12 +744,12 @@ "properties": { "name": { "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, or package) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument, will not show up in the CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ @@ -1129,6 +1145,182 @@ "additionalProperties": false } }, + "packagePresetsItemsV6": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, or package) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "minLength": 1 + }, + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the name of the package preset to inherit from.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the names of package presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } + } + ] + }, + "configurePreset": { + "type": "string", + "description": "An optional string specifying the name of a configure preset to associate with this package preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "vendor": { + "type": "object", + "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", + "properties": {} + }, + "displayName": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "description": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited package preset environments, but before environment variables explicitly specified in this package preset." + }, + "environment": { + "type": "object", + "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and 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 ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "string", + "description": "A string representing the value of the variable." + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "condition": { "$ref": "#/definitions/topCondition" }, + "generators": { + "type": "array", + "description": "An optional list of strings representing generators for CPack to use.", + "items": { + "type": "string", + "description": "An optional string representing the name of the CPack generator to use." + } + }, + "configurations": { + "type": "array", + "description": "An optional list of strings representing build configurations for CPack to package.", + "items": { + "type": "string", + "description": "An optional string representing the name of the configuration to use." + } + }, + "variables": { + "type": "object", + "description": "An optional map of variables to pass to CPack, equivalent to -D arguments. Each key is the name of a variable, and the value is the string to assign to that variable.", + "items": { + "type": "string", + "description": "An optional string representing the value of the variable." + } + }, + "configFile": { + "type": "string", + "description": "An optional string representing the config file for CPack to use." + }, + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "debug": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print debug information. A value of true is equivalent to passing --debug on the command line." + }, + "verbose": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print verbosely. A value of true is equivalent to passing --verbose on the command line." + } + }, + "additionalProperties": false + }, + "packageName": { + "type": "string", + "description": "An optional string representing the package name." + }, + "packageVersion": { + "type": "string", + "description": "An optional string representing the package version." + }, + "packageDirectory": { + "type": "string", + "description": "An optional string representing the directory in which to place the package." + }, + "vendorName": { + "type": "string", + "description": "An optional string representing the vendor name." + } + }, + "required": [ + "name" + ] + } + }, + "packagePresetsV6": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", + "allOf": [ + { "$ref": "#/definitions/packagePresetsItemsV6" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "condition": {}, + "generators": {}, + "configurations": {}, + "variables": {}, + "configFile": {}, + "output": {}, + "packageName": {}, + "packageVersion": {}, + "packageDirectory": {}, + "vendorName": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "condition": { "anyOf": [ { 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/E-capabilities-tls.rst b/Help/release/dev/E-capabilities-tls.rst new file mode 100644 index 0000000..e2324d2 --- /dev/null +++ b/Help/release/dev/E-capabilities-tls.rst @@ -0,0 +1,5 @@ +E-capabilities-tls +------------------ + +* The :manual:`cmake -E capabilities <cmake(1)>` command gained a new ``tls`` + field that tells whether or not TLS is enabled. 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/cmake-presets-package.rst b/Help/release/dev/cmake-presets-package.rst new file mode 100644 index 0000000..8f7ea6b --- /dev/null +++ b/Help/release/dev/cmake-presets-package.rst @@ -0,0 +1,5 @@ +cmake-presets-package +--------------------- + +* The :manual:`cmake-presets(7)` schema version has been bumped to ``6``. +* The :manual:`cmake-presets(7)` format now supports a ``packagePresets`` field. 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/cpack-archive-custom-extension.rst b/Help/release/dev/cpack-archive-custom-extension.rst new file mode 100644 index 0000000..38ad36f --- /dev/null +++ b/Help/release/dev/cpack-archive-custom-extension.rst @@ -0,0 +1,6 @@ +cpack-archive-custom-extension +------------------------------ + +* The :cpack_gen:`CPack Archive Generator` gained a new + :variable:`CPACK_ARCHIVE_FILE_EXTENSION` variable to control + the package file name extension. 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/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. |