diff options
Diffstat (limited to 'Help')
70 files changed, 737 insertions, 170 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 6683edb..aa06d49 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -15,6 +15,7 @@ The general signature is: [PATHS [path | ENV var]... ] [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [PATH_SUFFIXES suffix1 [suffix2 ...]] + [VALIDATOR function] [DOC "cache documentation string"] [NO_CACHE] [REQUIRED] @@ -66,6 +67,26 @@ Options include: Specify additional subdirectories to check below each directory location otherwise considered. +``VALIDATOR`` + .. versionadded:: 3.25 + + Specify a :command:`function` (a :command:`macro` is not an acceptable + choice) which will be called for each found item. The search ends when + the validation function returns a successful status. + + The validation function expects two arguments: output variable name and item + value. By default, the output variable name already holds a ``TRUE`` value. + + .. parsed-literal:: + + function (MY_CHECK output_status item) + if (NOT item MATCHES ...) + set(${output_status} FALSE PARENT_SCOPE) + endif() + endfunction() + + |FIND_XXX| (result NAMES ... VALIDATOR my_check) + ``DOC`` Specify the documentation string for the ``<VAR>`` cache entry. @@ -166,9 +187,9 @@ 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`` 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 + :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 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``. diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index cb8d60b..377e42d 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -14,6 +14,7 @@ Synopsis cmake_language(`EVAL`_ CODE <code>...) cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...]) cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...) + cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>) Introduction ^^^^^^^^^^^^ @@ -491,3 +492,28 @@ calling the provider command recursively for the same dependency. SET_DEPENDENCY_PROVIDER mycomp_provide_dependency SUPPORTED_METHODS FIND_PACKAGE ) + +Getting current message log level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.25 + +.. _GET_MESSAGE_LOG_LEVEL: +.. _query_message_log_level: + +.. code-block:: cmake + + cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>) + +Writes the current :command:`message` logging level +into the given ``<output_variable>``. + +See :command:`message` for the possible logging levels. + +The current message logging level can be set either using the ``--log-level`` +command line option of the :manual:`cmake(1)` program or using +the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. + +If both the command line option and the variable are set, the command line +option takes precedence. If neither are set, the default logging level +is returned. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index d2acbc8..d9103b8 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -1,13 +1,14 @@ enable_language --------------- -Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) + +Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc) .. code-block:: cmake - enable_language(<lang> [OPTIONAL] ) + enable_language(<lang>... [OPTIONAL]) -Enables support for the named language in CMake. This is -the same as the :command:`project` command but does not create any of the extra +Enables support for the named languages in CMake. This is the same as +the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. diff --git a/Help/command/export.rst b/Help/command/export.rst index dc69645..6785b05 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -25,7 +25,8 @@ Exporting Targets .. code-block:: cmake export(TARGETS <target>... [NAMESPACE <namespace>] - [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) + [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES] + [CXX_MODULES_DIRECTORY <directory>]) Creates a file ``<filename>`` that may be included by outside projects to import targets named by ``<target>...`` from the current project's build tree. @@ -52,6 +53,16 @@ The options are: in the export, even when policy :policy:`CMP0022` is NEW. This is useful to support consumers using CMake versions older than 2.8.12. +``CXX_MODULES_DIRECTORY <directory>`` + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Export C++ module properties to files under the given directory. Each file + will be named according to the target's export name (without any namespace). + These files will automatically be included from the export file. + This signature requires all targets to be listed explicitly. If a library target is included in the export, but a target to which it links is not included, the behavior is unspecified. See the `export(EXPORT)`_ signature @@ -95,7 +106,8 @@ Exporting Targets matching install(EXPORT) .. code-block:: cmake - export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>] + [CXX_MODULES_DIRECTORY <directory>]) Creates a file ``<filename>`` that may be included by outside projects to import targets from the current project's build tree. This is the same diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index d9f54ca..ddf8dfa 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -130,3 +130,11 @@ yields -- en=two, ba=dua -- en=three, ba=tiga -- en=four, ba= + +See Also +^^^^^^^^ + +* :command:`break` +* :command:`continue` +* :command:`endforeach` +* :command:`while` diff --git a/Help/command/function.rst b/Help/command/function.rst index 3d25aa4..fc55c03 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -73,3 +73,9 @@ argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined behavior. Checking that ``ARGC`` is greater than ``#`` is the only way to ensure that ``ARGV#`` was passed to the function as an extra argument. + +See Also +^^^^^^^^ + +* :command:`endfunction` +* :command:`return` diff --git a/Help/command/if.rst b/Help/command/if.rst index 301cdce..b72769f 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -424,3 +424,10 @@ There is no automatic evaluation for environment or cache :ref:`Variable References`. Their values must be referenced as ``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented condition syntax accepts ``<variable|string>``. + +See also +^^^^^^^^ + + * :command:`else` + * :command:`elseif` + * :command:`endif` diff --git a/Help/command/install.rst b/Help/command/install.rst index 973aa31..5aa3a4b 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -132,7 +132,7 @@ Installing Targets install(TARGETS targets... [EXPORT <export-name>] [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| - PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>] + PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI] [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] @@ -215,11 +215,21 @@ that may be installed: ``/blah/include/myproj/here.h`` with a base directory ``/blah/include`` would be installed to ``myproj/here.h`` below the destination. +``CXX_MODULES_BMI`` + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Any module files from C++ modules from ``PUBLIC`` sources in a file set of + type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All + modules are placed directly in the destination as no directory structure is + derived from the names of the modules. An empty ``DESTINATION`` may be used + to suppress installing these files (for use in generic code). + For each of these arguments given, the arguments following them only apply to the target or file type specified in the argument. If none is given, the -installation properties apply to all target types. If only one is given then -only targets of that type will be installed (which can be used to install -just a DLL or just an import library.) +installation properties apply to all target types. For regular executables, static libraries and shared libraries, the ``DESTINATION`` argument is not required. For these target types, when @@ -233,6 +243,14 @@ Apple bundles and frameworks. A destination can be omitted for interface and object libraries, but they are handled differently (see the discussion of this topic toward the end of this section). +For shared libraries on DLL platforms, if neither ``RUNTIME`` nor ``ARCHIVE`` +destinations are specified, both the ``RUNTIME`` and ``ARCHIVE`` components are +installed to their default destinations. If either a ``RUNTIME`` or ``ARCHIVE`` +destination is specified, the component is installed to that destination, and +the other component is not installed. If both ``RUNTIME`` and ``ARCHIVE`` +destinations are specified, then both components are installed to their +respective destinations. + The following table shows the target types with their associated variables and built-in defaults that apply when no destination is given: @@ -778,9 +796,10 @@ Installing Exports .. code-block:: cmake install(EXPORT <export-name> DESTINATION <dir> - [NAMESPACE <namespace>] [[FILE <name>.cmake]| + [NAMESPACE <namespace>] [FILE <name>.cmake] [PERMISSIONS permissions...] - [CONFIGURATIONS [Debug|Release|...]] + [CONFIGURATIONS [Debug|Release|...] + [CXX_MODULES_DIRECTORY <directory>] [EXPORT_LINK_INTERFACE_LIBRARIES] [COMPONENT <component>] [EXCLUDE_FROM_ALL]) @@ -836,6 +855,18 @@ library is always installed if the headers and CMake export file are present. to an ndk build system complete with transitive dependencies, include flags and defines required to use the libraries. +``CXX_MODULES_DIRECTORY`` + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Specify a subdirectory to store C++ module information for targets in the + export set. This directory will be populated with files which add the + necessary target property information to the relevant targets. Note that + without this information, none of the C++ modules which are part of the + targets in the export set will support being imported in consuming targets. + The ``EXPORT`` form is useful to help outside projects use targets built and installed by the current project. For example, the code diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 72119f6..a079307 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -75,9 +75,33 @@ File Sets Adds a file set to a target, or adds files to an existing file set. Targets have zero or more named file sets. Each file set has a name, a type, a scope of ``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and -files within those directories. The only acceptable type is ``HEADERS``. The -optional default file sets are named after their type. The target may not be a -custom target or :prop_tgt:`FRAMEWORK` target. +files within those directories. The acceptable types include: + +``HEADERS`` + + Sources intended to be used via a language's ``#include`` mechanism. + +``CXX_MODULES`` + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + Sources which contain C++ interface module or partition units (i.e., those + using the ``export`` keyword). This file set type may not have an + ``INTERFACE`` scope except on ``IMPORTED`` targets. + +``CXX_MODULE_HEADER_UNITS`` + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + + C++ header sources which may be imported by other C++ source code. This file + set type may not have an ``INTERFACE`` scope except on ``IMPORTED`` targets. + +The optional default file sets are named after their type. The target may not +be a custom target or :prop_tgt:`FRAMEWORK` target. Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets @@ -93,16 +117,17 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o The name of the file set to create or add to. It must contain only letters, numbers and underscores. Names starting with a capital letter are reserved - for built-in file sets predefined by CMake. The only predefined set name is - ``HEADERS``. All other set names must not start with a capital letter or + for built-in file sets predefined by CMake. The only predefined set names + are those matching the acceptable types. All other set names must not start + with a capital letter or underscore. ``TYPE <type>`` - Every file set is associated with a particular type of file. ``HEADERS`` - is currently the only defined type and it is an error to specify anything - else. As a special case, if the name of the file set is ``HEADERS``, the - type does not need to be specified and the ``TYPE <type>`` arguments can be + Every file set is associated with a particular type of file. Only types + specified above may be used and it is an error to specify anything else. As + a special case, if the name of the file set is one of the types, the type + does not need to be specified and the ``TYPE <type>`` arguments can be omitted. For all other file set names, ``TYPE`` is required. ``BASE_DIRS <dirs>...`` @@ -134,6 +159,8 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o The following target properties are set by ``target_sources(FILE_SET)``, but they should not generally be manipulated directly: +For file sets of type ``HEADERS``: + * :prop_tgt:`HEADER_SETS` * :prop_tgt:`INTERFACE_HEADER_SETS` * :prop_tgt:`HEADER_SET` @@ -141,17 +168,37 @@ but they should not generally be manipulated directly: * :prop_tgt:`HEADER_DIRS` * :prop_tgt:`HEADER_DIRS_<NAME>` +For file sets of type ``CXX_MODULES``: + +* :prop_tgt:`CXX_MODULE_SETS` +* :prop_tgt:`INTERFACE_CXX_MODULE_SETS` +* :prop_tgt:`CXX_MODULE_SET` +* :prop_tgt:`CXX_MODULE_SET_<NAME>` +* :prop_tgt:`CXX_MODULE_DIRS` +* :prop_tgt:`CXX_MODULE_DIRS_<NAME>` + +For file sets of type ``CXX_MODULE_HEADER_UNITS``: + +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SETS` +* :prop_tgt:`INTERFACE_CXX_MODULE_HEADER_UNIT_SETS` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET_<NAME>` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS` +* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS_<NAME>` + Target properties related to include directories are also modified by ``target_sources(FILE_SET)`` as follows: :prop_tgt:`INCLUDE_DIRECTORIES` - If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE`` - or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in - :genex:`$<BUILD_INTERFACE>` and appended to this property. + If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope + of the file set is ``PRIVATE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of + the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this + property. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` - If the ``TYPE`` is ``HEADERS``, and the scope of the file set is - ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are - wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property. + If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope + of the file set is ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of + the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this + property. diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index fc41cdd..125b0ac 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -19,6 +19,8 @@ Try Compiling and Running Source Files [LINK_LIBRARIES <libs>...] [COMPILE_OUTPUT_VARIABLE <var>] [RUN_OUTPUT_VARIABLE <var>] + [RUN_OUTPUT_STDOUT_VARIABLE <var>] + [RUN_OUTPUT_STDERR_VARIABLE <var>] [OUTPUT_VARIABLE <var>] [WORKING_DIRECTORY <var>] [ARGS <args>...]) @@ -70,6 +72,16 @@ The options are: ``RUN_OUTPUT_VARIABLE <var>`` Report the output from running the executable in a given variable. +``RUN_OUTPUT_STDOUT_VARIABLE <var>`` + .. versionadded:: 3.25 + + Report the output of stdout from running the executable in a given variable. + +``RUN_OUTPUT_STDERR_VARIABLE <var>`` + .. versionadded:: 3.25 + + Report the output of stderr from running the executable in a given variable. + ``WORKING_DIRECTORY <var>`` .. versionadded:: 3.20 @@ -110,6 +122,7 @@ These cache entries are: In order to make cross compiling your project easier, use ``try_run`` only if really required. If you use ``try_run``, use the +``RUN_OUTPUT_STDOUT_VARIABLE``, ``RUN_OUTPUT_STDERR_VARIABLE``, ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really required. Using them will require that when cross-compiling, the cache variables will have to be set manually to the output of the executable. diff --git a/Help/command/while.rst b/Help/command/while.rst index a4957c1..0bafae5 100644 --- a/Help/command/while.rst +++ b/Help/command/while.rst @@ -23,3 +23,11 @@ Per legacy, the :command:`endwhile` command admits an optional ``<condition>`` argument. If used, it must be a verbatim repeat of the argument of the opening ``while`` command. + +See Also +^^^^^^^^ + + * :command:`break` + * :command:`continue` + * :command:`foreach` + * :command:`endwhile` diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst index f429bc5..faf8c74 100644 --- a/Help/cpack_gen/freebsd.rst +++ b/Help/cpack_gen/freebsd.rst @@ -62,8 +62,6 @@ the RPM information (e.g. package license). - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set by CPack itself, if nothing else sets it explicitly). - - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION - parameter for :command:`project`). .. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION @@ -75,6 +73,10 @@ the RPM information (e.g. package license). - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already for Debian packaging, so it is used as a fallback). + - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set + by CPack itself, if nothing else sets it explicitly). + - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION + parameter for :command:`project`). .. variable:: CPACK_FREEBSD_PACKAGE_WWW @@ -85,12 +87,12 @@ the RPM information (e.g. package license). * Mandatory: YES * Default: - - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set, - :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already + - :variable:`CPACK_PACKAGE_HOMEPAGE_URL`, or if that is not set, + - :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already for Debian packaging, so it is used as a fallback). .. versionadded:: 3.12 - The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. + The ``CPACK_PACKAGE_HOMEPAGE_URL`` variable. .. variable:: CPACK_FREEBSD_PACKAGE_LICENSE diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 7638d22..adfa36f 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -7,6 +7,23 @@ See documentation on `CMake Development`_ for more information. .. _`CMake Development`: README.rst +Features are gated behind ``CMAKE_EXPERIMENTAL_`` variables which must be set +to specific values in order to enable their gated behaviors. Note that the +specific values will change over time to reinforce their experimental nature. +When used, a warning will be generated to indicate that an experimental +feature is in use and that the affected behavior in the project is not part of +CMake's stability guarantees. + +C++20 Module APIs +================= + +Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` +Value: ``3c375311-a3c9-4396-a187-3227ef642046`` + +In order to support C++20 modules, there are a number of behaviors that have +CMake APIs to provide the required features to build and export them from a +project. + C++20 Module Dependencies ========================= @@ -40,13 +57,8 @@ dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc`` for scandep rules which use ``msvc``-style dependency reporting. -For tools which need to know the file set the source belongs to, the -``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may -be provided so that different source types can be distinguished prior to -scanning. - The module dependencies should be written in the format described -by the `P1689r4`_ paper. +by the `P1689r5`_ paper. Compiler writers may try out their scanning functionality using the `cxx-modules-sandbox`_ test project, modified to set variables @@ -73,5 +85,5 @@ the GCC documentation, but the relevant section for the purposes of CMake is: -- GCC module mapper documentation .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html -.. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html +.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index cf1ec01..d57cc35 100644 --- a/Help/guide/tutorial/A Basic Starting Point.rst +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -19,8 +19,19 @@ required. This will be the starting point for our tutorial. Create a add_executable(Tutorial tutorial.cxx) -Note that this example uses lower case commands in the ``CMakeLists.txt`` file. -Upper, lower, and mixed case commands are supported by CMake. The source +Any project's top most ``CMakeLists.txt`` must start by specifying +a minimum CMake version using :command:`cmake_minimum_required`. This ensures +that the later CMake functions are run with a compatible version of CMake. + +To start a project, we use :command:`project` to set the project name. This +call is required with every project and should be called soon after +:command:`cmake_minimum_required`. + +Lastly, we use :command:`add_executable` to specify we want an executable +named Tutorial generated using ``tutorial.cxx`` as the source. + +Note that this example uses lower case commands in the ``CMakeLists.txt`` +file. Upper, lower, and mixed case commands are supported by CMake. The source code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be used to compute the square root of a number. @@ -79,7 +90,7 @@ to set the project name and version number. :language: cmake :end-before: # specify the C++ standard -Then, configure a header file to pass the version number to the source +Then use :command:`configure_file` to pass the version number to the source code: .. literalinclude:: Step2/CMakeLists.txt @@ -91,7 +102,8 @@ code: Since the configured file will be written into the binary tree, we must add that directory to the list of paths to search for include -files. Add the following lines to the end of the ``CMakeLists.txt`` file: +files. Use :command:`target_include_directories` to add the following lines to +the end of the ``CMakeLists.txt`` file: .. literalinclude:: Step2/CMakeLists.txt :caption: CMakeLists.txt @@ -107,9 +119,9 @@ directory with the following contents: :name: TutorialConfig.h.in :language: c++ -When CMake configures this header file the values for +When CMake configures this header file, the values for ``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be -replaced. +replaced with the corresponding version numbers from the project. Next modify ``tutorial.cxx`` to include the configured header file, ``TutorialConfig.h``. @@ -141,7 +153,7 @@ Next let's add some C++11 features to our project by replacing ``atof`` with We will need to explicitly state in the CMake code that it should use the correct flags. The easiest way to enable support for a specific C++ standard in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this -tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the +tutorial, :command:`set` the :variable:`CMAKE_CXX_STANDARD` variable in the ``CMakeLists.txt`` file to ``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the call to ``add_executable``. diff --git a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst index c6e0fd0..9ec195c 100644 --- a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst +++ b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst @@ -1,4 +1,4 @@ -Step 8: Adding Support for a Testing Dashboard +Step 5: Adding Support for a Testing Dashboard ============================================== Adding support for submitting our test results to a dashboard is simple. We @@ -9,21 +9,21 @@ we include the :module:`CTest` module in our top-level ``CMakeLists.txt``. Replace: -.. code-block:: cmake +.. literalinclude:: Step5/CMakeLists.txt :caption: CMakeLists.txt :name: CMakeLists.txt-enable_testing-remove - - # enable testing - enable_testing() + :language: cmake + :start-after: # enable testing + :end-before: # does the application run With: -.. code-block:: cmake +.. literalinclude:: Step6/CMakeLists.txt :caption: CMakeLists.txt :name: CMakeLists.txt-include-CTest - - # enable dashboard scripting - include(CTest) + :language: cmake + :start-after: # enable testing + :end-before: # does the application run The :module:`CTest` module will automatically call ``enable_testing()``, so we can remove it from our CMake files. @@ -46,7 +46,7 @@ downloaded from the ``Settings`` page of the project on the CDash instance that will host and display the test results. Once downloaded from CDash, the file should not be modified locally. -.. literalinclude:: Step9/CTestConfig.cmake +.. literalinclude:: Step6/CTestConfig.cmake :caption: CTestConfig.cmake :name: CTestConfig.cmake :language: cmake diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst index 8db0cb8..710e979 100644 --- a/Help/guide/tutorial/Adding System Introspection.rst +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -1,4 +1,4 @@ -Step 5: Adding System Introspection +Step 6: Adding System Introspection =================================== Let us consider adding some code to our project that depends on features the @@ -15,7 +15,7 @@ these functions using the :module:`CheckCXXSourceCompiles` module in Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``, after the call to :command:`target_include_directories`: -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles :language: cmake @@ -25,7 +25,7 @@ after the call to :command:`target_include_directories`: If available, use :command:`target_compile_definitions` to specify ``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-target_compile_definitions :language: cmake @@ -37,7 +37,7 @@ compute the square root in the ``mysqrt`` function. Add the following code to the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the ``#endif`` before returning the result!): -.. literalinclude:: Step6/MathFunctions/mysqrt.cxx +.. literalinclude:: Step7/MathFunctions/mysqrt.cxx :caption: MathFunctions/mysqrt.cxx :name: MathFunctions/mysqrt.cxx-ifdef :language: c++ @@ -46,7 +46,7 @@ the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the We will also need to modify ``mysqrt.cxx`` to include ``cmath``. -.. literalinclude:: Step6/MathFunctions/mysqrt.cxx +.. literalinclude:: Step7/MathFunctions/mysqrt.cxx :caption: MathFunctions/mysqrt.cxx :name: MathFunctions/mysqrt.cxx-include-cmath :language: c++ diff --git a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst index 70c6695..6dc4761 100644 --- a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst +++ b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst @@ -1,4 +1,4 @@ -Step 6: Adding a Custom Command and Generated File +Step 7: Adding a Custom Command and Generated File ================================================== Suppose, for the purpose of this tutorial, we decide that we never want to use @@ -26,7 +26,7 @@ accomplish this. First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for ``MakeTable`` is added as any other executable would be added. -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable :language: cmake @@ -36,7 +36,7 @@ First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for Then we add a custom command that specifies how to produce ``Table.h`` by running MakeTable. -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h :language: cmake @@ -47,7 +47,7 @@ Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated file ``Table.h``. This is done by adding the generated ``Table.h`` to the list of sources for the library MathFunctions. -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add_library-Table.h :language: cmake @@ -57,7 +57,7 @@ of sources for the library MathFunctions. We also have to add the current binary directory to the list of include directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h :language: cmake @@ -67,7 +67,7 @@ directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. Now let's use the generated table. First, modify ``mysqrt.cxx`` to include ``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table: -.. literalinclude:: Step7/MathFunctions/mysqrt.cxx +.. literalinclude:: Step8/MathFunctions/mysqrt.cxx :caption: MathFunctions/mysqrt.cxx :name: MathFunctions/mysqrt.cxx :language: c++ diff --git a/Help/guide/tutorial/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst index 0ee5db2..5f0b27a 100644 --- a/Help/guide/tutorial/Packaging an Installer.rst +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -1,4 +1,4 @@ -Step 7: Packaging an Installer +Step 8: Packaging an Installer ============================== Next suppose that we want to distribute our project to other people so that @@ -11,7 +11,7 @@ installations and package management features. To accomplish this we will use CPack to create platform specific installers. Specifically we need to add a few lines to the bottom of our top-level ``CMakeLists.txt`` file. -.. literalinclude:: Step8/CMakeLists.txt +.. literalinclude:: Step9/CMakeLists.txt :caption: CMakeLists.txt :name: CMakeLists.txt-include-CPack :language: cmake diff --git a/Help/guide/tutorial/Step5/CTestConfig.cmake b/Help/guide/tutorial/Step5/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step5/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index 82d00c8..3ac5cd6 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -37,7 +37,7 @@ install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" ) # enable testing -enable_testing() +include(CTest) # does the application run add_test(NAME Runs COMMAND Tutorial 25) diff --git a/Help/guide/tutorial/Step6/CTestConfig.cmake b/Help/guide/tutorial/Step6/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step6/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index 42e098a..b12f27d 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -6,29 +6,6 @@ target_include_directories(MathFunctions INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} ) -# does this system provide the log and exp functions? -include(CheckCXXSourceCompiles) -check_cxx_source_compiles(" - #include <cmath> - int main() { - std::log(1.0); - return 0; - } -" HAVE_LOG) -check_cxx_source_compiles(" - #include <cmath> - int main() { - std::exp(1.0); - return 0; - } -" HAVE_EXP) - -# add compile definitions -if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(MathFunctions - PRIVATE "HAVE_LOG" "HAVE_EXP") -endif() - # install rules install(TARGETS MathFunctions DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx deleted file mode 100644 index ee58556..0000000 --- a/Help/guide/tutorial/Step6/MathFunctions/MakeTable.cxx +++ /dev/null @@ -1,25 +0,0 @@ -// A simple program that builds a sqrt table -#include <cmath> -#include <fstream> -#include <iostream> - -int main(int argc, char* argv[]) -{ - // make sure we have enough arguments - if (argc < 2) { - return 1; - } - - std::ofstream fout(argv[1], std::ios_base::out); - const bool fileOpen = fout.is_open(); - if (fileOpen) { - fout << "double sqrtTable[] = {" << std::endl; - for (int i = 0; i < 10; ++i) { - fout << sqrt(static_cast<double>(i)) << "," << std::endl; - } - // close the table with a zero - fout << "0};" << std::endl; - fout.close(); - } - return fileOpen ? 0 : 1; // return 0 if wrote the file -} diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx index 7eecd26..abe767d 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -1,4 +1,3 @@ -#include <cmath> #include <iostream> #include "MathFunctions.h" @@ -10,12 +9,6 @@ double mysqrt(double x) return 0; } - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = std::exp(std::log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result - << " using log and exp" << std::endl; -#else double result = x; // do ten iterations @@ -27,6 +20,5 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } -#endif return result; } diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index 82d00c8..3ac5cd6 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -37,7 +37,7 @@ install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" ) # enable testing -enable_testing() +include(CTest) # does the application run add_test(NAME Runs COMMAND Tutorial 25) diff --git a/Help/guide/tutorial/Step7/CTestConfig.cmake b/Help/guide/tutorial/Step7/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step7/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step7/License.txt b/Help/guide/tutorial/Step7/License.txt deleted file mode 100644 index c62d00b..0000000 --- a/Help/guide/tutorial/Step7/License.txt +++ /dev/null @@ -1,2 +0,0 @@ -This is the open source License.txt file introduced in -CMake/Tutorial/Step7... diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt index 9ede4b3..42e098a 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -1,29 +1,34 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) - -# add the main library -add_library(MathFunctions - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) +add_library(MathFunctions mysqrt.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. -# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the -# TutorialConfig.h include is an implementation detail -# state that we depend on our binary dir to find Table.h target_include_directories(MathFunctions INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${CMAKE_CURRENT_BINARY_DIR} ) +# does this system provide the log and exp functions? +include(CheckCXXSourceCompiles) +check_cxx_source_compiles(" + #include <cmath> + int main() { + std::log(1.0); + return 0; + } +" HAVE_LOG) +check_cxx_source_compiles(" + #include <cmath> + int main() { + std::exp(1.0); + return 0; + } +" HAVE_EXP) + +# add compile definitions +if(HAVE_LOG AND HAVE_EXP) + target_compile_definitions(MathFunctions + PRIVATE "HAVE_LOG" "HAVE_EXP") +endif() + # install rules install(TARGETS MathFunctions DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx index 7d80ee9..7eecd26 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -1,10 +1,8 @@ +#include <cmath> #include <iostream> #include "MathFunctions.h" -// include the generated table -#include "Table.h" - // a hack square root calculation using simple operations double mysqrt(double x) { @@ -12,12 +10,13 @@ double mysqrt(double x) return 0; } - // use the table to help find an initial value + // if we have both log and exp then use them +#if defined(HAVE_LOG) && defined(HAVE_EXP) + double result = std::exp(std::log(x) * 0.5); + std::cout << "Computing sqrt of " << x << " to be " << result + << " using log and exp" << std::endl; +#else double result = x; - if (x >= 1 && x < 10) { - std::cout << "Use the table to help find an initial value " << std::endl; - result = sqrtTable[static_cast<int>(x)]; - } // do ten iterations for (int i = 0; i < 10; ++i) { @@ -28,6 +27,6 @@ double mysqrt(double x) result = result + 0.5 * delta / result; std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; } - +#endif return result; } diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index 4c78b94..3ac5cd6 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -37,7 +37,7 @@ install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" ) # enable testing -enable_testing() +include(CTest) # does the application run add_test(NAME Runs COMMAND Tutorial 25) @@ -64,11 +64,3 @@ do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") - -# setup installer -include(InstallRequiredSystemLibraries) -set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") -set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") -set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") -set(CPACK_SOURCE_GENERATOR "TGZ") -include(CPack) diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index 6bae26e..b13a662 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -65,6 +65,7 @@ do_test(Tutorial 25 "25 is 5") do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") +# setup installer include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 09553cb..65d4829 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -25,10 +25,10 @@ provides the complete solution for the previous step. Adding a Library Adding Usage Requirements for a Library Installing and Testing + Adding Support for a Testing Dashboard Adding System Introspection Adding a Custom Command and Generated File Packaging an Installer - Adding Support for a Testing Dashboard Selecting Static or Shared Libraries Adding Generator Expressions Adding Export Configuration diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 93beea9..9dd623a 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -236,6 +236,7 @@ They are normally called through the :command:`find_package` command. /module/FindRuby /module/FindSDL /module/FindSDL_image + /module/FindSDL_gfx /module/FindSDL_mixer /module/FindSDL_net /module/FindSDL_sound diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index d88322c..9fb46be 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -184,6 +184,16 @@ Properties on Targets /prop_tgt/CUDA_STANDARD /prop_tgt/CUDA_STANDARD_REQUIRED /prop_tgt/CXX_EXTENSIONS + /prop_tgt/CXX_MODULE_DIRS + /prop_tgt/CXX_MODULE_DIRS_NAME + /prop_tgt/CXX_MODULE_SET + /prop_tgt/CXX_MODULE_SET_NAME + /prop_tgt/CXX_MODULE_SETS + /prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS + /prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS_NAME + /prop_tgt/CXX_MODULE_HEADER_UNIT_SET + /prop_tgt/CXX_MODULE_HEADER_UNIT_SET_NAME + /prop_tgt/CXX_MODULE_HEADER_UNIT_SETS /prop_tgt/CXX_STANDARD /prop_tgt/CXX_STANDARD_REQUIRED /prop_tgt/DEBUG_POSTFIX @@ -202,6 +212,7 @@ Properties on Targets /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXPORT_COMPILE_COMMANDS /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_NO_SYSTEM /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES @@ -262,6 +273,8 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS + /prop_tgt/INTERFACE_CXX_MODULE_SETS + /prop_tgt/INTERFACE_CXX_MODULE_HEADER_UNIT_SETS /prop_tgt/INTERFACE_HEADER_SETS /prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES @@ -375,6 +388,7 @@ Properties on Targets /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME + /prop_tgt/SYSTEM /prop_tgt/TYPE /prop_tgt/UNITY_BUILD /prop_tgt/UNITY_BUILD_BATCH_SIZE @@ -451,6 +465,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ENVIRONMENT /prop_tgt/XCODE_SCHEME_EXECUTABLE /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_LAUNCH_MODE /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7c8a7fa..ce65aee 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -278,6 +278,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE /variable/CMAKE_XCODE_SCHEME_ENVIRONMENT /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 38105dd..2726f13 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -249,6 +249,11 @@ Options For backward compatibility reasons, ``--loglevel`` is also accepted as a synonym for this option. + .. versionadded:: 3.25 + See the :command:`cmake_language` + :ref:`cmake_language <query_message_log_level>` command for a way to query + the current message logging level. + ``--log-context`` Enable the :command:`message` command outputting context attached to each message. diff --git a/Help/module/FindSDL_gfx.rst b/Help/module/FindSDL_gfx.rst new file mode 100644 index 0000000..e05d661 --- /dev/null +++ b/Help/module/FindSDL_gfx.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindSDL_gfx.cmake diff --git a/Help/prop_tgt/CXX_MODULE_DIRS.rst b/Help/prop_tgt/CXX_MODULE_DIRS.rst new file mode 100644 index 0000000..fdf3831 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_DIRS.rst @@ -0,0 +1,17 @@ +CXX_MODULE_DIRS +--------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of base directories of the target's default +C++ module set (i.e. the file set with name and type ``CXX_MODULES``). The +property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_DIRS_<NAME>` for the list of base directories in +other C++ module sets. diff --git a/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst b/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst new file mode 100644 index 0000000..8c27d45 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst @@ -0,0 +1,17 @@ +CXX_MODULE_DIRS_<NAME> +---------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of base directories of the target's ``<NAME>`` C++ +module set, which has the set type ``CXX_MODULES``. The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_DIRS` for the list of base directories in the +default C++ module set. See :prop_tgt:`CXX_MODULE_SETS` for the file set names +of all C++ module sets. diff --git a/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS.rst b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS.rst new file mode 100644 index 0000000..17e5cf0 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS.rst @@ -0,0 +1,17 @@ +CXX_MODULE_HEADER_UNIT_DIRS +--------------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of base directories of the target's default C++ +module header set (i.e. the file set with name and type +``CXX_MODULE_HEADER_UNITS``). The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS_<NAME>` for the list of base directories +in other C++ module header sets. diff --git a/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS_NAME.rst b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS_NAME.rst new file mode 100644 index 0000000..ca30f23 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS_NAME.rst @@ -0,0 +1,19 @@ +CXX_MODULE_HEADER_UNIT_DIRS_<NAME> +---------------------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of base directories of the target's ``<NAME>`` C++ +module header set, which has the set type ``CXX_MODULE_HEADER_UNITS``. The +property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS` for the list of base directories +in the default C++ module header set. See +:prop_tgt:`CXX_MODULE_HEADER_UNIT_SETS` for the file set names of all C++ +module header sets. diff --git a/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SET.rst b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SET.rst new file mode 100644 index 0000000..f67a848 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SET.rst @@ -0,0 +1,18 @@ +CXX_MODULE_HEADER_UNIT_SET +-------------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of files in the target's default C++ module header +set, (i.e. the file set with name and type ``CXX_MODULE_HEADER_UNITS``). If +any of the paths are relative, they are computed relative to the target's +source directory. The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET_<NAME>` for the list of files in +other C++ module header sets. diff --git a/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SETS.rst b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SETS.rst new file mode 100644 index 0000000..7b4bd3f --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SETS.rst @@ -0,0 +1,18 @@ +CXX_MODULE_HEADER_UNIT_SETS +--------------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` C++ module header +sets (i.e. all file sets with the type ``CXX_MODULE_HEADER_UNITS``). Files +listed in these file sets are treated as source files for the purpose of IDE +integration. + +C++ module header sets may be defined using the :command:`target_sources` +command ``FILE_SET`` option with type ``CXX_MODULE_HEADER_UNITS``. + +See also :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET_<NAME>`, +:prop_tgt:`CXX_MODULE_HEADER_UNIT_SET` and +:prop_tgt:`INTERFACE_CXX_MODULE_HEADER_UNIT_SETS`. diff --git a/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SET_NAME.rst b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SET_NAME.rst new file mode 100644 index 0000000..d328950 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_HEADER_UNIT_SET_NAME.rst @@ -0,0 +1,19 @@ +CXX_MODULE_HEADER_UNIT_SET_<NAME> +--------------------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of files in the target's ``<NAME>`` C++ module header +set, which has the set type ``CXX_MODULE_HEADER_UNITS``. If any of the paths +are relative, they are computed relative to the target's source directory. The +property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET` for the list of files in the +default C++ module header set. See :prop_tgt:`CXX_MODULE_HEADER_UNIT_SETS` for +the file set names of all C++ module header sets. diff --git a/Help/prop_tgt/CXX_MODULE_SET.rst b/Help/prop_tgt/CXX_MODULE_SET.rst new file mode 100644 index 0000000..ae9000e --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_SET.rst @@ -0,0 +1,18 @@ +CXX_MODULE_SET +-------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of files in the target's default C++ module set, +(i.e. the file set with name and type ``CXX_MODULES``). If any of the paths +are relative, they are computed relative to the target's source directory. The +property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_SET_<NAME>` for the list of files in other C++ +module sets. diff --git a/Help/prop_tgt/CXX_MODULE_SETS.rst b/Help/prop_tgt/CXX_MODULE_SETS.rst new file mode 100644 index 0000000..c03df39 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_SETS.rst @@ -0,0 +1,16 @@ +CXX_MODULE_SETS +--------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` C++ module sets (i.e. +all file sets with the type ``CXX_MODULES``). Files listed in these file sets are +treated as source files for the purpose of IDE integration. + +C++ module sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``CXX_MODULES``. + +See also :prop_tgt:`CXX_MODULE_SET_<NAME>`, :prop_tgt:`CXX_MODULE_SET` and +:prop_tgt:`INTERFACE_CXX_MODULE_SETS`. diff --git a/Help/prop_tgt/CXX_MODULE_SET_NAME.rst b/Help/prop_tgt/CXX_MODULE_SET_NAME.rst new file mode 100644 index 0000000..27c88f3 --- /dev/null +++ b/Help/prop_tgt/CXX_MODULE_SET_NAME.rst @@ -0,0 +1,18 @@ +CXX_MODULE_SET_<NAME> +--------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Semicolon-separated list of files in the target's ``<NAME>`` C++ module set, +which has the set type ``CXX_MODULES``. If any of the paths are relative, they +are computed relative to the target's source directory. The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`CXX_MODULE_SET` for the list of files in the default C++ module +set. See :prop_tgt:`CXX_MODULE_SETS` for the file set names of all C++ module +sets. diff --git a/Help/prop_tgt/EXPORT_NO_SYSTEM.rst b/Help/prop_tgt/EXPORT_NO_SYSTEM.rst new file mode 100644 index 0000000..c93d1a5 --- /dev/null +++ b/Help/prop_tgt/EXPORT_NO_SYSTEM.rst @@ -0,0 +1,11 @@ +EXPORT_NO_SYSTEM +---------------- + +.. versionadded:: 3.25 + +Specifies that :command:`install(EXPORT)` and :command:`export` commands will +generate a imported target with :prop_tgt:`SYSTEM` property `OFF`. + +See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this +behavior on the target consuming the include directories rather than +providing them. diff --git a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst index ee22d6f..913d9f2 100644 --- a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst +++ b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst @@ -3,11 +3,21 @@ IMPORTED_NO_SYSTEM .. versionadded:: 3.23 +.. deprecated:: 3.25 + + ``IMPORTED_NO_SYSTEM`` is deprecated. Set :prop_tgt:`SYSTEM` to `OFF` + instead if you don't want target's include directories to be ``SYSTEM`` + when compiling consumers. Set :prop_tgt:`EXPORT_NO_SYSTEM` to `ON` instead + if you don't want the include directories of the imported target generated + by :command:`install(EXPORT)` and :command:`export` commands to be + ``SYSTEM`` when compiling consumers. + Specifies that an :ref:`Imported Target <Imported Targets>` is not a ``SYSTEM`` library. This has the following effects: * Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated - as ``SYSTEM`` include directories when compiling consumers, as they + as ``SYSTEM`` include directories when compiling consumers (regardless of + the value of the consumed target's :prop_tgt:`SYSTEM` property), as they would be by default. Entries of :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected, and will always be treated as ``SYSTEM`` include directories. diff --git a/Help/prop_tgt/INTERFACE_CXX_MODULE_HEADER_UNIT_SETS.rst b/Help/prop_tgt/INTERFACE_CXX_MODULE_HEADER_UNIT_SETS.rst new file mode 100644 index 0000000..eb3a9ff --- /dev/null +++ b/Help/prop_tgt/INTERFACE_CXX_MODULE_HEADER_UNIT_SETS.rst @@ -0,0 +1,16 @@ +INTERFACE_CXX_MODULE_HEADER_UNIT_SETS +------------------------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Read-only list of the target's ``PUBLIC`` C++ module header sets (i.e. all +file sets with the type ``CXX_MODULE_HEADER_UNITS``). Files listed in these +C++ module header sets can be installed with :command:`install(TARGETS)` and +exported with :command:`install(EXPORT)` and :command:`export`. + +C++ module header sets may be defined using the :command:`target_sources` +command ``FILE_SET`` option with type ``CXX_MODULE_HEADER_UNITS``. + +See also :prop_tgt:`CXX_MODULE_HEADER_UNIT_SETS`. diff --git a/Help/prop_tgt/INTERFACE_CXX_MODULE_SETS.rst b/Help/prop_tgt/INTERFACE_CXX_MODULE_SETS.rst new file mode 100644 index 0000000..cc30386 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_CXX_MODULE_SETS.rst @@ -0,0 +1,16 @@ +INTERFACE_CXX_MODULE_SETS +------------------------- + +.. note :: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` + +Read-only list of the target's ``PUBLIC`` C++ module sets (i.e. all file sets +with the type ``CXX_MODULES``). Files listed in these C++ module sets can be +installed with :command:`install(TARGETS)` and exported with +:command:`install(EXPORT)` and :command:`export`. + +C++ module sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``CXX_MODULES``. + +See also :prop_tgt:`CXX_MODULE_SETS`. diff --git a/Help/prop_tgt/SYSTEM.rst b/Help/prop_tgt/SYSTEM.rst new file mode 100644 index 0000000..2db6aed --- /dev/null +++ b/Help/prop_tgt/SYSTEM.rst @@ -0,0 +1,16 @@ +SYSTEM +------ + +.. versionadded:: 3.25 + +Specifies that a target is a ``SYSTEM`` library. This has the following effects: + +* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are treated as ``SYSTEM`` + include directories when compiling consumers. + Entries of :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected, + and will always be treated as ``SYSTEM`` include directories. + +For imported targets, this property has a default value `ON`, which means that their +`INTERFACE_INCLUDE_DIRECTORIES` are treated as ``SYSTEM`` by default. If their +`SYSTEM` property is `OFF`, then their `INTERFACE_INCLUDE_DIRECTORIES` will not be +treated as ``SYSTEM``, regardless of the value of `IMPORTED_NO_SYSTEM` property. diff --git a/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst index da461a7..dd415c8 100644 --- a/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst +++ b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst @@ -26,6 +26,10 @@ Otherwise, if C++ is enabled globally, the header is compiled as C++. Otherwise, if C is enabled globally, the header is compiled as C. Otherwise, the header file is not compiled. +If any verification targets are created, a top-level target called +``all_verify_interface_header_sets`` is created which depends on all +verification targets. + This property is initialized by the value of the :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable if it is set when a target is created. diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst index 8f46d2f..eceddc1 100644 --- a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -41,4 +41,5 @@ The following target properties will be applied on the - :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` - :prop_tgt:`XCODE_SCHEME_EXECUTABLE` +- :prop_tgt:`XCODE_SCHEME_LAUNCH_MODE` - :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` diff --git a/Help/prop_tgt/XCODE_SCHEME_LAUNCH_MODE.rst b/Help/prop_tgt/XCODE_SCHEME_LAUNCH_MODE.rst new file mode 100644 index 0000000..df5ae07 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_LAUNCH_MODE.rst @@ -0,0 +1,22 @@ +XCODE_SCHEME_LAUNCH_MODE +------------------------ + +.. versionadded:: 3.25 + +Property value for ``Launch`` in the Info section of the generated Xcode +scheme. + +Possible values are: + +``AUTO`` + Launch automatically. This is the default. + +``WAIT`` + Wait for the executable to be launched. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_LAUNCH_MODE` 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/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/FindVulkan-dxc.rst b/Help/release/dev/FindVulkan-dxc.rst new file mode 100644 index 0000000..e22f016 --- /dev/null +++ b/Help/release/dev/FindVulkan-dxc.rst @@ -0,0 +1,5 @@ +FindVulkan-dxc +-------------- + +* The :module:`FindVulkan` module gained support for a DirectX Shader Compiler + component, ``dxc``. diff --git a/Help/release/dev/cmake_language_GET_MESSAGE_LOG_LEVEL.rst b/Help/release/dev/cmake_language_GET_MESSAGE_LOG_LEVEL.rst new file mode 100644 index 0000000..6e99a05 --- /dev/null +++ b/Help/release/dev/cmake_language_GET_MESSAGE_LOG_LEVEL.rst @@ -0,0 +1,6 @@ +cmake-language_GET_MESSAGE_LOG_LEVEL +------------------------------------ + +* The :command:`cmake_language` command gained a new + ``GET_MESSAGE_LOG_LEVEL`` sub-command. It can be used to + query the current message logging level. diff --git a/Help/release/dev/cuda-device-lto.rst b/Help/release/dev/cuda-device-lto.rst new file mode 100644 index 0000000..113062b --- /dev/null +++ b/Help/release/dev/cuda-device-lto.rst @@ -0,0 +1,7 @@ +cuda-device-lto +--------------- + +* ``CUDA`` language now supports device link time optimization when using + ``nvcc``. The :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable and + the associated :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property will + activate device LTO. diff --git a/Help/release/dev/find_item-VALIDATOR.rst b/Help/release/dev/find_item-VALIDATOR.rst new file mode 100644 index 0000000..2cda421 --- /dev/null +++ b/Help/release/dev/find_item-VALIDATOR.rst @@ -0,0 +1,6 @@ +find_item-VALIDATOR +------------------- + +* :command:`find_file`, :command:`find_path`, :command:`find_library`, and + :command:`find_program` commands gain the capability to specify a function + which will be called for each found item to validate it. diff --git a/Help/release/dev/finddoxygen-better-version-checking.rst b/Help/release/dev/finddoxygen-better-version-checking.rst new file mode 100644 index 0000000..3c2215d --- /dev/null +++ b/Help/release/dev/finddoxygen-better-version-checking.rst @@ -0,0 +1,11 @@ +finddoxygen-better-version-checking +----------------------------------- + +* The :module:`FindDoxygen` module now evaluates as many candidate + Doxygen installs as are necessary to satisfy version constraints, + with the package considered to be not found if none are available. + +* The :module:`FindDoxygen` module now handles version ranges. + +* The :module:`FindDoxygen` module now ignores non-semantic portions + of the output from Doxygen's `--version` option. diff --git a/Help/release/dev/findopenal-add-import-library.rst b/Help/release/dev/findopenal-add-import-library.rst new file mode 100644 index 0000000..6c9c93f --- /dev/null +++ b/Help/release/dev/findopenal-add-import-library.rst @@ -0,0 +1,4 @@ +findopenal-add-import-library +----------------------------- + +* The :module:`FindOpenAL` module now provides an imported target. diff --git a/Help/release/dev/findvulkan-volk.rst b/Help/release/dev/findvulkan-volk.rst new file mode 100644 index 0000000..cb77078 --- /dev/null +++ b/Help/release/dev/findvulkan-volk.rst @@ -0,0 +1,5 @@ +findvulkan-volk +--------------- + +* The :module:`FindVulkan` module now includes a ``volk`` component + for the Volk open source vulkan meta-loader. diff --git a/Help/release/dev/p1689r5.rst b/Help/release/dev/p1689r5.rst new file mode 100644 index 0000000..a630dc4 --- /dev/null +++ b/Help/release/dev/p1689r5.rst @@ -0,0 +1,6 @@ +p1689r5 +------- + +* C++ module scanning now supports the latest revision, `P1689R5`_. + +.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html diff --git a/Help/release/dev/system.rst b/Help/release/dev/system.rst new file mode 100644 index 0000000..7cc841e --- /dev/null +++ b/Help/release/dev/system.rst @@ -0,0 +1,15 @@ +system +------ + +* The :prop_tgt:`SYSTEM` target property was added to specify + that a target should be treated as a system library (i.e. + its include directories are automatically ``SYSTEM`` when + compiling consumers). + +* The :prop_tgt:`EXPORT_NO_SYSTEM` target property was added to + specify that :command:`install(EXPORT)` and :command:`export` + commands will generate a imported target with + :prop_tgt:`SYSTEM` property `OFF`. + +* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was deprecated + in favor of :prop_tgt:`SYSTEM` and :prop_tgt:`EXPORT_NO_SYSTEM`. diff --git a/Help/release/dev/try_run_split_output.rst b/Help/release/dev/try_run_split_output.rst new file mode 100644 index 0000000..98aedd6 --- /dev/null +++ b/Help/release/dev/try_run_split_output.rst @@ -0,0 +1,6 @@ +try_run_split_output +-------------------- + +* The :command:`try_run` command gained ``RUN_OUTPUT_STDOUT_VARIABLE`` + and ``RUN_OUTPUT_STDERR_VARIABLE`` options to capture stdout and stderr + separately from the output of the compiled program. diff --git a/Help/release/dev/xcode-launch-mode.rst b/Help/release/dev/xcode-launch-mode.rst new file mode 100644 index 0000000..32b9ee6 --- /dev/null +++ b/Help/release/dev/xcode-launch-mode.rst @@ -0,0 +1,7 @@ +xcode-launch-mode +----------------- + +* The :variable:`CMAKE_XCODE_SCHEME_LAUNCH_MODE` variable and corresponding + :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. diff --git a/Help/release/index.rst b/Help/release/index.rst index 4dfac8a..11d5a11 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst index 3b45d1d..54ea6a4 100644 --- a/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst +++ b/Help/variable/CMAKE_MESSAGE_LOG_LEVEL.rst @@ -15,3 +15,8 @@ subsequent CMake runs will continue to use the chosen log level. Projects should not set this variable, it is intended for users so that they may control the log level according to their own needs. + +.. versionadded:: 3.25 + See the :command:`cmake_language` + :ref:`cmake_language <query_message_log_level>` command for a way to query + the current message logging level. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE.rst b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE.rst new file mode 100644 index 0000000..c15b1ea --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_LAUNCH_MODE +------------------------------ + +.. versionadded:: 3.25 + +Property value for ``Launch`` in the Info section of the generated Xcode +scheme. + +This variable initializes the :prop_tgt:`XCODE_SCHEME_LAUNCH_MODE` property on +all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. |