diff options
Diffstat (limited to 'Help')
98 files changed, 1744 insertions, 150 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 97eecfc..aae1c38 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -11,8 +11,8 @@ The general signature is: |FIND_XXX| ( <VAR> name | |NAMES| - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] + [HINTS [path | ENV var]... ] + [PATHS [path | ENV var]... ] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [REQUIRED] diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index c0b9593..569f1e8 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -271,21 +271,28 @@ The options are: ``DEPFILE`` .. versionadded:: 3.7 - Specify a ``.d`` depfile for the :generator:`Ninja` generator and - :ref:`Makefile Generators`. - A ``.d`` file holds dependencies usually emitted by the custom - command itself. - Using ``DEPFILE`` with other generators than :generator:`Ninja` or - :ref:`Makefile Generators` is an error. + Specify a ``.d`` depfile for the :generator:`Ninja`, :generator:`Xcode` and + :ref:`Makefile <Makefile Generators>` generators. The depfile may use + "generator expressions" with the syntax ``$<...>``. See the + :manual:`generator-expressions(7) <cmake-generator-expressions(7)>` manual + for available expressions. A ``.d`` file holds dependencies usually emitted + by the custom command itself. + + Using ``DEPFILE`` with other generators than :generator:`Ninja`, + :generator:`Xcode` or :ref:`Makefile <Makefile Generators>` is an error. .. versionadded:: 3.20 Added the support of :ref:`Makefile Generators`. + .. versionadded:: 3.21 + Added the support of :generator:`Xcode` generator and + :manual:`generator expressions <cmake-generator-expressions(7)>`. + If the ``DEPFILE`` argument is relative, it should be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR` (see policy :policy:`CMP0116`. This policy is always ``NEW`` for - :ref:`Makefile Generators`). + :ref:`Makefile <Makefile Generators>` and :generator:`Xcode` generators). .. note:: diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index c3b3e73..2cc3cfe 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -5,21 +5,21 @@ Require a minimum version of cmake. .. code-block:: cmake - cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) + cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR]) .. versionadded:: 3.12 - The optional ``<max>`` version. + The optional ``<policy_max>`` version. Sets the minimum required version of cmake for a project. Also updates the policy settings as explained below. -``<min>`` and the optional ``<max>`` are each CMake versions of the form -``major.minor[.patch[.tweak]]``, and the ``...`` is literal. +``<min>`` and the optional ``<policy_max>`` are each CMake versions of the +form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. If the running version of CMake is lower than the ``<min>`` required version it will stop processing the project and report an error. -The optional ``<max>`` version, if specified, must be at least the -``<min>`` version and affects policy settings as described below. +The optional ``<policy_max>`` version, if specified, must be at least the +``<min>`` version and affects policy settings as described in `Policy Settings`_. If the running version of CMake is older than 3.12, the extra ``...`` dots will be seen as version component separators, resulting in the ``...<max>`` part being ignored and preserving the pre-3.12 behavior @@ -43,6 +43,8 @@ with an error instead of just a warning. limits some effects to the function scope when invoked. Such calls should not be made with the intention of having global effects. +.. _`Policy Settings`: + Policy Settings ^^^^^^^^^^^^^^^ diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index a8999f3..193180d 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -687,7 +687,8 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized <Normalization>` after the path computation. Because ``cmake_path()`` does not access the filesystem, symbolic links are -not resolved. To compute a real path with symbolic links resolved, use the +not resolved and any leading tilde is not expanded. To compute a real path +with symbolic links resolved and leading tildes expanded, use the :command:`file(REAL_PATH)` command instead. Native Conversion diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index d00f08b..086668c 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -36,8 +36,30 @@ or depending on whether ``VAR`` is set in CMake to any value not considered a false constant by the :command:`if` command. The "..." content on the line after the variable name, if any, is processed as above. -Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with -either ``#define VAR 1`` or ``#define VAR 0`` similarly. + +Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form +``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1`` +rather than being assigned the value ``...``. Therefore, input lines of the form + +.. code-block:: c + + #cmakedefine01 VAR + +will be replaced with either + +.. code-block:: c + + #define VAR 0 + +or + +.. code-block:: c + + #define VAR 1 + +Input lines of the form ``#cmakedefine01 VAR ...`` will expand +as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, +which may lead to undefined behavior. .. versionadded:: 3.10 The result lines (with the exception of the ``#undef`` comments) can be diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index b4493a0..c61d01e 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -25,6 +25,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [RETURN_VALUE <result-var>] [CAPTURE_CMAKE_ERROR <result-var>] [REPEAT <mode>:<n>] + [OUTPUT_JUNIT <file>] [QUIET] ) @@ -150,6 +151,15 @@ The options are: Store in the ``<result-var>`` variable -1 if there are any errors running the command and prevent ctest from returning non-zero if an error occurs. +``OUTPUT_JUNIT`` + .. versionadded:: 3.21 + + Write test results to ``<file>`` in JUnit XML format. If ``<file>`` is a + relative path it will be placed in the build directory. If ``<file>>`` + already exists it will be overwritten. Note that the resulting JUnit XML + file is **not** uploaded to CDash because it would be redundant with + CTest's ``Test.xml`` file. + ``QUIET`` .. versionadded:: 3.3 @@ -160,3 +170,83 @@ The options are: See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. + +.. _`Additional Test Measurements`: + +Additional Test Measurements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CTest can parse the output of your tests for extra measurements to report +to CDash. + +When run as a :ref:`Dashboard Client`, CTest will include these custom +measurements in the ``Test.xml`` file that gets uploaded to CDash. + +Check the `CDash test measurement documentation +<https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_ +for more information on the types of test measurements that CDash recognizes. + +The following example demonstrates how to output a variety of custom test +measurements. + +.. code-block:: c++ + + std::cout << + "<DartMeasurement type=\"numeric/double\" name=\"score\">28.3</DartMeasurement>" + << std::endl; + + std::cout << + "<DartMeasurement type=\"text/string\" name=\"color\">red</DartMeasurement>" + << std::endl; + + std::cout << + "<DartMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</DartMeasurement>" + << std::endl; + + std::cout << + "<DartMeasurement type=\"text/preformatted\" name=\"Console Output\">" << + "line 1.\n" << + " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" << + "line 3. Not bold or indented...\n" << + "</DartMeasurement>" << std::endl; + +Image Measurements +"""""""""""""""""" + +The following example demonstrates how to upload test images to CDash. + +.. code-block:: c++ + + std::cout << + "<DartMeasurementFile type=\"image/jpg\" name=\"TestImage\">" << + "/dir/to/test_img.jpg</DartMeasurementFile>" << std::endl; + + std::cout << + "<DartMeasurementFile type=\"image/gif\" name=\"ValidImage\">" << + "/dir/to/valid_img.gif</DartMeasurementFile>" << std::endl; + + std::cout << + "<DartMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << + "/dir/to/img.png</DartMeasurementFile>" + << std::endl; + +Images will be displayed together in an interactive comparison mode on CDash +if they are provided with two or more of the following names. + +* ``TestImage`` +* ``ValidImage`` +* ``BaselineImage`` +* ``DifferenceImage2`` + +By convention, ``TestImage`` is the image generated by your test, and +``ValidImage`` (or ``BaselineImage``) is basis of comparison used to determine +if the test passed or failed. + +If another image name is used it will be displayed by CDash as a static image +separate from the interactive comparison UI. + +Attached Files +"""""""""""""" + +To associate other types of files with a test, use the +:prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test properties. diff --git a/Help/command/file.rst b/Help/command/file.rst index 31de610..e170526 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -38,7 +38,8 @@ Synopsis `Filesystem`_ file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) - file(`RENAME`_ <oldname> <newname>) + file(`RENAME`_ <oldname> <newname> [...]) + file(`COPY_FILE`_ <oldname> <newname> [...]) file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) file(`MAKE_DIRECTORY`_ [<dir>...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) @@ -49,7 +50,7 @@ Synopsis file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) `Path Conversion`_ - file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>]) + file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) file(`RELATIVE_PATH`_ <out-var> <directory> <file>) file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) @@ -675,11 +676,46 @@ Examples of recursive globbing include:: .. code-block:: cmake - file(RENAME <oldname> <newname>) + file(RENAME <oldname> <newname> + [RESULT <result>] + [NO_REPLACE]) Move a file or directory within a filesystem from ``<oldname>`` to ``<newname>``, replacing the destination atomically. +The options are: + +``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``NO_REPLACE`` + If the ``<newname>`` path already exists, do not replace it. + If ``RESULT <result>`` is used, the result variable will be + set to ``NO_REPLACE``. Otherwise, an error is emitted. + +.. _COPY_FILE: + +.. code-block:: cmake + + file(COPY_FILE <oldname> <newname> + [RESULT <result>] + [ONLY_IF_DIFFERENT]) + +Copy a file from ``<oldname>`` to ``<newname>``. Directories are not +supported. Symlinks are ignored and ``<oldfile>``'s content is read and +written to ``<newname>`` as a new file. + +The options are: + +``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``ONLY_IF_DIFFERENT`` + If the ``<newname>`` path already exists, do not replace it if it is the + same as ``<oldname>``. Otherwise, an error is emitted. + .. _REMOVE: .. _REMOVE_RECURSE: @@ -888,16 +924,26 @@ Path Conversion .. code-block:: cmake - file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>]) + file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) .. versionadded:: 3.19 Compute the absolute path to an existing file or directory with symlinks resolved. -If the provided ``<path>`` is a relative path, it is evaluated relative to the -given base directory ``<dir>``. If no base directory is provided, the default -base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. +``BASE_DIRECTORY <dir>`` + If the provided ``<path>`` is a relative path, it is evaluated relative to the + given base directory ``<dir>``. If no base directory is provided, the default + base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. + +``EXPAND_TILDE`` + .. versionadded:: 3.21 + + If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced by + the user's home directory. The path to the home directory is obtained from + environment variables. On Windows, the ``USERPROFILE`` environment variable + is used, falling back to the ``HOME`` environment variable if ``USERPROFILE`` + is not defined. On all other platforms, only ``HOME`` is used. .. _RELATIVE_PATH: diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 8de6deb..d9f54ca 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -14,9 +14,12 @@ semicolon or whitespace. All commands between ``foreach`` and the matching ``endforeach`` are recorded without being invoked. Once the ``endforeach`` is evaluated, the recorded list of commands is invoked once for each item in ``<items>``. -At the beginning of each iteration the variable ``loop_var`` will be set +At the beginning of each iteration the variable ``<loop_var>`` will be set to the value of the current item. +The scope of ``<loop_var>`` is restricted to the loop scope. See policy +:policy:`CMP0124` for details. + The commands :command:`break` and :command:`continue` provide means to escape from the normal control flow. diff --git a/Help/command/project.rst b/Help/command/project.rst index 6c931b6..8a6bc1e 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -20,12 +20,18 @@ Sets the name of the project, and stores it in the variable ``CMakeLists.txt`` also stores the project name in the variable :variable:`CMAKE_PROJECT_NAME`. -Also sets the variables +Also sets the variables: -* :variable:`PROJECT_SOURCE_DIR`, - :variable:`<PROJECT-NAME>_SOURCE_DIR` -* :variable:`PROJECT_BINARY_DIR`, - :variable:`<PROJECT-NAME>_BINARY_DIR` +:variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR` + Absolute path to the source directory for the project. + +:variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` + Absolute path to the binary directory for the project. + +:variable:`PROJECT_IS_TOP_LEVEL`, :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` + .. versionadded:: 3.21 + + Boolean value indicating whether the project is top-level. Further variables are set by the optional arguments described in the following. If any of these arguments is not used, then the corresponding variables are diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index b941812..47e8e13 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -82,7 +82,8 @@ CPack generators which are essentially archives at their core. These include: See also the :variable:`CPACK_THREADS` variable. -.. note:: + .. versionadded:: 3.21 - Official CMake binaries available on ``cmake.org`` ship with a ``liblzma`` - that does not support parallel compression. + Official CMake binaries available on ``cmake.org`` now ship + with a ``liblzma`` that supports parallel compression. + Older versions did not. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 4c662a6..ec2cf1e 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -103,6 +103,12 @@ on macOS: - Default: ``CPACK_PACKAGE_FILE_NAME-<component>`` +.. variable:: CPACK_DMG_FILESYSTEM + + The filesystem format. Common values are ``APFS`` and ``HFS+``. + See ``man hdiutil`` for a full list of supported formats. + Defaults to ``HFS+``. + .. variable:: CPACK_COMMAND_HDIUTIL Path to the ``hdiutil(1)`` command used to operate on disk image files on diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index de1f3b5..02e33ba 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -195,3 +195,9 @@ on Windows Nullsoft Scriptable Install System. If set, trim down the size of the control to the size of the branding text string. Allowed values for this variable are ``LEFT``, ``CENTER`` or ``RIGHT``. If not specified, the default behavior is ``LEFT``. + +.. variable:: CPACK_NSIS_EXECUTABLE + + .. versionadded:: 3.21 + + If set, specify the name of the NSIS executable. Default is ``makensis``. diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 8326e70..10ff87b 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -254,7 +254,8 @@ The preferred form for references to other commits is The author date of the commit, in its original time zone, formatted as ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. -This may be generated with +This may be generated with ``git show -s --pretty=reference <commit>`` with +Git 2.25 and newer. Older versions of Git can generate the same format via ``git show -s --date=short --pretty="format:%h (%s, %ad)" <commit>``. If the commit is a fix for the mentioned commit, consider using a ``Fixes:`` diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst index 963f9d1..cf65927 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -15,6 +15,10 @@ ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. This environment variable is primarily meant for use with projects that enable ``CUDA`` as a first-class language. +.. note:: + + Ignored when using :ref:`Visual Studio Generators`. + .. versionadded:: 3.13 The :module:`FindCUDA` module will use this variable to initialize its ``CUDA_HOST_COMPILER`` setting. diff --git a/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt index 9a9e40e..d277b54 100644 --- a/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt @@ -1,6 +1,9 @@ cmake_minimum_required(VERSION 3.15) project(MathFunctions) +# make cache variables for install destinations +include(GNUInstallDirs) + # specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) @@ -12,26 +15,26 @@ add_library(MathFunctions STATIC MathFunctions.cxx) target_include_directories(MathFunctions PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" - "$<INSTALL_INTERFACE:include>" + "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>" ) # install the target and create export-set install(TARGETS MathFunctions EXPORT MathFunctionsTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES MathFunctions.h DESTINATION include) +install(FILES MathFunctions.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT MathFunctionsTargets FILE MathFunctionsTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # include CMakePackageConfigHelpers macro @@ -58,14 +61,14 @@ write_basic_package_version_file( # create config file configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION lib/cmake/MathFunctions + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # install config files install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # generate the export targets for the build tree diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt index 17ad952..9de935e 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt @@ -7,24 +7,24 @@ add_library(MathFunctions::Addition ALIAS Addition) target_include_directories(Addition PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" - $<INSTALL_INTERFACE:include> + $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}> ) # install the target and create export-set install(TARGETS Addition EXPORT AdditionTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES Addition.h DESTINATION include) +install(FILES Addition.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT AdditionTargets FILE MathFunctionsAdditionTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt index fd95e28..90ee89f 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt @@ -1,6 +1,9 @@ cmake_minimum_required(VERSION 3.15) project(MathFunctionsComponents) +# make cache variables for install destinations +include(GNUInstallDirs) + # specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) @@ -24,7 +27,7 @@ write_basic_package_version_file( # create config file configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION lib/cmake/MathFunctions + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions NO_CHECK_REQUIRED_COMPONENTS_MACRO ) @@ -32,5 +35,5 @@ configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt index be5ae65..517c5e2 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt @@ -7,24 +7,24 @@ add_library(MathFunctions::SquareRoot ALIAS SquareRoot) target_include_directories(SquareRoot PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" - "$<INSTALL_INTERFACE:include>" + "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>" ) # install the target and create export-set install(TARGETS SquareRoot EXPORT SquareRootTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES SquareRoot.h DESTINATION include) +install(FILES SquareRoot.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT SquareRootTargets FILE MathFunctionsSquareRootTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/index.rst b/Help/guide/importing-exporting/index.rst index 2e6e06d..3e60250 100644 --- a/Help/guide/importing-exporting/index.rst +++ b/Help/guide/importing-exporting/index.rst @@ -202,6 +202,10 @@ project. Start by specifying the :command:`cmake_minimum_required` version and :language: cmake :end-before: # create library +The :module:`GNUInstallDirs` module is included in order to provide the +project with the flexibility to install into different platform layouts by +making the directories available as cache variables. + Create a library called ``MathFunctions`` with the :command:`add_library` command: diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt index eca79d9..1b0c826 100644 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -110,6 +110,7 @@ write_basic_package_version_file( # install the configuration file install(FILES ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake DESTINATION lib/cmake/MathFunctions ) diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 0947e41..c4f83f7 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -76,6 +76,14 @@ native build system to choose a compiler or SDK. See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. +``--toolchain <path-to-file>`` + Specify the cross compiling toolchain file, equivalant to setting + :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +``--install-prefix <directory>`` + Specify the installation directory, used by the + :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. + ``-Wno-dev`` Suppress developer warnings. diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 2c2b04c..2b0de11 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -261,6 +261,7 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * ``Cray``: Cray Compiler Environment version 8.1+. +* ``Fujitsu``: Fujitsu HPC compiler 4.0+. * ``PGI``: PGI version 12.10+. * ``NVHPC``: NVIDIA HPC compilers version 11.0+. * ``TI``: Texas Instruments compiler. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index af9a8ab..fe146de 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -350,6 +350,24 @@ look. PATHS ${PC_Foo_LIBRARY_DIRS} ) +Alternatively, if the library is available with multiple configurations, you can +use :module:`SelectLibraryConfigurations` to automatically set the +``Foo_LIBRARY`` variable instead: + +.. code-block:: cmake + + find_library(Foo_LIBRARY_RELEASE + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Release + ) + find_library(Foo_LIBRARY_DEBUG + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Debug + ) + + include(SelectLibraryConfigurations) + select_library_configurations(Foo) + If you have a good way of getting the version (from a header file, for example), you can use that information to set ``Foo_VERSION`` (although note that find modules have traditionally used ``Foo_VERSION_STRING``, diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 89739b7..cbc3d6d 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -443,7 +443,8 @@ Version 1 does not exist to avoid confusion with that from "hasInstallRule": true, "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "<file>" }, { "source": "sub", @@ -453,7 +454,8 @@ Version 1 does not exist to avoid confusion with that from "targetIndexes": [ 1 ], "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "<file>" } ], "projects": [ @@ -569,6 +571,13 @@ The members specific to ``codemodel`` objects are: :command:`install` rules, i.e. whether a ``make install`` or equivalent rule is available. + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "directory" object`_. + + This field was added in codemodel version 2.3. + ``projects`` A JSON array of entries corresponding to the top-level project and sub-projects defined in the build system. Each (sub-)project @@ -633,6 +642,182 @@ The members specific to ``codemodel`` objects are: to another JSON file containing a `"codemodel" version 2 "target" object`_. +"codemodel" version 2 "directory" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "directory" object is referenced by a `"codemodel" version 2`_ +object's ``directories`` array. Each "directory" object is a JSON object +with members: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the path to the source directory, represented + with forward slashes. If the directory is inside the top-level + source directory then the path is specified relative to that + directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the build directory, represented + with forward slashes. If the directory is inside the top-level + build directory then the path is specified relative to that + directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + +``installers`` + A JSON array of entries corresponding to :command:`install` rules. + Each entry is a JSON object containing members: + + ``component`` + A string specifying the component selected by the corresponding + :command:`install` command invocation. + + ``destination`` + Optional member that is present for specific ``type`` values below. + The value is a string specifying the install destination path. + The path may be absolute or relative to the install prefix. + + ``paths`` + Optional member that is present for specific ``type`` values below. + The value is a JSON array of entries corresponding to the paths + (files or directories) to be installed. Each entry is one of: + + * A string specifying the path from which a file or directory + is to be installed. The portion of the path not preceded by + a ``/`` also specifies the path (name) to which the file + or directory is to be installed under the destination. + + * A JSON object with members: + + ``from`` + A string specifying the path from which a file or directory + is to be installed. + + ``to`` + A string specifying the path to which the file or directory + is to be installed under the destination. + + In both cases the paths are represented with forward slashes. If + the "from" path is inside the top-level directory documented by the + corresponding ``type`` value, then the path is specified relative + to that directory. Otherwise the path is absolute. + + ``type`` + A string specifying the type of installation rule. The value is one + of the following, with some variants providing additional members: + + ``file`` + An :command:`install(FILES)` or :command:`install(PROGRAMS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``directory`` + An :command:`install(DIRECTORY)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``target`` + An :command:`install(TARGETS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has additional members ``targetId``, ``targetIndex``, + ``targetIsImportLibrary``, and ``targetInstallNamelink``. + + ``export`` + An :command:`install(EXPORT)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``paths`` entries refer to files generated automatically by + CMake for installation, and their actual values are considered + private implementation details. + This type has additional members ``exportName`` and ``exportTargets``. + + ``script`` + An :command:`install(SCRIPT)` call. + This type has additional member ``scriptFile``. + + ``code`` + An :command:`install(CODE)` call. + This type has no additional members. + + ``isExcludeFromAll`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option. + + ``isOptional`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``OPTIONAL`` option. + This is allowed when ``type`` is ``file``, ``directory``, or ``target``. + + ``targetId`` + Optional member that is present when ``type`` is ``target``. + The value is a string uniquely identifying the target to be installed. + This matches the ``id`` member of the target in the main + "codemodel" object's ``targets`` array. + + ``targetIndex`` + Optional member that is present when ``type`` is ``target``. + The value is an unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target to be installed. + + ``targetIsImportLibrary`` + Optional member that is present when ``type`` is ``target`` and + the installer is for a Windows DLL import library file or for an + AIX linker import file. If present, it has boolean value ``true``. + + ``targetInstallNamelink`` + Optional member that is present when ``type`` is ``target`` and + the installer corresponds to a target that may use symbolic links + to implement the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` + target properties. + The value is a string indicating how the installer is supposed to + handle the symlinks: ``skip`` means the installer should skip the + symlinks and install only the real file, and ``only`` means the + installer should install only the symlinks and not the real file. + In all cases the ``paths`` member lists what it actually installs. + + ``exportName`` + Optional member that is present when ``type`` is ``export``. + The value is a string specifying the name of the export. + + ``exportTargets`` + Optional member that is present when ``type`` is ``export``. + The value is a JSON array of entries corresponding to the targets + included in the export. Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + ``scriptFile`` + Optional member that is present when ``type`` is ``script``. + The value is a string specifying the path to the script file on disk, + represented with forward slashes. If the file is inside the top-level + source directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` or other command invocation that added this + installer is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``backtraceGraph`` + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "directory" object. + "codemodel" version 2 "target" object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -964,40 +1149,48 @@ with members: with forward slashes. ``backtraceGraph`` - A JSON object describing the graph of backtraces whose nodes are - referenced from ``backtrace`` members elsewhere. The members are: - - ``nodes`` - A JSON array listing nodes in the backtrace graph. Each entry - is a JSON object with members: - - ``file`` - An unsigned integer 0-based index into the backtrace ``files`` array. - - ``line`` - An optional member present when the node represents a line within - the file. The value is an unsigned integer 1-based line number. - - ``command`` - An optional member present when the node represents a command - invocation within the file. The value is an unsigned integer - 0-based index into the backtrace ``commands`` array. - - ``parent`` - An optional member present when the node is not the bottom of - the call stack. The value is an unsigned integer 0-based index - of another entry in the backtrace ``nodes`` array. - - ``commands`` - A JSON array listing command names referenced by backtrace nodes. - Each entry is a string specifying a command name. - - ``files`` - A JSON array listing CMake language files referenced by backtrace nodes. - Each entry is a string specifying the path to a file, represented - with forward slashes. If the file is inside the top-level source - directory then the path is specified relative to that directory. - Otherwise the path is absolute. + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "target" object. + +"codemodel" version 2 "backtrace graph" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``backtraceGraph`` member of a `"codemodel" version 2 "directory" object`_, +or `"codemodel" version 2 "target" object`_ is a JSON object describing a +graph of backtraces. Its nodes are referenced from ``backtrace`` members +elsewhere in the containing object. The backtrace graph object members are: + +``nodes`` + A JSON array listing nodes in the backtrace graph. Each entry + is a JSON object with members: + + ``file`` + An unsigned integer 0-based index into the backtrace ``files`` array. + + ``line`` + An optional member present when the node represents a line within + the file. The value is an unsigned integer 1-based line number. + + ``command`` + An optional member present when the node represents a command + invocation within the file. The value is an unsigned integer + 0-based index into the backtrace ``commands`` array. + + ``parent`` + An optional member present when the node is not the bottom of + the call stack. The value is an unsigned integer 0-based index + of another entry in the backtrace ``nodes`` array. + +``commands`` + A JSON array listing command names referenced by backtrace nodes. + Each entry is a string specifying a command name. + +``files`` + A JSON array listing CMake language files referenced by backtrace nodes. + Each entry is a string specifying the path to a file, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. Object Kind "cache" ------------------- diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7bc490f..775067a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -940,6 +940,29 @@ which is just the string ``tgt``. :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. +.. genex:: $<TARGET_RUNTIME_DLLS:tgt> + + List of DLLs that the target depends on at runtime. This is determined by + the locations of all the ``SHARED`` and ``MODULE`` targets in the target's + transitive dependencies. Using this generator expression on targets other + than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + On non-DLL platforms, it evaluates to an empty string. + + This generator expression can be used to copy all of the DLLs that a target + depends on into its output directory in a ``POST_BUILD`` custom command. For + example: + + .. code-block:: cmake + + find_package(foo REQUIRED) + + add_executable(exe main.c) + target_link_libraries(exe PRIVATE foo::foo foo::bar) + add_custom_command(TARGET exe POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> + COMMAND_EXPAND_LISTS + ) + .. genex:: $<INSTALL_PREFIX> Content of the install prefix when the target is exported via diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 17c1a1e..141eeaa 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -185,6 +185,7 @@ They are normally called through the :command:`find_package` command. /module/FindMPEG /module/FindMPEG2 /module/FindMPI + /module/FindMsys /module/FindODBC /module/FindOpenACC /module/FindOpenAL diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index bd6b2f0..08449a7 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,17 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.21 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0124: foreach() loop variables are only available in the loop scope. </policy/CMP0124> + CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123> + CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122> + CMP0121: The list command detects invalid indicies. </policy/CMP0121> + Policies Introduced by CMake 3.20 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 467818d..3714004 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -39,7 +39,7 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1`` and ``2``. + The supported versions are ``1``, ``2``, and ``3``. ``cmakeMinimumRequired`` @@ -70,17 +70,17 @@ The root object recognizes the following fields: ``configurePresets`` An optional array of `Configure Preset`_ objects. - This is allowed in preset files specifying version 1 or above. + This is allowed in preset files specifying version ``1`` or above. ``buildPresets`` An optional array of `Build Preset`_ objects. - This is allowed in preset files specifying version 2 or above. + This is allowed in preset files specifying version ``2`` or above. ``testPresets`` An optional array of `Test Preset`_ objects. - This is allowed in preset files specifying version 2 or above. + This is allowed in preset files specifying version ``2`` or above. Configure Preset ^^^^^^^^^^^^^^^^ @@ -119,6 +119,11 @@ that may contain the following fields: This field can also be a string, which is equivalent to an array containing one string. +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -140,7 +145,9 @@ that may contain the following fields: An optional string representing the generator to use for the preset. If ``generator`` is not specified, it must be inherited from the - ``inherits`` preset (unless this preset is ``hidden``). + ``inherits`` preset (unless this preset is ``hidden``). In version ``3`` + or above, this field may be omitted to fall back to regular generator + discovery procedure. Note that for Visual Studio generators, unlike in the command line ``-G`` argument, you cannot include the platform name in the generator name. Use @@ -181,7 +188,15 @@ that may contain the following fields: This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the source directory. If ``binaryDir`` is not specified, it must be inherited from the ``inherits`` preset (unless this - preset is ``hidden``). + preset is ``hidden``). In version ``3`` or above, this field may be + omitted. + +``installDir`` + + An optional string representing the path to the installation directory. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the source directory. This is allowed in + preset files specifying version ``3`` or above. ``cmakeExecutable`` @@ -338,6 +353,11 @@ that may contain the following fields: This field can also be a string, which is equivalent to an array containing one string. +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -457,6 +477,11 @@ that may contain the following fields: This field can also be a string, which is equivalent to an array containing one string. +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -782,6 +807,103 @@ that may contain the following fields: Equivalent to passing ``--no-tests=ignore`` on the command line. +Condition +^^^^^^^^^ + +The ``condition`` field of a preset, allowed in preset files specifying version +``3`` or above, is used to determine whether or not the preset is enabled. For +example, this can be used to disable a preset on platforms other than Windows. +``condition`` may be either a boolean, ``null``, or an object. If it is a +boolean, the boolean indicates whether the preset is enabled or disabled. If it +is ``null``, the preset is enabled, but the ``null`` condition is not inherited +by any presets that may inherit from the preset. Sub-conditions (for example in +a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an +object, it has the following fields: + +``type`` + + A required string with one of the following values: + + ``"const"`` + + Indicates that the condition is constant. This is equivalent to using a + boolean in place of the object. The condition object will have the + following additional fields: + + ``value`` + + A required boolean which provides a constant value for the condition's + evaluation. + + ``"equals"`` + + ``"notEquals"`` + + Indicates that the condition compares two strings to see if they are equal + (or not equal). The condition object will have the following additional + fields: + + ``lhs`` + + First string to compare. This field supports macro expansion. + + ``rhs`` + + Second string to compare. This field supports macro expansion. + + ``"inList"`` + + ``"notInList"`` + + Indicates that the condition searches for a string in a list of strings. + The condition object will have the following additional fields: + + ``string`` + + A required string to search for. This field supports macro expansion. + + ``list`` + + A required list of strings to search. This field supports macro + expansion, and uses short-circuit evaluation. + + ``"matches"`` + + ``"notMatches"`` + + Indicates that the condition searches for a regular expression in a string. + The condition object will have the following additional fields: + + ``string`` + + A required string to search. This field supports macro expansion. + + ``regex`` + + A required regular expression to search for. This field supports macro + expansion. + + ``"anyOf"`` + + ``"allOf"`` + + Indicates that the condition is an aggregation of zero or more nested + conditions. The condition object will have the following additional fields: + + ``conditions`` + + A required array of condition objects. These conditions use short-circuit + evaluation. + + ``"not"`` + + Indicates that the condition is an inversion of another condition. The + condition object will have the following additional fields: + + ``condition`` + + A required condition object. + Macro Expansion ^^^^^^^^^^^^^^^ @@ -823,6 +945,12 @@ Recognized macros include: test presets, this will evaluate to the generator specified by ``configurePreset``. +``${hostSystemName}`` + + The name of the host operating system. Contains the same value as + :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files + specifying version ``3`` or above. + ``${dollar}`` A literal dollar sign (``$``). diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index af170da..4f2c1b0 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -21,6 +21,7 @@ Properties of Global Scope /prop_gbl/AUTOMOC_SOURCE_GROUP /prop_gbl/AUTOMOC_TARGETS_FOLDER /prop_gbl/AUTORCC_SOURCE_GROUP + /prop_gbl/AUTOUIC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES @@ -402,7 +403,9 @@ Properties on Targets /prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EMBED_type + /prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_type_PATH + /prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_GENERATE_SCHEME /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 1ededee..a941310 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -96,8 +96,8 @@ Cross Compiling =============== If :manual:`cmake(1)` is invoked with the command line parameter -``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set -values for the compilers. +``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the +file will be loaded early to set values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4317dd4..37ef053 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -130,6 +130,7 @@ Variables that Provide Information /variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_DESCRIPTION /variable/PROJECT-NAME_HOMEPAGE_URL + /variable/PROJECT-NAME_IS_TOP_LEVEL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -139,6 +140,7 @@ Variables that Provide Information /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION /variable/PROJECT_HOMEPAGE_URL + /variable/PROJECT_IS_TOP_LEVEL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 02828ac..f416f86 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -381,9 +381,9 @@ Options ``--preset <preset>``, ``--preset=<preset>`` Reads a :manual:`preset <cmake-presets(7)>` from ``<path-to-source>/CMakePresets.json`` and - ``<path-to-source>/CMakeUserPresets.json``. The preset specifies the - generator and the build directory, and optionally a list of variables and - other arguments to pass to CMake. The current working directory must contain + ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the + generator and the build directory, and a list of variables and other + arguments to pass to CMake. The current working directory must contain CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details on these files, see :manual:`cmake-presets(7)`. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 175359d..811997c 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -134,6 +134,12 @@ Options This option tells CTest to write all its output to a ``<file>`` log file. +``--output-junit <file>`` + Write test results in JUnit format. + + This option tells CTest to write test results to a ``<file>`` JUnit XML file. + If ``<file>`` already exists it will be overwritten. + ``-N,--show-only[=<format>]`` Disable actual execution of tests. @@ -155,7 +161,10 @@ Options Run tests with labels matching regular expression. This option tells CTest to run only the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-L`` option is given, + a test will only be run if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-R <regex>, --tests-regex <regex>`` Run tests matching regular expression. @@ -173,7 +182,10 @@ Options Exclude tests with labels matching regular expression. This option tells CTest to NOT run the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-LE`` option is given, + a test will only be excluded if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-FA <regex>, --fixture-exclude-any <regex>`` Exclude fixtures matching ``<regex>`` from automatically adding any tests to @@ -398,6 +410,46 @@ Specify the directory in which to look for tests. .. include:: OPTIONS_HELP.txt +.. _`Label Matching`: + +Label Matching +============== + +Tests may have labels attached to them. Tests may be included +or excluded from a test run by filtering on the labels. +Each individual filter is a regular expression applied to +the labels attached to a test. + +When ``-L`` is used, in order for a test to be included in a +test run, each regular expression must match at least one +label. Using more than one ``-L`` option means "match **all** +of these". + +The ``-LE`` option works just like ``-L``, but excludes tests +rather than including them. A test is excluded if each regular +expression matches at least one label. + +If a test has no labels attached to it, then ``-L`` will never +include that test, and ``-LE`` will never exclude that test. +As an example of tests with labels, consider five tests, +with the following labels: + +* *test1* has labels *tuesday* and *production* +* *test2* has labels *tuesday* and *test* +* *test3* has labels *wednesday* and *production* +* *test4* has label *wednesday* +* *test5* has labels *friday* and *test* + +Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has +both labels. Running CTest with ``-L test`` will select *test2* and +*test5*, because both of them have a label that matches that regular +expression. + +Because the matching works with regular expressions, take note that +running CTest with ``-L es`` will match all five tests. +To select the *tuesday* and *wednesday* tests together, use a single +regular expression that matches either of them, like ``-L "tue|wed"``. + .. _`Label and Subproject Summary`: Label and Subproject Summary @@ -1043,6 +1095,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` +To report extra test values to CDash, see :ref:`Additional Test Measurements`. + .. _`CTest Coverage Step`: CTest Coverage Step @@ -1619,4 +1673,4 @@ See Also .. include:: LINKS.txt -.. _`CDash`: http://cdash.org/ +_`CDash`: https://cdash.org diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index dfc2910..346f342 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,5 +1,5 @@ { - "version": 2, + "version": 3, "cmakeMinimumRequired": { "major": 3, "minor": 20, @@ -35,6 +35,17 @@ "displayName": "Ninja Multi-Config", "description": "Default build using Ninja Multi-Config generator", "generator": "Ninja Multi-Config" + }, + { + "name": "windows-only", + "inherits": "default", + "displayName": "Windows-only configuration", + "description": "This build is only available on Windows", + "condition": { + "type": "equals", + "lhs": "${hostSystemName}", + "rhs": "Windows" + } } ], "buildPresets": [ diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index f8faf3d..a69d270 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -11,7 +11,7 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"} }, "additionalProperties": false }, @@ -23,9 +23,23 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"}, - "buildPresets": { "$ref": "#/definitions/buildPresets"}, - "testPresets": { "$ref": "#/definitions/testPresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV2"}, + "testPresets": { "$ref": "#/definitions/testPresetsV2"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 3, + "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/buildPresetsV3"}, + "testPresets": { "$ref": "#/definitions/testPresetsV3"} }, "additionalProperties": false } @@ -58,7 +72,30 @@ "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, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", "properties": {} }, - "configurePresets": { + "configurePresetsItemsV3": { + "type": "array", + "description": "A configure preset object.", + "items": { + "type": "object", + "description": "A configure preset object.", + "properties": { + "binaryDir": { + "type": "string", + "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, the path is calculated using regular methods." + }, + "generator": { + "type": "string", + "description": "An optional string representing the generator to use for the preset. If generator is not specified, the normal generator discovery procedure is used. Note that for Visual Studio generators, unlike in the command line -G argument, you cannot include the platform name in the generator name. Use the architecture field instead." + }, + "installDir": { + "type": "string", + "description": "An optional string representing the path to the installation directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory." + }, + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "configurePresetsItemsV1": { "type": "array", "description": "An optional array of configure preset objects.", "items": { @@ -302,6 +339,67 @@ }, "additionalProperties": false } + } + } + }, + "configurePresetsV3": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsItemsV3" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "binaryDir": {}, + "installDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "configurePresetsV1": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "binaryDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {} }, "required": [ "name" @@ -309,7 +407,17 @@ "additionalProperties": false } }, - "buildPresets": { + "buildPresetsItemsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "buildPresetsItemsV2": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "items": { @@ -427,11 +535,84 @@ }, "required": [ "name" + ] + } + }, + "buildPresetsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsV2": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {} + }, + "required": [ + "name" ], "additionalProperties": false } }, - "testPresets": { + "testPresetsItemsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "testPresetsItemsV2": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "items": { @@ -743,9 +924,312 @@ }, "required": [ "name" + ] + } + }, + "testPresetsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "testPresetsV2": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {} + }, + "required": [ + "name" ], "additionalProperties": false } + }, + "condition": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean which provides a constant value for the condition's evaluation." + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "const" + }, + "value": { + "type": "boolean", + "description": "A required boolean which provides a constant value for the condition's evaluation." + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "equals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notEquals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "inList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notInList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "matches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notMatches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "anyOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "allOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "not" + }, + "condition": { "$ref": "#/definitions/condition" } + }, + "required": [ + "type", + "condition" + ], + "additionalProperties": false + } + ] + }, + "topCondition": { + "anyOf": [ + { "$ref": "#/definitions/condition" }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] } } } diff --git a/Help/module/FindMsys.rst b/Help/module/FindMsys.rst new file mode 100644 index 0000000..fc5495c --- /dev/null +++ b/Help/module/FindMsys.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMsys.cmake diff --git a/Help/policy/CMP0104.rst b/Help/policy/CMP0104.rst index 7c7a16e..b125729 100644 --- a/Help/policy/CMP0104.rst +++ b/Help/policy/CMP0104.rst @@ -41,7 +41,7 @@ Examples .. code-block:: cmake - set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72) + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") Generates code for real and virtual architectures ``30``, ``50`` and ``72``. diff --git a/Help/policy/CMP0121.rst b/Help/policy/CMP0121.rst new file mode 100644 index 0000000..5ef2856 --- /dev/null +++ b/Help/policy/CMP0121.rst @@ -0,0 +1,21 @@ +CMP0121 +------- + +.. versionadded:: 3.21 + +The :command:`list` command now detects invalid indicies. + +Prior to CMake version 3.21, the :command:`list` command's ``GET``, +``INSERT``, ``SUBLIST``, and ``REMOVE_AT`` subcommands did not detect invalid +index arguments. + +The ``OLD`` behavior of this policy is for invalid indicies to be treated as +their integer value (if any) at the start of the string. For example, +``2good4you`` is a ``2`` and ``not_an_integer`` is a ``0``. The ``NEW`` +behavior is for invalid indicies to trigger an error. + +This policy was introduced in CMake version 3.21. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0122.rst b/Help/policy/CMP0122.rst new file mode 100644 index 0000000..1ff8c48 --- /dev/null +++ b/Help/policy/CMP0122.rst @@ -0,0 +1,17 @@ +CMP0122 +------- + +.. versionadded:: 3.21 + +:module:`UseSWIG` use library name conventions for ``CSharp`` language. + +Starting with CMake 3.21, :module:`UseSWIG` generates now a library using +default naming conventions. This policy provides compatibility with projects +that expect the legacy behavior. + +This policy was introduced in CMake version 3.21. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0123.rst b/Help/policy/CMP0123.rst new file mode 100644 index 0000000..e09b5ec --- /dev/null +++ b/Help/policy/CMP0123.rst @@ -0,0 +1,32 @@ +CMP0123 +------- + +.. versionadded:: 3.21 + +``ARMClang`` cpu/arch compile and link flags must be set explicitly. + +CMake 3.20 and lower automatically maps the :variable:`CMAKE_SYSTEM_PROCESSOR` +variable and an undocumented ``CMAKE_SYSTEM_ARCH`` to compile and link options +for ``ARMClang``. For example, the ``-mcpu=cortex-m33`` flag is added when +:variable:`CMAKE_SYSTEM_PROCESSOR` equals ``cortex-m33``. CMake requires +projects to set either variable or it raises a fatal error. However, the +project may need to additionally specify CPU features using e.g. +``-mcpu=cortex-m33+nodsp``, conflicting with the ``-mcpu=cortex-m33`` added +by CMake. This results in either link errors or unusable binaries. + +CMake 3.21 and above prefer instead to not add any cpu/arch compile and link +flags automatically. Instead, projects must specify them explicitly. +This policy provides compatibility for projects that have not been updated. + +The ``OLD`` behavior of this policy requires projects that use ``ARMClang`` +to set either :variable:`CMAKE_SYSTEM_PROCESSOR` or ``CMAKE_SYSTEM_ARCH`` +and it automatically adds a compile option ``-mcpu=`` or ``-march=`` and +a link option ``--cpu=`` based on those variables. The ``NEW`` behavior +does not add compile or link options, and projects are responsible for +setting correct options. + +This policy was introduced in CMake version 3.21. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0124.rst b/Help/policy/CMP0124.rst new file mode 100644 index 0000000..88d03e3 --- /dev/null +++ b/Help/policy/CMP0124.rst @@ -0,0 +1,20 @@ +CMP0124 +------- + +.. versionadded:: 3.21 + +The loop variables created by :command:`foreach` command have now their scope +restricted to the loop scope. + +Starting with CMake 3.21, the :command:`foreach` command ensures that the loop +variables have their scope restricted to the loop scope. + +The ``OLD`` behavior for this policy let the loop variables to exist, with an +empty value, in the outer scope of loop scope. + +This policy was introduced in CMake version 3.21. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst index 2e32320..07c732b 100644 --- a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst +++ b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst @@ -3,15 +3,16 @@ AUTOGEN_SOURCE_GROUP .. versionadded:: 3.9 -Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` and -:prop_tgt:`AUTORCC` generated files. +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` generated files. -Files generated by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` are not always -known at configure time and therefore can't be passed to -:command:`source_group`. -:prop_gbl:`AUTOGEN_SOURCE_GROUP` an be used instead to generate or select -a source group for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` generated files. +Files generated by :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` are not always known at configure time and therefore can't +be passed to :command:`source_group`. +:prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used instead to generate or select +a source group for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` generated files. -For :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` specific overrides see -:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` -respectively. +For :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` specific +overrides see :prop_gbl:`AUTOMOC_SOURCE_GROUP`, :prop_gbl:`AUTORCC_SOURCE_GROUP` +and :prop_gbl:`AUTOUIC_SOURCE_GROUP` respectively. diff --git a/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst new file mode 100644 index 0000000..79ebfe0 --- /dev/null +++ b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst @@ -0,0 +1,9 @@ +AUTOUIC_SOURCE_GROUP +-------------------- + +.. versionadded:: 3.21 + +Name of the :command:`source_group` for :prop_tgt:`AUTOUIC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTOUIC`. diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 7166381..2bd0feb 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -24,6 +24,12 @@ The features known to this version of CMake are: ``c_std_11`` Compiler mode is at least C 11. +``c_std_17`` + Compiler mode is at least C 17. + +``c_std_23`` + Compiler mode is at least C 23. + ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst index 6ef4580..216dfe8 100644 --- a/Help/prop_sf/GENERATED.rst +++ b/Help/prop_sf/GENERATED.rst @@ -32,9 +32,10 @@ The :ref:`Makefile Generators` will remove ``GENERATED`` files during ``make clean``. Generated sources may be hidden in some IDE tools, while in others they might -be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` -or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`, -:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target +be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTORCC` or :prop_tgt:`AUTOUIC` functionality, the +:prop_gbl:`AUTOGEN_SOURCE_GROUP`, :prop_gbl:`AUTOMOC_SOURCE_GROUP`, +:prop_gbl:`AUTORCC_SOURCE_GROUP` and :prop_gbl:`AUTOUIC_SOURCE_GROUP` target properties may influence where the generated sources are grouped in the project's file lists. diff --git a/Help/prop_tgt/CUDA_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst index d56b769..a3191e8 100644 --- a/Help/prop_tgt/CUDA_ARCHITECTURES.rst +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -25,7 +25,7 @@ Examples .. code-block:: cmake - set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72) + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") Generates code for real and virtual architectures ``30``, ``50`` and ``72``. diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 3f0d242..e22b775 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -11,7 +11,7 @@ flag such as ``-std=gnu11`` to the compile line. For compilers that have no notion of a C standard level, such as Microsoft Visual C++ before VS 16.7, this property has no effect. -Supported values are ``90``, ``99`` and ``11``. +Supported values are ``90``, ``99``, ``11``, ``17``, ``23``. 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 diff --git a/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst index 5c6778d..dc2dc9e 100644 --- a/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst +++ b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst @@ -10,5 +10,6 @@ to re-link this target. Logical target-level dependencies will not be affected so the linked shared libraries will still be brought up to date before this target is built. -This property is initialized by the value of the variable -CMAKE_LINK_DEPENDS_NO_SHARED if it is set when a target is created. +This property is initialized by the value of the +:variable:`CMAKE_LINK_DEPENDS_NO_SHARED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst index 7b68126..2a4d666 100644 --- a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst @@ -6,3 +6,8 @@ XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY Tell the :generator:`Xcode` generator to perform code signing for all the frameworks and libraries that are embedded using the :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property. + +.. versionadded:: 3.21 + +This property was generalized to other types of embedded items. See +:prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY` for the more general form. diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst index 29f8c5c..04daa85 100644 --- a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst @@ -6,3 +6,9 @@ XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY Tell the :generator:`Xcode` generator to remove headers from all the frameworks that are embedded using the :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property. + +.. versionadded:: 3.21 + +This property was generalized to other types of embedded items. See +:prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` for the more +general form. diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst index 90c5bc7..a1af56f 100644 --- a/Help/prop_tgt/XCODE_EMBED_type.rst +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -5,10 +5,20 @@ XCODE_EMBED_<type> Tell the :generator:`Xcode` generator to embed the specified list of items into the target bundle. ``<type>`` specifies the embed build phase to use. +See the Xcode documentation for the base location of each ``<type>``. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + The specified items will be added to the ``Embed Frameworks`` build phase. + The items can be CMake target names or paths to frameworks or libraries. + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + + The specified items will be added to the ``Embed App Extensions`` build phase. + They must be CMake target names. -Currently, the only supported value for ``<type>`` is ``FRAMEWORKS``. -The specified items will be added to the ``Embed Frameworks`` build phase. -The items can be CMake target names or paths to frameworks or libraries. See also :prop_tgt:`XCODE_EMBED_<type>_PATH`, -:prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` and -:prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`. +:prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` and +:prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`. diff --git a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst new file mode 100644 index 0000000..7ec0385 --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst @@ -0,0 +1,18 @@ +XCODE_EMBED_<type>_CODE_SIGN_ON_COPY +------------------------------------ + +.. versionadded:: 3.20 + +Boolean property used only by the :generator:`Xcode` generator. It specifies +whether to perform code signing for the items that are embedded using the +:prop_tgt:`XCODE_EMBED_<type>` property. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + +If a ``XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`` property is not defined on the +target, no code signing on copy will be performed for that ``<type>``. diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst index 887cf57..a6f980d 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -3,7 +3,16 @@ XCODE_EMBED_<type>_PATH .. versionadded:: 3.20 -Tell the :generator:`Xcode` generator the relative path to use when embedding -the items specified by :prop_tgt:`XCODE_EMBED_<type>`. The path is relative +This property is used only by the :generator:`Xcode` generator. When defined, +it specifies the relative path to use when embedding the items specified by +:prop_tgt:`XCODE_EMBED_<type>`. The path is relative to the base location of the ``Embed XXX`` build phase associated with +``<type>``. See the Xcode documentation for the base location of each ``<type>``. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 diff --git a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst new file mode 100644 index 0000000..75c8eae --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst @@ -0,0 +1,20 @@ +XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY +----------------------------------------- + +.. versionadded:: 3.20 + +Boolean property used only by the :generator:`Xcode` generator. It specifies +whether to remove headers from all the frameworks that are embedded using the +:prop_tgt:`XCODE_EMBED_<type>` property. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + If the ``XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY`` property is not + defined, headers will not be removed on copy by default. + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + + If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not + defined, headers WILL be removed on copy by default. 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/ARMClang-cpu-arch-flags.rst b/Help/release/dev/ARMClang-cpu-arch-flags.rst new file mode 100644 index 0000000..5e885fe --- /dev/null +++ b/Help/release/dev/ARMClang-cpu-arch-flags.rst @@ -0,0 +1,7 @@ +ARMClang-cpu-arch-flags +----------------------- + +* ``ARMClang`` cpu/arch compile and link flags are no longer added + automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR` + variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable. + They must be specified explicitly. See policy :policy:`CMP0123`. diff --git a/Help/release/dev/FindDevIL-imported-targets.rst b/Help/release/dev/FindDevIL-imported-targets.rst new file mode 100644 index 0000000..aa0929e --- /dev/null +++ b/Help/release/dev/FindDevIL-imported-targets.rst @@ -0,0 +1,4 @@ +FindDevIL +--------- + +* The :module:`FindDevIL` module now provides imported targets. diff --git a/Help/release/dev/FindIconv-version.rst b/Help/release/dev/FindIconv-version.rst new file mode 100644 index 0000000..3546d86 --- /dev/null +++ b/Help/release/dev/FindIconv-version.rst @@ -0,0 +1,4 @@ +FindIconv-version +----------------- + +* The :module:`FindIconv` module now has version support. diff --git a/Help/release/dev/FindIntl-version.rst b/Help/release/dev/FindIntl-version.rst new file mode 100644 index 0000000..5365cf1 --- /dev/null +++ b/Help/release/dev/FindIntl-version.rst @@ -0,0 +1,4 @@ +FindIntl-version +---------------- + +* The :module:`FindIntl` module now has version support. diff --git a/Help/release/dev/FindMsys.rst b/Help/release/dev/FindMsys.rst new file mode 100644 index 0000000..d237c4e --- /dev/null +++ b/Help/release/dev/FindMsys.rst @@ -0,0 +1,6 @@ +FindMsys +-------- + +* The :module:`FindMsys` module was added to find MSYS installations. + Like :module:`FindCygwin`, it is used automatically by some other + find modules to locate UNIX-style tools on Windows. diff --git a/Help/release/dev/UseSWIG-csharp.rst b/Help/release/dev/UseSWIG-csharp.rst new file mode 100644 index 0000000..dbbeaf1 --- /dev/null +++ b/Help/release/dev/UseSWIG-csharp.rst @@ -0,0 +1,5 @@ +UseSWIG-csharp +-------------- + +* The :module:`UseSWIG` module use now standard library name conventions for + ``CSharp`` language. See policy :policy:`CMP0122`. diff --git a/Help/release/dev/UseSWIG-dependencies.rst b/Help/release/dev/UseSWIG-dependencies.rst new file mode 100644 index 0000000..b5a38c3 --- /dev/null +++ b/Help/release/dev/UseSWIG-dependencies.rst @@ -0,0 +1,6 @@ +UseSWIG-dependencies +-------------------- + +* :module:`UseSWIG` module gained the capability, for + :generator:`Xcode` generator, to use `swig` tool to generate implicit + dependencies. diff --git a/Help/release/dev/Xcode-add_custom_command-DEPFILE.rst b/Help/release/dev/Xcode-add_custom_command-DEPFILE.rst new file mode 100644 index 0000000..4c4d48c --- /dev/null +++ b/Help/release/dev/Xcode-add_custom_command-DEPFILE.rst @@ -0,0 +1,5 @@ +Xcode-add_custom_command-DEPFILE +-------------------------------- + +* The :command:`add_custom_command` command gained ``DEPFILE`` support on + :generator:`Xcode` generator. diff --git a/Help/release/dev/add_custom_command-DEPFILE-genex.rst b/Help/release/dev/add_custom_command-DEPFILE-genex.rst new file mode 100644 index 0000000..52e5e9f --- /dev/null +++ b/Help/release/dev/add_custom_command-DEPFILE-genex.rst @@ -0,0 +1,5 @@ +add_custom_command-DEPFILE-genex +-------------------------------- + +* The :command:`add_custom_command` command ``DEPFILE`` option learned to + support :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/c-std.rst b/Help/release/dev/c-std.rst new file mode 100644 index 0000000..44daa85 --- /dev/null +++ b/Help/release/dev/c-std.rst @@ -0,0 +1,6 @@ +c-std +----- + +* :prop_tgt:`C_STANDARD` and the + :manual:`Compile Features <cmake-compile-features(7)>` functionality gained + support for C17 and C23. diff --git a/Help/release/dev/cmake-install-prefix-command.rst b/Help/release/dev/cmake-install-prefix-command.rst new file mode 100644 index 0000000..2de5d91 --- /dev/null +++ b/Help/release/dev/cmake-install-prefix-command.rst @@ -0,0 +1,8 @@ +cmake-install-prefix-command +---------------------------- + +* The :manual:`cmake(1)` command gained the ``--install-prefix <dir>`` + command line option to specify the location of the install prefix. + +* :manual:`cmake-presets(7)` configure preset gained support for specifying + the install prefix. diff --git a/Help/release/dev/cmake-presets-condition.rst b/Help/release/dev/cmake-presets-condition.rst new file mode 100644 index 0000000..aa01bc1 --- /dev/null +++ b/Help/release/dev/cmake-presets-condition.rst @@ -0,0 +1,4 @@ +cmake-presets-condition +----------------------- + +* :manual:`cmake-presets(7)` now support conditional enabling of presets. diff --git a/Help/release/dev/cmake-presets-host-system-name.rst b/Help/release/dev/cmake-presets-host-system-name.rst new file mode 100644 index 0000000..8036939 --- /dev/null +++ b/Help/release/dev/cmake-presets-host-system-name.rst @@ -0,0 +1,5 @@ +cmake-presets-host-system-name +------------------------------ + +* :manual:`cmake-presets(7)` gained support for a new ``${hostSystemName}`` + macro. diff --git a/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst b/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst new file mode 100644 index 0000000..7973489 --- /dev/null +++ b/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst @@ -0,0 +1,5 @@ +cmake-presets-optional-generator-and-binarydir +---------------------------------------------- + +* :manual:`cmake-presets(7)` now support omitting the ``generator`` and + ``binaryDir`` fields. diff --git a/Help/release/dev/cmake-system-name-version.rst b/Help/release/dev/cmake-system-name-version.rst new file mode 100644 index 0000000..9cfe401 --- /dev/null +++ b/Help/release/dev/cmake-system-name-version.rst @@ -0,0 +1,10 @@ +cmake-system-name-version +------------------------- + +* :variable:`CMAKE_HOST_SYSTEM_NAME`'s undocumented version-stripping behavior + has been moved earlier, before :command:`project` or + :command:`enable_language` is called. +* :variable:`CMAKE_SYSTEM_NAME`'s undocumented version-stripping behavior has + been removed entirely. If it is set by a ``-D`` flag or by a + :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered, even if + it still contains a version number. diff --git a/Help/release/dev/cmake-toolchain-command.rst b/Help/release/dev/cmake-toolchain-command.rst new file mode 100644 index 0000000..111ca49 --- /dev/null +++ b/Help/release/dev/cmake-toolchain-command.rst @@ -0,0 +1,5 @@ +cmake-toolchain-command +---------------------------- + +* The :manual:`cmake(1)` command gained the ``--toolchain <path/to/file>`` + command line option to specify a toolchain file. diff --git a/Help/release/dev/cpack-dmg-filesystem.rst b/Help/release/dev/cpack-dmg-filesystem.rst new file mode 100644 index 0000000..e2a4742 --- /dev/null +++ b/Help/release/dev/cpack-dmg-filesystem.rst @@ -0,0 +1,5 @@ +cpack-dmg-filesystem +-------------------- + +* The :cpack_gen:`CPack DragNDrop Generator` gained option + :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem. diff --git a/Help/release/dev/cpack-nsis-executable-name.rst b/Help/release/dev/cpack-nsis-executable-name.rst new file mode 100644 index 0000000..a3818db --- /dev/null +++ b/Help/release/dev/cpack-nsis-executable-name.rst @@ -0,0 +1,6 @@ +cpack-nsis-executable-name +-------------------------- + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_EXECUTABLE` to specify the makensis + executable to use instead of the default one. diff --git a/Help/release/dev/ctest-output-junit.rst b/Help/release/dev/ctest-output-junit.rst new file mode 100644 index 0000000..66df19d --- /dev/null +++ b/Help/release/dev/ctest-output-junit.rst @@ -0,0 +1,5 @@ +ctest-output-junit +------------------ + +* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results + to a JUnit XML file. diff --git a/Help/release/dev/cxx-module-extensions.rst b/Help/release/dev/cxx-module-extensions.rst new file mode 100644 index 0000000..b9d0a8a --- /dev/null +++ b/Help/release/dev/cxx-module-extensions.rst @@ -0,0 +1,4 @@ +cxx-module-extensions +--------------------- + +* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++. diff --git a/Help/release/dev/file-COPY_FILE.rst b/Help/release/dev/file-COPY_FILE.rst new file mode 100644 index 0000000..2f0cdf0 --- /dev/null +++ b/Help/release/dev/file-COPY_FILE.rst @@ -0,0 +1,4 @@ +file-COPY_ONLY +-------------- + +* The :command:`file(COPY_FILE)` command was added to copy a file to another. diff --git a/Help/release/dev/file-REAL_PATH-EXPAND_TILDE.rst b/Help/release/dev/file-REAL_PATH-EXPAND_TILDE.rst new file mode 100644 index 0000000..cdf1efa --- /dev/null +++ b/Help/release/dev/file-REAL_PATH-EXPAND_TILDE.rst @@ -0,0 +1,5 @@ +file-REAL_PATH-EXPAND_TILDE +--------------------------- + +* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to + replace any leading tilde with the path to the user's home directory. diff --git a/Help/release/dev/file-RENAME.rst b/Help/release/dev/file-RENAME.rst new file mode 100644 index 0000000..6c1314d --- /dev/null +++ b/Help/release/dev/file-RENAME.rst @@ -0,0 +1,6 @@ +file-RENAME +----------- + +* The :command:`file(RENAME)` command learned to optionally capture + failure in a result variable. It also gained a ``NO_REPLACE`` + option to fail if the destination exists. diff --git a/Help/release/dev/fileapi-codemodel-directory.rst b/Help/release/dev/fileapi-codemodel-directory.rst new file mode 100644 index 0000000..f6515fd --- /dev/null +++ b/Help/release/dev/fileapi-codemodel-directory.rst @@ -0,0 +1,10 @@ +fileapi-codemodel-directory +--------------------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + component been updated to 2.3. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a + new "directory" object containing directory-level information. + This includes a list of installers generated by the :command:`install` + command. diff --git a/Help/release/dev/foreach-variable-scope.rst b/Help/release/dev/foreach-variable-scope.rst new file mode 100644 index 0000000..29a57bb --- /dev/null +++ b/Help/release/dev/foreach-variable-scope.rst @@ -0,0 +1,5 @@ +foreach-variable-scope +---------------------- + +* The :command:`foreach` command restrict loop variables to the loop scope. + See policy :policy:`CMP0124` for details. diff --git a/Help/release/dev/fujitsu-compiler-support.rst b/Help/release/dev/fujitsu-compiler-support.rst new file mode 100644 index 0000000..c6f8cfb --- /dev/null +++ b/Help/release/dev/fujitsu-compiler-support.rst @@ -0,0 +1,11 @@ +fujitsu-compiler-support +------------------------ + +* Addition of the ``Fujitsu`` compiler ID operating in traditional ``Trad`` + mode and ``FujitsuClang`` operating in ``Clang`` mode. +* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and + ``FujitsuClang``. +* The :module:`FindMPI` module learned to support ``Fujitsu`` and + ``FujitsuClang`` in both host and cross compiling modes. +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + the serial ``Fujitsu SSL2`` and parallel ``Fujitsu SSL2BLAMP`` libraries. diff --git a/Help/release/dev/ifw-default-version-operator.rst b/Help/release/dev/ifw-default-version-operator.rst new file mode 100644 index 0000000..4aeace2 --- /dev/null +++ b/Help/release/dev/ifw-default-version-operator.rst @@ -0,0 +1,7 @@ +ifw-default-version-operator +---------------------------- + +* Names given as ``DEPENDS`` or ``DEPENDENCIES`` arguments to + :command:`cpack_ifw_configure_component` or + :command:`cpack_ifw_configure_component_group` may now contain hyphens. + This requires QtIFW 3.1 or later. diff --git a/Help/release/dev/list-index-arg-parsing.rst b/Help/release/dev/list-index-arg-parsing.rst new file mode 100644 index 0000000..2ea525b --- /dev/null +++ b/Help/release/dev/list-index-arg-parsing.rst @@ -0,0 +1,7 @@ +list-index-arg-parsing +---------------------- + +* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and + ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values + are given as any of their index arguments based on the setting of policy + :policy:`CMP0121`. diff --git a/Help/release/dev/lzma-threads.rst b/Help/release/dev/lzma-threads.rst new file mode 100644 index 0000000..a481cfa --- /dev/null +++ b/Help/release/dev/lzma-threads.rst @@ -0,0 +1,7 @@ +lzma-threads +------------ + +* The precompiled binaries provided on + `cmake.org <https://cmake.org/download/>`_ now support + ``liblzma`` multi-threading. See the :variable:`CPACK_THREADS` and + :variable:`CPACK_ARCHIVE_THREADS` variables. diff --git a/Help/release/dev/msys.rst b/Help/release/dev/msys.rst new file mode 100644 index 0000000..ece5de7 --- /dev/null +++ b/Help/release/dev/msys.rst @@ -0,0 +1,4 @@ +msys +---- + +* CMake now supports the MSYS runtime environment, much like CYGWIN. diff --git a/Help/release/dev/project-is-top-level.rst b/Help/release/dev/project-is-top-level.rst new file mode 100644 index 0000000..568afe0 --- /dev/null +++ b/Help/release/dev/project-is-top-level.rst @@ -0,0 +1,6 @@ +project-is-top-level +-------------------- + +* :command:`project` now sets variables :variable:`PROJECT_IS_TOP_LEVEL` and + :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` to indicate whether it was called + in a top level ``CMakeLists.txt`` file. diff --git a/Help/release/dev/runtime-dll-deps.rst b/Help/release/dev/runtime-dll-deps.rst new file mode 100644 index 0000000..831410f --- /dev/null +++ b/Help/release/dev/runtime-dll-deps.rst @@ -0,0 +1,4 @@ +runtime-dll-deps +---------------- + +* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added. diff --git a/Help/release/dev/xcode_app_extensions.rst b/Help/release/dev/xcode_app_extensions.rst new file mode 100644 index 0000000..7be7d82 --- /dev/null +++ b/Help/release/dev/xcode_app_extensions.rst @@ -0,0 +1,11 @@ +xcode_app_extensions +-------------------- + +* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property + was added to tell the :generator:`Xcode` generator to embed app extensions + such as iMessage sticker packs. + Aspects of the embedding can be customized with the + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`, + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>` + properties. diff --git a/Help/release/index.rst b/Help/release/index.rst index 95b41fb..5dfca05 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_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index d5fcb7d..9817b1a 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -23,3 +23,7 @@ is read-only and changes to it are undefined behavior. :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``, it does not make sense to set ``CMAKE_CUDA_HOST_COMPILER`` without also setting ``CMAKE_CUDA_COMPILER`` to NVCC. + +.. note:: + + Ignored when using :ref:`Visual Studio Generators`. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 53ad2f3..45f2d32 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -63,3 +63,27 @@ Supported pairs are: Specify an alternative ``VCTargetsPath`` value for Visual Studio project files. This allows use of VS platform extension configuration files (``.props`` and ``.targets``) that are not installed with VS. + +Visual Studio Toolset Customization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**These are unstable interfaces with no compatibility guarantees** +because they hook into undocumented internal CMake implementation details. +Institutions may use these to internally maintain support for non-public +Visual Studio platforms and toolsets, but must accept responsibility to +make updates as changes are made to CMake. + +Additional ``key=value`` pairs are available: + +``customFlagTableDir=<path>`` + .. versionadded:: 3.21 + + Specify the absolute path to a directory from which to load custom + flag tables stored as JSON documents with file names of the form + ``<platform>_<toolset>_<tool>.json`` or ``<platform>_<tool>.json``, + where ``<platform>`` is the :variable:`CMAKE_VS_PLATFORM_NAME`, + ``<toolset>`` is the :variable:`CMAKE_VS_PLATFORM_TOOLSET`, + and ``<tool>`` is the tool for which the flag table is meant. + **This naming pattern is an internal CMake implementation detail.** + The ``<tool>`` names are undocumented. The format of the ``.json`` + flag table files is undocumented. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 89d9e27..0abedde 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -19,6 +19,8 @@ include: Cray = Cray Compiler (cray.com) Embarcadero, Borland = Embarcadero (embarcadero.com) Flang = Flang LLVM Fortran Compiler + Fujitsu = Fujitsu HPC compiler (Trad mode) + FujitsuClang = Fujitsu HPC compiler (Clang mode) G95 = G95 Fortran (g95.org) GNU = GNU Compiler Collection (gcc.gnu.org) GHS = Green Hills Software (www.ghs.com) diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst index 14b2694..11864f8 100644 --- a/Help/variable/CMAKE_LANG_FLAGS.rst +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -15,3 +15,6 @@ This is initialized for each language from environment variables: Initialized by the :envvar:`CUDAFLAGS` environment variable. * ``CMAKE_Fortran_FLAGS``: Initialized by the :envvar:`FFLAGS` environment variable. + +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst index 67ff2cb..ca13a29 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -12,6 +12,8 @@ the contents of a ``xxxFLAGS`` environment variable will be prepended, where ``xxx`` will be language-specific but not necessarily the same as ``<LANG>`` (e.g. :envvar:`CXXFLAGS` for ``CXX``, :envvar:`FFLAGS` for ``Fortran``, and so on). +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. See also the configuration-specific :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst index 168ee74..e462c5e 100644 --- a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -7,3 +7,6 @@ This variable is specified on the command line when cross-compiling with CMake. It is the path to a file which is read early in the CMake run and which specifies locations for compilers and toolchain utilities, and other target platform and compiler related information. + +Relative paths are allowed and are interpreted first as relative to the +build directory, and if not found, relative to the source directory. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst index 74db6b1..a19e7e1 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -9,10 +9,9 @@ The :ref:`Visual Studio Generators` for VS 2010 and above support using a standalone (non-installed) NVIDIA CUDA toolkit. The path may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of the form ``cuda=C:\path\to\cuda``. The given directory must at least -contain a folder ``.\nvcc`` and must provide Visual Studio integration -files in path ``.\CUDAVisualStudioIntegration\extras\ -visual_studio_integration\MSBuildExtensions\``. One can create a standalone -CUDA toolkit directory by either opening a installer with 7zip or -copying the files that are extracted by the running installer. -The value may be empty if no path to a standalone CUDA Toolkit was -specified. +contain the nvcc compiler in path ``.\bin`` and must provide Visual Studio +integration files in path ``.\extras\visual_studio_integration\ +MSBuildExtensions\``. One can create a standalone CUDA toolkit directory by +either opening a installer with 7zip or copying the files that are extracted +by the running installer. The value may be empty if no path to a standalone +CUDA Toolkit was specified. diff --git a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..953e978 --- /dev/null +++ b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst @@ -0,0 +1,11 @@ +<PROJECT-NAME>_IS_TOP_LEVEL +--------------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the named project was called in a top +level ``CMakeLists.txt`` file. + +To obtain the value from the most recent call to :command:`project` in +the current directory scope or above, see the +:variable:`PROJECT_IS_TOP_LEVEL` variable. diff --git a/Help/variable/PROJECT_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..e5eb6c1 --- /dev/null +++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst @@ -0,0 +1,21 @@ +PROJECT_IS_TOP_LEVEL +-------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether :command:`project` was called in a top +level ``CMakeLists.txt`` file. + +Some modules should only be included as part of the top level +``CMakeLists.txt`` file to not cause unintended side effects in the build +tree, and this variable can be used to conditionally execute such code. For +example, consider the :module:`CTest` module, which creates targets and +options: + +.. code-block:: cmake + + project(MyProject) + ... + if(PROJECT_IS_TOP_LEVEL) + include(CTest) + endif() |