diff options
Diffstat (limited to 'Help')
124 files changed, 2012 insertions, 586 deletions
diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 2b902a915..998e14674 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -13,46 +13,236 @@ queried. The list of queried values is stored in ``<variable>``. ``<key>`` can be one of the following values: -============================= ================================================ -Key Description -============================= ================================================ -``NUMBER_OF_LOGICAL_CORES`` Number of logical cores -``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores -``HOSTNAME`` Hostname -``FQDN`` Fully qualified domain name -``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in MiB [#mebibytes]_ -``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in MiB [#mebibytes]_ -``TOTAL_PHYSICAL_MEMORY`` Total physical memory in MiB [#mebibytes]_ -``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in MiB [#mebibytes]_ -============================= ================================================ - -.. versionadded:: 3.10 - Additional ``<key>`` values are available: - -============================= ================================================ -Key Description -============================= ================================================ -``IS_64BIT`` One if processor is 64Bit -``HAS_FPU`` One if processor has floating point unit -``HAS_MMX`` One if processor supports MMX instructions -``HAS_MMX_PLUS`` One if processor supports Ext. MMX instructions -``HAS_SSE`` One if processor supports SSE instructions -``HAS_SSE2`` One if processor supports SSE2 instructions -``HAS_SSE_FP`` One if processor supports SSE FP instructions -``HAS_SSE_MMX`` One if processor supports SSE MMX instructions -``HAS_AMD_3DNOW`` One if processor supports 3DNow instructions -``HAS_AMD_3DNOW_PLUS`` One if processor supports 3DNow+ instructions -``HAS_IA64`` One if IA64 processor emulating x86 -``HAS_SERIAL_NUMBER`` One if processor has serial number -``PROCESSOR_SERIAL_NUMBER`` Processor serial number -``PROCESSOR_NAME`` Human readable processor name -``PROCESSOR_DESCRIPTION`` Human readable full processor description -``OS_NAME`` See :variable:`CMAKE_HOST_SYSTEM_NAME` -``OS_RELEASE`` The OS sub-type e.g. on Windows ``Professional`` -``OS_VERSION`` The OS build ID -``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` -============================= ================================================ +``NUMBER_OF_LOGICAL_CORES`` + Number of logical cores + +``NUMBER_OF_PHYSICAL_CORES`` + Number of physical cores + +``HOSTNAME`` + Hostname + +``FQDN`` + Fully qualified domain name + +``TOTAL_VIRTUAL_MEMORY`` + Total virtual memory in MiB [#mebibytes]_ + +``AVAILABLE_VIRTUAL_MEMORY`` + Available virtual memory in MiB [#mebibytes]_ + +``TOTAL_PHYSICAL_MEMORY`` + Total physical memory in MiB [#mebibytes]_ + +``AVAILABLE_PHYSICAL_MEMORY`` + Available physical memory in MiB [#mebibytes]_ + +``IS_64BIT`` + .. versionadded:: 3.10 + + One if processor is 64Bit + +``HAS_FPU`` + .. versionadded:: 3.10 + + One if processor has floating point unit + +``HAS_MMX`` + .. versionadded:: 3.10 + + One if processor supports MMX instructions + +``HAS_MMX_PLUS`` + .. versionadded:: 3.10 + + One if processor supports Ext. MMX instructions + +``HAS_SSE`` + .. versionadded:: 3.10 + + One if processor supports SSE instructions + +``HAS_SSE2`` + .. versionadded:: 3.10 + + One if processor supports SSE2 instructions + +``HAS_SSE_FP`` + .. versionadded:: 3.10 + + One if processor supports SSE FP instructions + +``HAS_SSE_MMX`` + .. versionadded:: 3.10 + + One if processor supports SSE MMX instructions + +``HAS_AMD_3DNOW`` + .. versionadded:: 3.10 + + One if processor supports 3DNow instructions + +``HAS_AMD_3DNOW_PLUS`` + .. versionadded:: 3.10 + + One if processor supports 3DNow+ instructions + +``HAS_IA64`` + .. versionadded:: 3.10 + + One if IA64 processor emulating x86 + +``HAS_SERIAL_NUMBER`` + .. versionadded:: 3.10 + + One if processor has serial number + +``PROCESSOR_SERIAL_NUMBER`` + .. versionadded:: 3.10 + + Processor serial number + +``PROCESSOR_NAME`` + .. versionadded:: 3.10 + + Human readable processor name + +``PROCESSOR_DESCRIPTION`` + .. versionadded:: 3.10 + + Human readable full processor description + +``OS_NAME`` + .. versionadded:: 3.10 + + See :variable:`CMAKE_HOST_SYSTEM_NAME` + +``OS_RELEASE`` + .. versionadded:: 3.10 + + The OS sub-type e.g. on Windows ``Professional`` + +``OS_VERSION`` + .. versionadded:: 3.10 + + The OS build ID + +``OS_PLATFORM`` + .. versionadded:: 3.10 + + See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` + +``DISTRIB_INFO`` + .. versionadded:: 3.22 + + Read :file:`/etc/os-release` file and define the given ``<variable>`` + into a list of read variables + +``DISTRIB_<name>`` + .. versionadded:: 3.22 + + Get the ``<name>`` variable (see `man 5 os-release`_) if it exists in the + :file:`/etc/os-release` file + + Example: + + .. code-block:: cmake + + cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME) + message(STATUS "${PRETTY_NAME}") + + cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO) + + foreach(VAR IN LISTS DISTRO) + message(STATUS "${VAR}=`${${VAR}}`") + endforeach() + + + Output:: + + -- Ubuntu 20.04.2 LTS + -- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/` + -- DISTRO_HOME_URL=`https://www.ubuntu.com/` + -- DISTRO_ID=`ubuntu` + -- DISTRO_ID_LIKE=`debian` + -- DISTRO_NAME=`Ubuntu` + -- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS` + -- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy` + -- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/` + -- DISTRO_UBUNTU_CODENAME=`focal` + -- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)` + -- DISTRO_VERSION_CODENAME=`focal` + -- DISTRO_VERSION_ID=`20.04` + +If :file:`/etc/os-release` file is not found, the command tries to gather OS +identification via fallback scripts. The fallback script can use `various +distribution-specific files`_ to collect OS identification data and map it +into `man 5 os-release`_ variables. + +Fallback Interface Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS + + In addition to the scripts shipped with CMake, a user may append full + paths to his script(s) to the this list. The script filename has the + following format: ``NNN-<name>.cmake``, where ``NNN`` is three digits + used to apply collected scripts in a specific order. + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname> + + Variables collected by the user provided fallback script + ought to be assigned to CMake variables using this naming + convention. Example, the ``ID`` variable from the manual becomes + ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID``. + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT + + The fallback script ought to store names of all assigned + ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>`` variables in this list. + +Example: + +.. code-block:: cmake + + # Try to detect some old distribution + # See also + # - http://linuxmafia.com/faq/Admin/release-files.html + # + if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release") + return() + endif() + # Get the first string only + file( + STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT + LIMIT_COUNT 1 + ) + # + # Example: + # + # Foobar distribution release 1.2.3 (server) + # + if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*") + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}") + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1}) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1}) + list( + APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID + ) + endif() + unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT) + .. rubric:: Footnotes .. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. + +.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html +.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 086668c16..1d8142351 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -96,6 +96,7 @@ The arguments are: with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. If the path names an existing directory the output file is placed in that directory with the same file name as the input file. + If the path contains non-existent directories, they are created. ``NO_SOURCE_PERMISSIONS`` .. versionadded:: 3.19 diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index e6d277f59..d66182540 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -30,7 +30,8 @@ The options are: Build = ctest_build results, in Build.xml Test = ctest_test results, in Test.xml Coverage = ctest_coverage results, in Coverage.xml - MemCheck = ctest_memcheck results, in DynamicAnalysis.xml + MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and + DynamicAnalysis-Test.xml Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES Upload = Files prepared for upload by ctest_upload(), in Upload.xml diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 89787d133..6a9a6a04d 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -190,29 +190,34 @@ 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. +.. versionadded: 3.22 + CTest can parse custom measurements from tags named + ``<CTestMeasurement>`` or ``<CTestMeasurementFile>``. The older names + ``<DartMeasurement>`` and ``<DartMeasurementFile>`` are still supported. + 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>" + "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>" << std::endl; std::cout << - "<DartMeasurement type=\"text/string\" name=\"color\">red</DartMeasurement>" + "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>" << std::endl; std::cout << - "<DartMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</DartMeasurement>" + "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>" << std::endl; std::cout << - "<DartMeasurement type=\"text/preformatted\" name=\"Console Output\">" << + "<CTestMeasurement 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; + "</CTestMeasurement>" << std::endl; Image Measurements """""""""""""""""" @@ -222,16 +227,16 @@ 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; + "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" << + "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl; std::cout << - "<DartMeasurementFile type=\"image/gif\" name=\"ValidImage\">" << - "/dir/to/valid_img.gif</DartMeasurementFile>" << std::endl; + "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" << + "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl; std::cout << - "<DartMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << - "/dir/to/img.png</DartMeasurementFile>" + "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << + "/dir/to/img.png</CTestMeasurementFile>" << std::endl; Images will be displayed together in an interactive comparison mode on CDash @@ -252,13 +257,17 @@ separate from the interactive comparison UI. Attached Files """""""""""""" +.. versionadded:: 3.21 + The following example demonstrates how to upload non-image files to CDash. .. code-block:: c++ std::cout << - "<DartMeasurementFile type=\"file\" name=\"MyTestInputData\">" << - "/dir/to/data.csv</DartMeasurementFile>" << std::endl; + "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" << + "/dir/to/data1.csv</CTestMeasurementFile>\n" << + "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" << + "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl; If the name of the file to upload is known at configure time, you can use the :prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test @@ -267,6 +276,8 @@ properties instead. Custom Details """""""""""""" +.. versionadded:: 3.21 + The following example demonstrates how to specify a custom value for the ``Test Details`` field displayed on CDash. @@ -274,3 +285,22 @@ The following example demonstrates how to specify a custom value for the std::cout << "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl; + +.. _`Additional Labels`: + +Additional Labels +""""""""""""""""" + +.. versionadded:: 3.22 + +The following example demonstrates how to add additional labels to a test +at runtime. + +.. code-block:: c++ + + std::cout << + "<CTestLabel>Custom Label 1</CTestLabel>\n" << + "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl; + +Use the :prop_test:`LABELS` test property instead for labels that can be +determined at configure time. diff --git a/Help/command/file.rst b/Help/command/file.rst index f038871b7..799b6ff10 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -838,11 +838,16 @@ of their content even if options are used to select a subset of files. The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. +status messages, and ``NO_SOURCE_PERMISSIONS`` is default. + Installation scripts generated by the :command:`install` command use this signature (with some undocumented options for internal use). +.. versionchanged:: 3.22 + + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`file(INSTALL)`. + .. _SIZE: .. code-block:: cmake @@ -1068,7 +1073,7 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: .. versionadded:: 3.11 Specify whether the .netrc file is to be used for operation. If this - option is not specified, the value of the ``CMAKE_NETRC`` variable + option is not specified, the value of the :variable:`CMAKE_NETRC` variable will be used instead. Valid levels are: @@ -1087,29 +1092,28 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: Specify an alternative .netrc file to the one in your home directory, if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option - is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable will be used instead. -If neither ``NETRC`` option is given CMake will check variables -``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. - ``TLS_VERIFY <ON|OFF>`` Specify whether to verify the server certificate for ``https://`` URLs. - The default is to *not* verify. + The default is to *not* verify. If this option is not specified, the value + of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead. .. versionadded:: 3.18 Added support to ``file(UPLOAD)``. ``TLS_CAINFO <file>`` - Specify a custom Certificate Authority file for ``https://`` URLs. + Specify a custom Certificate Authority file for ``https://`` URLs. If this + option is not specified, the value of the :variable:`CMAKE_TLS_CAINFO` + variable will be used instead. .. versionadded:: 3.18 Added support to ``file(UPLOAD)``. For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to -check certificates. If neither ``TLS`` option is given CMake will check -variables :variable:`CMAKE_TLS_VERIFY` and ``CMAKE_TLS_CAINFO``, respectively. +check certificates. Additional options to ``DOWNLOAD`` are: diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 3dfd62fc3..1a79a8af3 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -5,12 +5,74 @@ find_package .. contents:: -Find an external project, and load its settings. +Find a package (usually provided by something external to the project), +and load its package-specific details. + +Search Modes +^^^^^^^^^^^^ + +The command has two very distinct ways of conducting the search: + +**Module mode** + In this mode, CMake searches for a file called ``Find<PackageName>.cmake``, + looking first in the locations listed in the :variable:`CMAKE_MODULE_PATH`, + then among the :ref:`Find Modules` provided by the CMake installation. + If the file is found, it is read and processed by CMake. It is responsible + for finding the package, checking the version, and producing any needed + messages. Some Find modules provide limited or no support for versioning; + check the Find module's documentation. + + The ``Find<PackageName>.cmake`` file is not typically provided by the + package itself. Rather, it is normally provided by something external to + the package, such as the operating system, CMake itself, or even the project + from which the ``find_package()`` command was called. Being externally + provided, :ref:`Find Modules` tend to be heuristic in nature and are + susceptible to becoming out-of-date. They typically search for certain + libraries, files and other package artifacts. + + Module mode is only supported by the + :ref:`basic command signature <Basic Signature>`. + +**Config mode** + In this mode, CMake searches for a file called + ``<lowercasePackageName>-config.cmake`` or ``<PackageName>Config.cmake``. + It will also look for ``<lowercasePackageName>-config-version.cmake`` or + ``<PackageName>ConfigVersion.cmake`` if version details were specified + (see :ref:`version selection` for an explanation of how these separate + version files are used). + + In config mode, the command can be given a list of names to search for + as package names. The locations where CMake searches for the config and + version files is considerably more complicated than for Module mode + (see :ref:`search procedure`). + + The config and version files are typically installed as part of the + package, so they tend to be more reliable than Find modules. They usually + contain direct knowledge of the package contents, so no searching or + heuristics are needed within the config or version files themselves. + + Config mode is supported by both the :ref:`basic <Basic Signature>` and + :ref:`full <Full Signature>` command signatures. + +The command arguments determine which of the above modes is used. When the +`basic signature`_ is used, the command searches in Module mode first. +If the package is not found, the search falls back to Config mode. +A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable +to true to reverse the priority and direct CMake to search using Config mode +first before falling back to Module mode. The basic signature can also be +forced to use only Module mode with a ``MODULE`` keyword. If the +`full signature`_ is used, the command only searches in Config mode. + +Where possible, user code should generally look for packages using the +`basic signature`_, since that allows the package to be found with either mode. +Project maintainers wishing to provide a config package should understand +the bigger picture, as explained in :ref:`Full Signature` and all subsequent +sections on this page. .. _`basic signature`: -Basic Signature and Module Mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Basic Signature +^^^^^^^^^^^^^^^ .. code-block:: cmake @@ -19,20 +81,39 @@ Basic Signature and Module Mode [OPTIONAL_COMPONENTS components...] [NO_POLICY_SCOPE]) -Finds and loads settings from an external project. ``<PackageName>_FOUND`` -will be set to indicate whether the package was found. When the -package is found package-specific information is provided through -variables and :ref:`Imported Targets` documented by the package itself. The +The basic signature is supported by both Module and Config modes. +The ``MODULE`` keyword implies that only Module mode can be used to find +the package, with no fallback to Config mode. + +Regardless of the mode used, a ``<PackageName>_FOUND`` variable will be +set to indicate whether the package was found. When the package is found, +package-specific information may be provided through other variables and +:ref:`Imported Targets` documented by the package itself. The ``QUIET`` option disables informational messages, including those indicating that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. A package-specific list of required components may be listed after the -``COMPONENTS`` option (or after the ``REQUIRED`` option if present). +``COMPONENTS`` keyword. If any of these components are not able to be +satisfied, the package overall is considered to be not found. If the +``REQUIRED`` option is also present, this is treated as a fatal error, +otherwise execution still continues. As a form of shorthand, if the +``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted +and the required components can be listed directly after ``REQUIRED``. + Additional optional components may be listed after -``OPTIONAL_COMPONENTS``. Available components and their influence on -whether a package is considered to be found are defined by the target -package. +``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall +can still be considered found, as long as all required components are +satisfied. + +The set of available components and their meaning are defined by the +target package. Formally, it is up to the target package how to +interpret the component information given to it, but it should follow +the expectations stated above. For calls where no components are specified, +there is no single expected behavior and target packages should clearly +define what occurs in such cases. Common arrangements include assuming it +should find all components, no components or some well-defined subset of the +available components. .. _FIND_PACKAGE_VERSION_FORMAT: @@ -40,12 +121,13 @@ The ``[version]`` argument requests a version with which the package found should be compatible. There are two possible forms in which it may be specified: - * A single version with the format ``major[.minor[.patch[.tweak]]]``. + * A single version with the format ``major[.minor[.patch[.tweak]]]``, where + each component is a numeric value. * A version range with the format ``versionMin...[<]versionMax`` where - ``versionMin`` and ``versionMax`` have the same format as the single - version. By default, both end points are included. By specifying ``<``, - the upper end point will be excluded. Version ranges are only supported - with CMake 3.19 or later. + ``versionMin`` and ``versionMax`` have the same format and constraints + on components being integers as the single version. By default, both end + points are included. By specifying ``<``, the upper end point will be + excluded. Version ranges are only supported with CMake 3.19 or later. The ``EXACT`` option requests that the version be matched exactly. This option is incompatible with the specification of a version range. @@ -62,36 +144,10 @@ only take the single version at the lower end of the range into account. See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. -The command has two modes by which it searches for packages: "Module" -mode and "Config" mode. The above signature selects Module mode. -If no module is found the command falls back to Config mode, described -below. This fall back is disabled if the ``MODULE`` option is given. - -In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``. -The file is first searched in the :variable:`CMAKE_MODULE_PATH`, -then among the :ref:`Find Modules` provided by the CMake installation. -If the file is found, it is read and processed by CMake. It is responsible -for finding the package, checking the version, and producing any needed -messages. Some find-modules provide limited or no support for versioning; -check the module documentation. - -If the ``MODULE`` option is not specified in the above signature, -CMake first searches for the package using Module mode. Then, if the -package is not found, it searches again using Config mode. A user -may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to -``TRUE`` to direct CMake first search using Config mode before falling -back to Module mode. - -Full Signature and Config Mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -User code should generally look for packages using the above `basic -signature`_. The remainder of this command documentation specifies the -full command signature and details of the search process. Project -maintainers wishing to provide a package to be found by this command -are encouraged to read on. - -The complete Config mode command signature is +.. _`full signature`: + +Full Signature +^^^^^^^^^^^^^^ .. code-block:: cmake @@ -129,18 +185,19 @@ hold the directory containing the file. By default the command searches for a package with the name ``<PackageName>``. If the ``NAMES`` option is given the names following it are used instead of ``<PackageName>``. The command searches for a file called ``<PackageName>Config.cmake`` or -``<lower-case-package-name>-config.cmake`` for each name specified. +``<lowercasePackageName>-config.cmake`` for each name specified. A replacement set of possible configuration file names may be given -using the ``CONFIGS`` option. The search procedure is specified below. -Once found, the configuration file is read and processed by CMake. +using the ``CONFIGS`` option. The :ref:`search procedure` is specified below. +Once found, any :ref:`version constraint <version selection>` is checked, +and if satisfied, the configuration file is read and processed by CMake. Since the file is provided by the package it already knows the location of package contents. The full path to the configuration file is stored in the cmake variable ``<PackageName>_CONFIG``. All configuration files which have been considered by CMake while -searching for an installation of the package with an appropriate -version are stored in the cmake variable ``<PackageName>_CONSIDERED_CONFIGS``, -the associated versions in ``<PackageName>_CONSIDERED_VERSIONS``. +searching for the package with an appropriate version are stored in the +``<PackageName>_CONSIDERED_CONFIGS`` variable, and the associated versions +in the ``<PackageName>_CONSIDERED_VERSIONS`` variable. If the package configuration file cannot be found CMake will generate an error describing the problem unless the ``QUIET`` argument is @@ -150,143 +207,18 @@ fatal error is generated and the configure step stops executing. If configuration file CMake will ignore it and search from scratch. Package maintainers providing CMake package configuration files are -encouraged to name and install them such that the `Search Procedure`_ +encouraged to name and install them such that the :ref:`search procedure` outlined below will find them without requiring use of additional options. -Version Selection -^^^^^^^^^^^^^^^^^ +.. _`search procedure`: -When the ``[version]`` argument is given, Config mode will only find a -version of the package that claims compatibility with the requested -version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the -``EXACT`` option is given, only a version of the package claiming an exact match -of the requested version may be found. CMake does not establish any -convention for the meaning of version numbers. Package version -numbers are checked by "version" files provided by the packages -themselves. For a candidate package configuration file -``<config-file>.cmake`` the corresponding version file is located next -to it and named either ``<config-file>-version.cmake`` or -``<config-file>Version.cmake``. If no such version file is available -then the configuration file is assumed to not be compatible with any -requested version. A basic version file containing generic version -matching code can be created using the -:module:`CMakePackageConfigHelpers` module. When a version file -is found it is loaded to check the requested version number. The -version file is loaded in a nested scope in which the following -variables have been defined: +Config Mode Search Procedure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``PACKAGE_FIND_NAME`` - The ``<PackageName>`` -``PACKAGE_FIND_VERSION`` - Full requested version string -``PACKAGE_FIND_VERSION_MAJOR`` - Major version if requested, else 0 -``PACKAGE_FIND_VERSION_MINOR`` - Minor version if requested, else 0 -``PACKAGE_FIND_VERSION_PATCH`` - Patch version if requested, else 0 -``PACKAGE_FIND_VERSION_TWEAK`` - Tweak version if requested, else 0 -``PACKAGE_FIND_VERSION_COUNT`` - Number of version components, 0 to 4 - -When a version range is specified, the above version variables will hold -values based on the lower end of the version range. This is to preserve -compatibility with packages that have not been implemented to expect version -ranges. In addition, the version range will be described by the following -variables: - -``PACKAGE_FIND_VERSION_RANGE`` - Full requested version range string -``PACKAGE_FIND_VERSION_RANGE_MIN`` - This specifies whether the lower end point of the version range should be - included or excluded. Currently, the only supported value for this variable - is ``INCLUDE``. -``PACKAGE_FIND_VERSION_RANGE_MAX`` - This specifies whether the upper end point of the version range should be - included or excluded. The supported values for this variable are - ``INCLUDE`` and ``EXCLUDE``. - -``PACKAGE_FIND_VERSION_MIN`` - Full requested version string of the lower end point of the range -``PACKAGE_FIND_VERSION_MIN_MAJOR`` - Major version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_MINOR`` - Minor version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_PATCH`` - Patch version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_TWEAK`` - Tweak version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_COUNT`` - Number of version components of the lower end point, 0 to 4 - -``PACKAGE_FIND_VERSION_MAX`` - Full requested version string of the upper end point of the range -``PACKAGE_FIND_VERSION_MAX_MAJOR`` - Major version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_MINOR`` - Minor version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_PATCH`` - Patch version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_TWEAK`` - Tweak version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_COUNT`` - Number of version components of the upper end point, 0 to 4 - -Regardless of whether a single version or a version range is specified, the -variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold -the full requested version string as specified. - -The version file checks whether it satisfies the requested version and -sets these variables: - -``PACKAGE_VERSION`` - Full provided version string -``PACKAGE_VERSION_EXACT`` - True if version is exact match -``PACKAGE_VERSION_COMPATIBLE`` - True if version is compatible -``PACKAGE_VERSION_UNSUITABLE`` - True if unsuitable as any version - -These variables are checked by the ``find_package`` command to determine -whether the configuration file provides an acceptable version. They -are not available after the ``find_package`` call returns. If the version -is acceptable the following variables are set: - -``<PackageName>_VERSION`` - Full provided version string -``<PackageName>_VERSION_MAJOR`` - Major version if provided, else 0 -``<PackageName>_VERSION_MINOR`` - Minor version if provided, else 0 -``<PackageName>_VERSION_PATCH`` - Patch version if provided, else 0 -``<PackageName>_VERSION_TWEAK`` - Tweak version if provided, else 0 -``<PackageName>_VERSION_COUNT`` - Number of version components, 0 to 4 - -and the corresponding package configuration file is loaded. -When multiple package configuration files are available whose version files -claim compatibility with the version requested it is unspecified which -one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` -is set no attempt is made to choose a highest or closest version number. - -To control the order in which ``find_package`` checks for compatibility use -the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and -:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. -For instance in order to select the highest version one can set - -.. code-block:: cmake - - SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) - SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) - -before calling ``find_package``. - -Search Procedure -^^^^^^^^^^^^^^^^ +.. note:: + When Config mode is used, this search procedure is applied regardless of + whether the :ref:`full <full signature>` or :ref:`basic <basic signature>` + signature was given. CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a @@ -432,7 +364,7 @@ enabled. hard-coded guesses. .. versionadded:: 3.16 - Added the ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable + Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable various search locations. .. |FIND_XXX| replace:: find_package @@ -448,8 +380,154 @@ which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable may be set to ``TRUE`` before calling ``find_package`` in order to resolve symbolic links and store the real path to the file. -Every non-REQUIRED ``find_package`` call can be disabled by setting the -:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. +Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED: + +* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable + to ``TRUE`` disables the package. + +* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable + to ``TRUE`` makes the package REQUIRED. + +Setting both variables to ``TRUE`` simultaneously is an error. + +.. _`version selection`: + +Config Mode Version Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + When Config mode is used, this version selection process is applied + regardless of whether the :ref:`full <full signature>` or + :ref:`basic <basic signature>` signature was given. + +When the ``[version]`` argument is given, Config mode will only find a +version of the package that claims compatibility with the requested +version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the +``EXACT`` option is given, only a version of the package claiming an exact match +of the requested version may be found. CMake does not establish any +convention for the meaning of version numbers. Package version +numbers are checked by "version" files provided by the packages +themselves. For a candidate package configuration file +``<config-file>.cmake`` the corresponding version file is located next +to it and named either ``<config-file>-version.cmake`` or +``<config-file>Version.cmake``. If no such version file is available +then the configuration file is assumed to not be compatible with any +requested version. A basic version file containing generic version +matching code can be created using the +:module:`CMakePackageConfigHelpers` module. When a version file +is found it is loaded to check the requested version number. The +version file is loaded in a nested scope in which the following +variables have been defined: + +``PACKAGE_FIND_NAME`` + The ``<PackageName>`` +``PACKAGE_FIND_VERSION`` + Full requested version string +``PACKAGE_FIND_VERSION_MAJOR`` + Major version if requested, else 0 +``PACKAGE_FIND_VERSION_MINOR`` + Minor version if requested, else 0 +``PACKAGE_FIND_VERSION_PATCH`` + Patch version if requested, else 0 +``PACKAGE_FIND_VERSION_TWEAK`` + Tweak version if requested, else 0 +``PACKAGE_FIND_VERSION_COUNT`` + Number of version components, 0 to 4 + +When a version range is specified, the above version variables will hold +values based on the lower end of the version range. This is to preserve +compatibility with packages that have not been implemented to expect version +ranges. In addition, the version range will be described by the following +variables: + +``PACKAGE_FIND_VERSION_RANGE`` + Full requested version range string +``PACKAGE_FIND_VERSION_RANGE_MIN`` + This specifies whether the lower end point of the version range should be + included or excluded. Currently, the only supported value for this variable + is ``INCLUDE``. +``PACKAGE_FIND_VERSION_RANGE_MAX`` + This specifies whether the upper end point of the version range should be + included or excluded. The supported values for this variable are + ``INCLUDE`` and ``EXCLUDE``. + +``PACKAGE_FIND_VERSION_MIN`` + Full requested version string of the lower end point of the range +``PACKAGE_FIND_VERSION_MIN_MAJOR`` + Major version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_MINOR`` + Minor version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_PATCH`` + Patch version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_TWEAK`` + Tweak version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_COUNT`` + Number of version components of the lower end point, 0 to 4 + +``PACKAGE_FIND_VERSION_MAX`` + Full requested version string of the upper end point of the range +``PACKAGE_FIND_VERSION_MAX_MAJOR`` + Major version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_MINOR`` + Minor version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_PATCH`` + Patch version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_TWEAK`` + Tweak version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_COUNT`` + Number of version components of the upper end point, 0 to 4 + +Regardless of whether a single version or a version range is specified, the +variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold +the full requested version string as specified. + +The version file checks whether it satisfies the requested version and +sets these variables: + +``PACKAGE_VERSION`` + Full provided version string +``PACKAGE_VERSION_EXACT`` + True if version is exact match +``PACKAGE_VERSION_COMPATIBLE`` + True if version is compatible +``PACKAGE_VERSION_UNSUITABLE`` + True if unsuitable as any version + +These variables are checked by the ``find_package`` command to determine +whether the configuration file provides an acceptable version. They +are not available after the ``find_package`` call returns. If the version +is acceptable the following variables are set: + +``<PackageName>_VERSION`` + Full provided version string +``<PackageName>_VERSION_MAJOR`` + Major version if provided, else 0 +``<PackageName>_VERSION_MINOR`` + Minor version if provided, else 0 +``<PackageName>_VERSION_PATCH`` + Patch version if provided, else 0 +``<PackageName>_VERSION_TWEAK`` + Tweak version if provided, else 0 +``<PackageName>_VERSION_COUNT`` + Number of version components, 0 to 4 + +and the corresponding package configuration file is loaded. +When multiple package configuration files are available whose version files +claim compatibility with the version requested it is unspecified which +one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` +is set no attempt is made to choose a highest or closest version number. + +To control the order in which ``find_package`` checks for compatibility use +the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and +:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. +For instance in order to select the highest version one can set + +.. code-block:: cmake + + SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) + +before calling ``find_package``. Package File Interface Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -479,7 +557,7 @@ restores their original state before returning): ``<PackageName>_FIND_VERSION_EXACT`` True if ``EXACT`` option was given ``<PackageName>_FIND_COMPONENTS`` - List of requested components + List of specified components (required and optional) ``<PackageName>_FIND_REQUIRED_<c>`` True if component ``<c>`` is required, false if component ``<c>`` is optional diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index f77d8af78..46da2853b 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -9,7 +9,7 @@ Get a property. <GLOBAL | DIRECTORY [<dir>] | TARGET <target> | - SOURCE <source> | + SOURCE <source> [DIRECTORY <dir> | TARGET_DIRECTORY <target>] | INSTALL <file> | TEST <test> | diff --git a/Help/command/if.rst b/Help/command/if.rst index fbf3e363f..6ff8852a3 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -171,7 +171,7 @@ Comparisons ``if(<variable|string> MATCHES regex)`` True if the given string or variable's value matches the given regular - condition. See :ref:`Regex Specification` for regex format. + expression. See :ref:`Regex Specification` for regex format. .. versionadded:: 3.9 ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. diff --git a/Help/command/install.rst b/Help/command/install.rst index c6af4897e..1236f1d32 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -30,6 +30,10 @@ are executed in order during installation. with those in the parent directory to run in the order declared (see policy :policy:`CMP0082`). +.. versionchanged:: 3.22 + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`install()`. + There are multiple signatures for this command. Some of them define installation options for files and targets. Options common to multiple signatures are covered here but they are valid only for diff --git a/Help/command/list.rst b/Help/command/list.rst index f46641f0b..9b49cb493 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -161,8 +161,9 @@ Inserts elements to the list to the specified location. .. versionadded:: 3.15 If no variable name is given, removes exactly one element. Otherwise, -assign the last element's value to the given variable and removes it, -up to the last variable name given. +with `N` variable names provided, assign the last `N` elements' values +to the given variables and then remove the last `N` values from +``<list>``. .. _POP_FRONT: @@ -173,8 +174,9 @@ up to the last variable name given. .. versionadded:: 3.15 If no variable name is given, removes exactly one element. Otherwise, -assign the first element's value to the given variable and removes it, -up to the last variable name given. +with `N` variable names provided, assign the first `N` elements' values +to the given variables and then remove the first `N` values from +``<list>``. .. _PREPEND: diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index bf437b434..555520d22 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,8 +9,8 @@ Set a named property in a given scope. DIRECTORY [<dir>] | TARGET [<target1> ...] | SOURCE [<src1> ...] - [DIRECTORY <dirs> ...] | - [TARGET_DIRECTORY <targets> ...] + [DIRECTORY <dirs> ...] + [TARGET_DIRECTORY <targets> ...] | INSTALL [<file1> ...] | TEST [<test1> ...] | CACHE [<entry1> ...] > diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index a4b5bf1c6..83ae2864c 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -22,7 +22,8 @@ The options are: CMake will automatically detect, from ``<src>`` files paths, source groups it needs to create, to keep structure of source groups analogically to the actual files and directories structure in the project. Paths of ``<src>`` - files will be cut to be relative to ``<root>``. + files will be cut to be relative to ``<root>``. The command fails if the + paths within ``src`` do not start with ``root``. ``PREFIX`` .. versionadded:: 3.8 diff --git a/Help/command/string.rst b/Help/command/string.rst index 8ad0089af..29ad082a9 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -449,38 +449,73 @@ be in Coordinated Universal Time (UTC) rather than local time. The optional ``<format_string>`` may contain the following format specifiers: -:: +``%%`` + .. versionadded:: 3.8 - %% A literal percent sign (%). - %d The day of the current month (01-31). - %H The hour on a 24-hour clock (00-23). - %I The hour on a 12-hour clock (01-12). - %j The day of the current year (001-366). - %m The month of the current year (01-12). - %b Abbreviated month name (e.g. Oct). - %B Full month name (e.g. October). - %M The minute of the current hour (00-59). - %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). - %S The second of the current minute. - 60 represents a leap second. (00-60) - %U The week number of the current year (00-53). - %w The day of the current week. 0 is Sunday. (0-6) - %a Abbreviated weekday name (e.g. Fri). - %A Full weekday name (e.g. Friday). - %y The last two digits of the current year (00-99) - %Y The current year. - -.. versionadded:: 3.6 - ``%s`` format specifier (UNIX time). + A literal percent sign (%). -.. versionadded:: 3.7 - ``%a`` and ``%b`` format specifiers (abbreviated month and weekday names). +``%d`` + The day of the current month (01-31). -.. versionadded:: 3.8 - ``%%`` specifier (literal ``%``). +``%H`` + The hour on a 24-hour clock (00-23). -.. versionadded:: 3.7 - ``%A`` and ``%B`` format specifiers (full month and weekday names). +``%I`` + The hour on a 12-hour clock (01-12). + +``%j`` + The day of the current year (001-366). + +``%m`` + The month of the current year (01-12). + +``%b`` + .. versionadded:: 3.7 + + Abbreviated month name (e.g. Oct). + +``%B`` + .. versionadded:: 3.10 + + Full month name (e.g. October). + +``%M`` + The minute of the current hour (00-59). + +``%s`` + .. versionadded:: 3.6 + + Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). + +``%S`` + The second of the current minute. 60 represents a leap second. (00-60) + +``%U`` + The week number of the current year (00-53). + +``%V`` + .. versionadded:: 3.22 + + The ISO 8601 week number of the current year (01-53). + +``%w`` + The day of the current week. 0 is Sunday. (0-6) + +``%a`` + .. versionadded:: 3.7 + + Abbreviated weekday name (e.g. Fri). + +``%A`` + .. versionadded:: 3.10 + + Full weekday name (e.g. Friday). + +``%y`` + The last two digits of the current year (00-99). + +``%Y`` + The current year. Unknown format specifiers will be ignored and copied to the output as-is. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 08f8d5b62..06da910dd 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -19,6 +19,10 @@ Try Compiling Whole Projects Try building a project. The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. +.. versionadded:: 3.14 + The name of the ``<resultVar>`` is defined by the user. Previously, it had + a fixed name ``RESULT_VAR``. + In this form, ``<srcdir>`` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` will not be deleted after this command is run. Specify ``<targetName>`` to @@ -47,6 +51,10 @@ Try building an executable or static library from one or more source files variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. +.. versionadded:: 3.14 + The name of the ``<resultVar>`` is defined by the user. Previously, it had + a fixed name ``RESULT_VAR``. + In this form, one or more source files must be provided. If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``, the sources must include a definition for ``main`` and CMake will create a diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index fc41cdd7b..404de985d 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -30,6 +30,11 @@ executable was built, but failed to run, then ``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for information on how the test project is constructed to build the source file. +.. versionadded:: 3.14 + The names of the result variables ``<runResultVar>`` and + ``<compileResultVar>`` are defined by the user. Previously, they had + fixed names ``RUN_RESULT_VAR`` and ``COMPILE_RESULT_VAR``. + The options are: ``CMAKE_FLAGS <flags>...`` diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index d8d53ece3..f96ca3203 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -274,10 +274,23 @@ List of CPack DEB generator specific variables: Possible values are: - - lzma - - xz - - bzip2 - - gzip + ``lzma`` + Lempel–Ziv–Markov chain algorithm + + ``xz`` + XZ Utils compression + + ``bzip2`` + bzip2 Burrows–Wheeler algorithm + + ``gzip`` + GNU Gzip compression + + ``zstd`` + .. versionadded:: 3.22 + + Zstandard compression + .. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY @@ -652,9 +665,18 @@ Dbgsym packaging has its own set of variables: .. note:: + Setting this also strips the ELF files in the generated non-dbgsym package, + which results in debuginfo only being available in the dbgsym package. + +.. note:: + Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the DEB generator, so will not contain debug symbols and + a dbgsym package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + Building Debian packages on Windows ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index 02e33ba30..299cfece9 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -3,8 +3,8 @@ CPack NSIS Generator CPack Nullsoft Scriptable Install System (NSIS) generator specific options. -.. versionchanged:: 3.17 - The NSIS generator requires NSIS 3.0 or newer. +.. versionchanged:: 3.22 + The NSIS generator requires NSIS 3.03 or newer. Variables specific to CPack NSIS generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -201,3 +201,9 @@ on Windows Nullsoft Scriptable Install System. .. versionadded:: 3.21 If set, specify the name of the NSIS executable. Default is ``makensis``. + +.. variable:: CPACK_NSIS_IGNORE_LICENSE_PAGE + + .. versionadded:: 3.22 + + If set, do not display the page containing the license during installation. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 322ab68aa..0d287fc91 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -840,6 +840,10 @@ Debuginfo RPM packaging has its own set of variables: Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the RPM generator, so will not contain debug symbols and + a debuginfo package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + .. note:: Packages generated from packages without binary files, with binary files but @@ -1023,7 +1027,7 @@ Source RPM packaging has its own set of variables: * Mandatory : YES * Default : "/" -.. VARIABLE:: CPACK_RPM_BUILDREQUIRES +.. variable:: CPACK_RPM_BUILDREQUIRES List of source rpm build dependencies. @@ -1035,3 +1039,16 @@ Source RPM packaging has its own set of variables: example:: set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8") + +.. variable:: CPACK_RPM_REQUIRES_EXCLUDE_FROM + + .. versionadded:: 3.22 + + * Mandatory : NO + * Default : - + + May be used to keep the dependency generator from scanning specific files + or directories for dependencies. Note that you can use a regular + expression that matches all of the directories or files, for example:: + + set(CPACK_RPM_REQUIRES_EXCLUDE_FROM "bin/libqsqloci.*\\.so.*") diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 29fc88033..4a2a5d963 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -92,6 +92,11 @@ literal block after ``::`` the referenced documents inline as part of the referencing document. +``versionadded``, ``versionchanged`` directives + Specify that something was added or changed by a named CMake version. + The command-line help processor prints the block content as if the lines + were normal paragraph text with interpretation. + Inline markup constructs not listed above are printed literally in the command-line help output. We prefer to use inline markup constructs that look correct in source form, so avoid use of \\-escapes in favor of inline diff --git a/Help/envvar/CMAKE_BUILD_TYPE.rst b/Help/envvar/CMAKE_BUILD_TYPE.rst new file mode 100644 index 000000000..f798aff1f --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,10 @@ +CMAKE_BUILD_TYPE +---------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_BUILD_TYPE`` environment variable specifies a default value +for the :variable:`CMAKE_BUILD_TYPE` variable when there is no explicit +configuration given on the first run while creating a new build tree. diff --git a/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst new file mode 100644 index 000000000..833aa4a9f --- /dev/null +++ b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst @@ -0,0 +1,11 @@ +CMAKE_CONFIGURATION_TYPES +------------------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_CONFIGURATION_TYPES`` environment variable specifies a +default value for the :variable:`CMAKE_CONFIGURATION_TYPES` variable +when there is no explicit configuration given on the first run while +creating a new build tree. diff --git a/Help/envvar/CMAKE_INSTALL_MODE.rst b/Help/envvar/CMAKE_INSTALL_MODE.rst new file mode 100644 index 000000000..37db0d714 --- /dev/null +++ b/Help/envvar/CMAKE_INSTALL_MODE.rst @@ -0,0 +1,37 @@ +CMAKE_INSTALL_MODE +------------------ + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_INSTALL_MODE`` environment variable allows users to operate +CMake in an alternate mode of :command:`file(INSTALL)` and :command:`install()`. + +The default behavior for an installation is to copy a source file from a +source directory into a destination directory. This environment variable +however allows the user to override this behavior, causing CMake to create +symbolic links instead. + +.. note:: + A symbolic link consists of a reference file path rather than contents of its own, + hence there are two ways to express the relation, either by a relative or an absolute path. + +The following values are allowed for ``CMAKE_INSTALL_MODE``: + +* empty, unset or ``COPY``: default behavior, duplicate the file at its destination +* ``ABS_SYMLINK``: create an *absolute* symbolic link to the source file at the destination *or fail* +* ``ABS_SYMLINK_OR_COPY``: like ``ABS_SYMLINK`` but silently copy on error +* ``REL_SYMLINK``: create an *relative* symbolic link to the source file at the destination *or fail* +* ``REL_SYMLINK_OR_COPY``: like ``REL_SYMLINK`` but silently copy on error +* ``SYMLINK``: try as if through ``REL_SYMLINK`` and fall back to ``ABS_SYMLINK`` if the referenced + file cannot be expressed using a relative path. Fail on error. +* ``SYMLINK_OR_COPY``: like ``SYMLINK`` but silently copy on error + +Installing symbolic links rather than copying files can help conserve storage space because files do +not have to be duplicated on disk. However, modifications applied to the source immediately affects +the symbolic link and vice versa. *Use with caution*. + +.. note:: ``CMAKE_INSTALL_MODE`` only affects files, *not* directories. + +.. note:: Symbolic links are not available on all platforms. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index c06555036..9ec33c354 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -1,7 +1,14 @@ Visual Studio 10 2010 --------------------- -Generates Visual Studio 10 (VS 2010) project files. +Deprecated. Generates Visual Studio 10 (VS 2010) project files. + +.. note:: + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 10 2010 tools + using the :generator:`Visual Studio 11 2012` (or above) generator + with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``, or by + using the :generator:`NMake Makefiles` generator. For compatibility with CMake versions prior to 3.0, one may specify this generator using the name ``Visual Studio 10`` without the year component. diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index a4f5f98e3..b4d6f6d9f 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -15,20 +15,20 @@ Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ -.. versionadded:: 3.9 - VS 2017 supports multiple installations on the same machine. - The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a - cache entry containing the absolute path to a Visual Studio instance. - If the value is not specified explicitly by the user or a toolchain file, - CMake queries the Visual Studio Installer to locate VS instances, chooses - one, and sets the variable as a cache entry to hold the value persistently. - .. versionadded:: 3.11 - When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment - variable is set and points to the ``Common7/Tools`` directory within - one of the instances, that instance will be used. Otherwise, if more - than one instance is installed we do not define which one is chosen - by default. + +VS 2017 supports multiple installations on the same machine. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +one of the instances, that instance will be used. Otherwise, if more +than one instance is installed we do not define which one is chosen +by default. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index 41e8479b2..cf1ec0186 100644 --- a/Help/guide/tutorial/A Basic Starting Point.rst +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -24,6 +24,45 @@ Upper, lower, and mixed case commands are supported by CMake. The source code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be used to compute the square root of a number. +Build and Run +------------- + +That's all that is needed - we can build and run our project now! First, run +the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. + +For example, from the command line we could navigate to the +``Help/guide/tutorial`` directory of the CMake source code tree and create a +build directory: + +.. code-block:: console + + mkdir Step1_build + +Next, navigate to the build directory and run CMake to configure the project +and generate a native build system: + +.. code-block:: console + + cd Step1_build + cmake ../Step1 + +Then call that build system to actually compile/link the project: + +.. code-block:: console + + cmake --build . + +Finally, try to use the newly built ``Tutorial`` with these commands: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + + Adding a Version Number and Configured Header File -------------------------------------------------- @@ -113,39 +152,24 @@ call to ``add_executable``. :language: cmake :end-before: # configure a header file to pass some of the CMake settings -Build and Test --------------- - -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -For example, from the command line we could navigate to the -``Help/guide/tutorial`` directory of the CMake source code tree and create a -build directory: - -.. code-block:: console +Rebuild +------- - mkdir Step1_build - -Next, navigate to the build directory and run CMake to configure the project -and generate a native build system: +Let's build our project again. We already created a build directory and ran +CMake, so we can skip to the build step: .. code-block:: console cd Step1_build - cmake ../Step1 - -Then call that build system to actually compile/link the project: - -.. code-block:: console - cmake --build . -Finally, try to use the newly built ``Tutorial`` with these commands: +Now we can try to use the newly built ``Tutorial`` with same commands as before: .. code-block:: console Tutorial 4294967296 Tutorial 10 Tutorial + +Check that the version number is now reported when running the executable without +any arguments. diff --git a/Help/guide/tutorial/Adding Export Configuration.rst b/Help/guide/tutorial/Adding Export Configuration.rst index e5ab6a226..3bd6d6464 100644 --- a/Help/guide/tutorial/Adding Export Configuration.rst +++ b/Help/guide/tutorial/Adding Export Configuration.rst @@ -12,10 +12,10 @@ packaged. The first step is to update our :command:`install(TARGETS)` commands to not only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword -generates and installs a CMake file containing code to import all targets -listed in the install command from the installation tree. So let's go ahead and -explicitly ``EXPORT`` the ``MathFunctions`` library by updating the ``install`` -command in ``MathFunctions/CMakeLists.txt`` to look like: +generates a CMake file containing code to import all targets listed in the +install command from the installation tree. So let's go ahead and explicitly +``EXPORT`` the ``MathFunctions`` library by updating the ``install`` command +in ``MathFunctions/CMakeLists.txt`` to look like: .. literalinclude:: Complete/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt @@ -82,6 +82,46 @@ bottom of the top-level ``CMakeLists.txt``: :name: CMakeLists.txt-install-Config.cmake :language: cmake :start-after: # install the configuration targets + :end-before: # generate the config file + + +Next, we execute the :command:`configure_package_config_file`. This command +will configure a provided file but with a few specific differences from the +standard :command:`configure_file` way. +To properly utilize this function, the input file should have a single line +with the text ``@PACKAGE_INIT@`` in addition to the content that is desired. +That variable will be replaced with a block of code which turns set values into +relative paths. These values which are new can be referenced by the same name +but prepended with a ``PACKAGE_`` prefix. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-configure-package-config.cmake + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the version file + +The :command:`write_basic_package_version_file` is next. This command writes +a file which is used by the "find_package" document the version and +compatibility of the desired package. Here, we use the ``Tutorial_VERSION_*`` +variables and say that it is compatible with ``AnyNewerVersion``, which +denotes that this version or any higher one are compatible with the requested +version. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-basic-version-file.cmake + :language: cmake + :start-after: # generate the version file + :end-before: # install the generated configuration files + +Finally, set both generated files to be installed: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-configured-files.cmake + :language: cmake + :start-after: # install the generated configuration files :end-before: # generate the export At this point, we have generated a relocatable CMake Configuration for our diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst index 55acb346f..7fcc97fcc 100644 --- a/Help/guide/tutorial/Adding Generator Expressions.rst +++ b/Help/guide/tutorial/Adding Generator Expressions.rst @@ -53,6 +53,16 @@ Would be replaced with: :start-after: project(Tutorial VERSION 1.0) :end-before: # add compiler warning flags just when building this project via +**Note**: This upcoming section will require a change to the +:command:`cmake_minimum_required` usage in the code. The Generator Expression +that is about to be used was introduced in `3.15`. Update the call to require +that more recent version: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-version-update + + cmake_minimum_required(VERSION 3.15) Next we add the desired compiler warning flags that we want for our project. As warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID`` diff --git a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst index 26aae4f81..c6e0fd0b3 100644 --- a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst +++ b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst @@ -28,9 +28,23 @@ With: The :module:`CTest` module will automatically call ``enable_testing()``, so we can remove it from our CMake files. -We will also need to create a ``CTestConfig.cmake`` file in the top-level -directory where we can specify the name of the project and where to submit the -dashboard. +We will also need to acquire a ``CTestConfig.cmake`` file to be placed in the +top-level directory where we can specify information to CTest about the +project. It contains: + +* The project name + +* The project "Nightly" start time + + * The time when a 24 hour "day" starts for this project. + +* The URL of the CDash instance where the submission's generated documents + will be sent + +One has been provided for you in this directory. It would normally be +downloaded from the ``Settings`` page of the project on the CDash +instance that will host and display the test results. Once downloaded from +CDash, the file should not be modified locally. .. literalinclude:: Step9/CTestConfig.cmake :caption: CTestConfig.cmake diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst index 7210a8dbc..e14911008 100644 --- a/Help/guide/tutorial/Adding System Introspection.rst +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -14,11 +14,14 @@ these functions using the :module:`CheckSymbolExists` module in the ``m`` library. If ``log`` and ``exp`` are not initially found, require the ``m`` library and try again. +Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``, +after the call to :command:`target_include_directories`: + .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-check_symbol_exists :language: cmake - :start-after: # does this system provide the log and exp functions? + :start-after: # to find MathFunctions.h, while we don't. :end-before: # add compile definitions If available, use :command:`target_compile_definitions` to specify diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index 180636141..ed034489c 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst @@ -64,8 +64,13 @@ will be stored in the cache so that the user does not need to set the value each time they run CMake on a build directory. The next change is to make building and linking the ``MathFunctions`` library -conditional. To do this we change the end of the top-level ``CMakeLists.txt`` -file to look like the following: +conditional. To do this, we will create an ``if`` statement which checks the +value of the option. Inside the ``if`` block, put the +:command:`add_subdirectory` command from above with some additional list +commands to store information needed to link to the library and add the +subdirectory as an include directory in the ``Tutorial`` target. +The end of the top-level ``CMakeLists.txt`` file will now look like the +following: .. literalinclude:: Step3/CMakeLists.txt :caption: CMakeLists.txt diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index 4d8a3ada8..ac1d0839a 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -73,7 +73,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -81,7 +81,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst index 2fc3202e5..394c9865f 100644 --- a/Help/guide/tutorial/Installing and Testing.rst +++ b/Help/guide/tutorial/Installing and Testing.rst @@ -88,6 +88,8 @@ input, and expected results based on the passed arguments. Rebuild the application and then cd to the binary directory and run the :manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual Studio), the configuration type must be -specified. To run tests in Debug mode, for example, use ``ctest -C Debug -VV`` -from the build directory (not the Debug subdirectory!). Alternatively, build -the ``RUN_TESTS`` target from the IDE. +specified with the ``-C <mode>`` flag. For example, to run tests in Debug +mode use ``ctest -C Debug -VV`` from the binary directory +(not the Debug subdirectory!). Release mode would be executed from the same +location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS`` +target from the IDE. diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index 34ae70c27..dc9a0e8e6 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -55,7 +55,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -63,7 +63,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt index 4763951c7..10f35ce2d 100644 --- a/Help/guide/tutorial/Step11/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -63,7 +63,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -71,7 +71,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt index 1b0c82667..634b84cdd 100644 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -69,7 +69,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -77,7 +77,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) @@ -107,7 +107,7 @@ write_basic_package_version_file( COMPATIBILITY AnyNewerVersion ) -# install the configuration file +# install the generated configuration files install(FILES ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index c3b375a3d..82d00c8d4 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index c3b375a3d..82d00c8d4 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index c3b375a3d..82d00c8d4 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index 19b9913e9..4ae898f9b 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,7 +62,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") # setup installer diff --git a/Help/guide/tutorial/Step8/CTestConfig.cmake b/Help/guide/tutorial/Step8/CTestConfig.cmake new file mode 100644 index 000000000..73efdb1f6 --- /dev/null +++ b/Help/guide/tutorial/Step8/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index d5f1cc897..130bc9a20 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,7 +62,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 70083833d..2f430705e 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,9 +21,9 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. -Dependencies between binary targets are expressed using the -:command:`target_link_libraries` command: +appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the +platform targeted. Dependencies between binary targets are expressed using +the :command:`target_link_libraries` command: .. code-block:: cmake @@ -530,38 +530,6 @@ the calculated "compatible" value of a property may be read with the In this case, the ``exe1`` source files will be compiled with ``-DCONTAINER_SIZE=200``. -Configuration determined build specifications may be conveniently set using -the ``CONFIG`` generator expression. - -.. code-block:: cmake - - target_compile_definitions(exe1 PRIVATE - $<$<CONFIG:Debug>:DEBUG_BUILD> - ) - -The ``CONFIG`` parameter is compared case-insensitively with the configuration -being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of -:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also -accounted for by this expression. - -Some buildsystems generated by :manual:`cmake(1)` have a predetermined -build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The -buildsystem for the IDEs such as Visual Studio and Xcode are generated -independent of the build-configuration, and the actual build configuration -is not known until build-time. Therefore, code such as - -.. code-block:: cmake - - string(TOLOWER ${CMAKE_BUILD_TYPE} _type) - if (_type STREQUAL debug) - target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) - endif() - -may appear to work for :ref:`Makefile Generators` and :generator:`Ninja` -generators, but is not portable to IDE generators. Additionally, -the :prop_tgt:`IMPORTED` configuration-mappings are not accounted for -with code like this, so it should be avoided. - The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY`` generator expression are evaluated with the consuming target context. This means that a usage requirement specification may be evaluated differently based @@ -840,6 +808,121 @@ target at a time. The commands :command:`add_compile_definitions`, a similar function, but operate at directory scope instead of target scope for convenience. +.. _`Build Configurations`: + +Build Configurations +==================== + +Configurations determine specifications for a certain type of build, such +as ``Release`` or ``Debug``. The way this is specified depends on the type +of :manual:`generator <cmake-generators(7)>` being used. For single +configuration generators like :ref:`Makefile Generators` and +:generator:`Ninja`, the configuration is specified at configure time by the +:variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators +like :ref:`Visual Studio <Visual Studio Generators>`, :generator:`Xcode`, and +:generator:`Ninja Multi-Config`, the configuration is chosen by the user at +build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the +multi-configuration case, the set of *available* configurations is specified +at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable, +but the actual configuration used cannot be known until the build stage. +This difference is often misunderstood, leading to problematic code like the +following: + +.. code-block:: cmake + + # WARNING: This is wrong for multi-config generators because they don't use + # and typically don't even set CMAKE_BUILD_TYPE + string(TOLOWER ${CMAKE_BUILD_TYPE} build_type) + if (build_type STREQUAL debug) + target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) + endif() + +:manual:`Generator expressions <cmake-generator-expressions(7)>` should be +used instead to handle configuration-specific logic correctly, regardless of +the generator used. For example: + +.. code-block:: cmake + + # Works correctly for both single and multi-config generators + target_compile_definitions(exe1 PRIVATE + $<$<CONFIG:Debug>:DEBUG_BUILD> + ) + +In the presence of :prop_tgt:`IMPORTED` targets, the content of +:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also +accounted for by the above ``$<CONFIG:Debug>`` expression. + + +Case Sensitivity +---------------- + +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are +just like other variables in that any string comparisons made with their +values will be case-sensitive. The ``$<CONFIG>`` generator expression also +preserves the casing of the configuration as set by the user or CMake defaults. +For example: + +.. code-block:: cmake + + # NOTE: Don't use these patterns, they are for illustration purposes only. + + set(CMAKE_BUILD_TYPE Debug) + if(CMAKE_BUILD_TYPE STREQUAL DEBUG) + # ... will never get here, "Debug" != "DEBUG" + endif() + add_custom_target(print_config ALL + # Prints "Config is Debug" in this single-config case + COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>" + VERBATIM + ) + + set(CMAKE_CONFIGURATION_TYPES Debug Release) + if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES) + # ... will never get here, "Debug" != "DEBUG" + endif() + +In contrast, CMake treats the configuration type case-insensitively when +using it internally in places that modify behavior based on the configuration. +For example, the ``$<CONFIG:Debug>`` generator expression will evaluate to 1 +for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or +even ``DeBuG``. Therefore, you can specify configuration types in +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with +any mixture of upper and lowercase, although there are strong conventions +(see the next section). If you must test the value in string comparisons, +always convert the value to upper or lowercase first and adjust the test +accordingly. + +Default And Custom Configurations +--------------------------------- + +By default, CMake defines a number of standard configurations: + +* ``Debug`` +* ``Release`` +* ``RelWithDebInfo`` +* ``MinSizeRel`` + +In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable +will be populated with (potentially a subset of) the above list by default, +unless overridden by the project or user. The actual configuration used is +selected by the user at build time. + +For single-config generators, the configuration is specified with the +:variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed +at build time. The default value will often be none of the above standard +configurations and will instead be an empty string. A common misunderstanding +is that this is the same as ``Debug``, but that is not the case. Users should +always explicitly specify the build type instead to avoid this common problem. + +The above standard configuration types provide reasonable behavior on most +platforms, but they can be extended to provide other types. Each configuration +defines a set of compiler and linker flag variables for the language in use. +These variables follow the convention :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`, +where ``<CONFIG>`` is always the uppercase configuration name. When defining +a custom configuration type, make sure these variables are set appropriately, +typically as cache variables. + + Pseudo Targets ============== diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 2b0de1101..67b0f6ec7 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -118,13 +118,12 @@ as well as any dependents (that may include headers from ``mylib``). Availability of Compiler Extensions ----------------------------------- -Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, -CMake uses extended variants of language dialects by default, such as -``-std=gnu++11`` instead of ``-std=c++11``. That target property may be -set to ``OFF`` to use the non-extended variant of the dialect flag. Note -that because most compilers enable extensions by default, this could -expose cross-platform bugs in user code or in the headers of third-party -dependencies. +The :prop_tgt:`<LANG>_EXTENSIONS` target property defaults to the compiler's +default (see :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`). Note that because +most compilers enable extensions by default, this may expose portability bugs +in user code or in the headers of third-party dependencies. + +:prop_tgt:`<LANG>_EXTENSIONS` used to default to ``ON``. See :policy:`CMP0128`. Optional Compile Features ========================= diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index fa38588a8..0799fddb6 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -30,12 +30,15 @@ Environment Variables that Control the Build /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_LANG_LINKER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index d3cbd491c..df13dd0ae 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -134,8 +134,8 @@ Variable Queries .. genex:: $<CONFIG:cfgs> - ``1`` if config is any one of the entries in ``cfgs``, else ``0``. This is a - case-insensitive comparison. The mapping in + ``1`` if config is any one of the entries in comma-separated list + ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 4b2934a8e..5c109ff67 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -74,7 +74,9 @@ package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``<PackageName>`` package will not be searched, and will always -be ``NOTFOUND``. +be ``NOTFOUND``. Likewise, setting the +:variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` to ``TRUE`` will make the +package REQUIRED. .. _`Config File Packages`: @@ -447,7 +449,7 @@ be true. This can be tested with logic in the package configuration file: set(_supported_components Plot Table) foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) - if (NOT ";${_supported_components};" MATCHES _comp) + if (NOT ";${_supported_components};" MATCHES ";${_comp};") set(ClimbingStats_FOUND False) set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index b9e3d452f..3df4f9fa7 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,15 @@ 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.22 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0128: Selection of language standard and extension flags improved. </policy/CMP0128> + CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127> + Policies Introduced by CMake 3.21 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 5f18a8247..bb5dba3f0 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -202,6 +202,7 @@ Properties on Targets /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER + /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/Fortran_PREPROCESS @@ -214,6 +215,9 @@ Properties on Targets /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/HIP_ARCHITECTURES + /prop_tgt/HIP_EXTENSIONS + /prop_tgt/HIP_STANDARD + /prop_tgt/HIP_STANDARD_REQUIRED /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME @@ -273,8 +277,11 @@ Properties on Targets /prop_tgt/LANG_COMPILER_LAUNCHER /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT + /prop_tgt/LANG_EXTENSIONS /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_LINKER_LAUNCHER + /prop_tgt/LANG_STANDARD + /prop_tgt/LANG_STANDARD_REQUIRED /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -450,6 +457,7 @@ Properties on Tests /prop_test/DEPENDS /prop_test/DISABLED /prop_test/ENVIRONMENT + /prop_test/ENVIRONMENT_MODIFICATION /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_REQUIRED diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9cea0fbc1..4ed0b2e62 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -71,6 +71,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR + /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -124,6 +125,9 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION + /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION + /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER + /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM @@ -231,6 +235,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -246,6 +251,7 @@ Variables that Change Behavior /variable/CMAKE_SYSTEM_LIBRARY_PATH /variable/CMAKE_SYSTEM_PREFIX_PATH /variable/CMAKE_SYSTEM_PROGRAM_PATH + /variable/CMAKE_TLS_CAINFO /variable/CMAKE_TLS_VERIFY /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED @@ -428,6 +434,7 @@ Variables that Control the Build /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -438,6 +445,7 @@ Variables that Control the Build /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_WHAT_YOU_USE + /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG @@ -525,6 +533,9 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG /variable/CMAKE_HIP_ARCHITECTURES + /variable/CMAKE_HIP_EXTENSIONS + /variable/CMAKE_HIP_STANDARD + /variable/CMAKE_HIP_STANDARD_REQUIRED /variable/CMAKE_ISPC_HEADER_DIRECTORY /variable/CMAKE_ISPC_HEADER_SUFFIX /variable/CMAKE_ISPC_INSTRUCTION_SETS @@ -546,6 +557,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_EXTENSIONS + /variable/CMAKE_LANG_EXTENSIONS_DEFAULT /variable/CMAKE_LANG_FLAGS /variable/CMAKE_LANG_FLAGS_CONFIG /variable/CMAKE_LANG_FLAGS_CONFIG_INIT @@ -574,8 +587,11 @@ Variables for Languages /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS + /variable/CMAKE_LANG_STANDARD + /variable/CMAKE_LANG_STANDARD_DEFAULT /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_LANG_STANDARD_REQUIRED /variable/CMAKE_OBJC_EXTENSIONS /variable/CMAKE_OBJC_STANDARD /variable/CMAKE_OBJC_STANDARD_REQUIRED diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 03d8bf6c8..d66c5a9d5 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -464,6 +464,10 @@ CTest prints timing summary information for each ``LABEL`` and subproject associated with the tests run. The label time summary will not include labels that are mapped to subprojects. +.. versionadded:: 3.22 + Labels added dynamically during test execution are also reported in the + timing summary. See :ref:`Additional Labels`. + When the :prop_test:`PROCESSORS` test property is set, CTest will display a weighted test timing result in label and subproject summaries. The time is reported with `sec*proc` instead of just `sec`. diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 767e80b6b..7852550dc 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -124,7 +124,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -446,7 +446,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of build presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of build presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -641,7 +641,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of test presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of test presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", diff --git a/Help/policy/CMP0127.rst b/Help/policy/CMP0127.rst new file mode 100644 index 000000000..2106110d4 --- /dev/null +++ b/Help/policy/CMP0127.rst @@ -0,0 +1,34 @@ +CMP0127 +------- + +.. versionadded:: 3.22 + +:command:`cmake_dependent_option` supports full :ref:`Condition Syntax`. + +The ``<depends>`` parameter accepts a :ref:`semicolon-separated list <CMake +Language Lists>` of conditions. CMake 3.21 and lower evaluates each +``condition`` as ``if(${condition})``, which does not properly handle +conditions with nested paren groups. CMake 3.22 and above instead prefer +to evaluate each ``condition`` as ``if(<condition>)``, where ``<condition>`` +is re-parsed as if literally written in a call to :command:`if`. This +allows expressions like:: + + "A AND (B OR C)" + +but requires expressions like:: + + "FOO MATCHES (UPPER|lower)" + +to be re-written as:: + + "FOO MATCHES \"(UPPER|lower)\"" + +Policy ``CMP0127`` provides compatibility for projects that have not +been updated to expect the new behavior. + +This policy was introduced in CMake version 3.22. 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/CMP0128.rst b/Help/policy/CMP0128.rst new file mode 100644 index 000000000..604a146a1 --- /dev/null +++ b/Help/policy/CMP0128.rst @@ -0,0 +1,71 @@ +CMP0128 +------- + +.. versionadded:: 3.22 + +When this policy is set to ``NEW``: + +* :prop_tgt:`<LANG>_EXTENSIONS` is initialized to + :variable:`CMAKE_<LANG>_EXTENSIONS` if set, otherwise falling back to + :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`. + +* Extensions are correctly enabled/disabled if :prop_tgt:`<LANG>_STANDARD` is + unset or satisfied by the default. + +* Standard mode-affecting flags aren't added unless necessary to achieve the + specified mode. + +The ``OLD`` behavior: + +* Initializes :prop_tgt:`<LANG>_EXTENSIONS` to + :variable:`CMAKE_<LANG>_EXTENSIONS` if set, otherwise falling back to ``ON``. + +* Always adds a flag if :prop_tgt:`<LANG>_STANDARD` is set and + :prop_tgt:`<LANG>_STANDARD_REQUIRED` is ``OFF``. + +* If :prop_tgt:`<LANG>_STANDARD` is unset: + + * Doesn't disable extensions even if :prop_tgt:`<LANG>_EXTENSIONS` is + ``OFF``. + + * Fails to enable extensions if :prop_tgt:`<LANG>_EXTENSIONS` is ``ON`` + except for the ``IAR`` compiler. + +Code may need to be updated for the ``NEW`` behavior in the following cases: + +* If a standard mode flag previously overridden by CMake's and not used during + compiler detection now takes effect due to CMake no longer adding one as the + default detected is appropriate. + + Such code should be converted to either: + + * Use :prop_tgt:`<LANG>_STANDARD` and :prop_tgt:`<LANG>_EXTENSIONS` instead + of manually adding flags. + + * Or ensure the manually-specified flags are used during compiler detection. + +* If extensions were disabled without :prop_tgt:`<LANG>_STANDARD` being set + CMake previously wouldn't actually disable extensions. + + Such code should be updated to not disable extensions if they are required. + +* If extensions were enabled/disabled when :prop_tgt:`<LANG>_STANDARD` was + satisfied by the compiler's default CMake previously wouldn't actually + enable/disable extensions. + + Such code should be updated to set the correct extensions mode. + +If compiler flags affecting the standard mode are used during compiler +detection (for example in :manual:`a toolchain file <cmake-toolchains(7)>` +using :variable:`CMAKE_<LANG>_FLAGS_INIT`) then they will affect the detected +default :variable:`standard <CMAKE_<LANG>_STANDARD_DEFAULT>` and +:variable:`extensions <CMAKE_<LANG>_EXTENSIONS_DEFAULT>`. + +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses the ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0128 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst index 6bbb870f1..3a1797356 100644 --- a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -32,4 +32,6 @@ The features known to this version of CMake are: Compiler mode is at least CUDA/C++ 20. ``cuda_std_23`` + .. versionadded:: 3.20 + Compiler mode is at least CUDA/C++ 23. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 73c0b34ee..1a913fb65 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -18,6 +18,8 @@ The features known to this version of CMake are listed below. High level meta features indicating C++ standard support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 3.8 + The following meta features indicate general support for the associated language standard. It reflects the language support claimed by the compiler, but it does not necessarily imply complete conformance to that standard. @@ -35,9 +37,13 @@ but it does not necessarily imply complete conformance to that standard. Compiler mode is at least C++ 17. ``cxx_std_20`` + .. versionadded:: 3.12 + Compiler mode is at least C++ 20. ``cxx_std_23`` + .. versionadded:: 3.20 + Compiler mode is at least C++ 23. Low level individual compile features diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 2bd0febea..97da697e0 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -13,7 +13,12 @@ The features listed here may be used with the :command:`target_compile_features` command. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -The features known to this version of CMake are: +The features known to this version of CMake are listed below. + +High level meta features indicating C standard support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.8 ``c_std_90`` Compiler mode is at least C 90. @@ -25,11 +30,18 @@ The features known to this version of CMake are: Compiler mode is at least C 11. ``c_std_17`` + .. versionadded:: 3.21 + Compiler mode is at least C 17. ``c_std_23`` + .. versionadded:: 3.21 + Compiler mode is at least C 23. +Low level individual compile features +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_sf/VS_SETTINGS.rst b/Help/prop_sf/VS_SETTINGS.rst index 322f5a6d7..871e36e85 100644 --- a/Help/prop_sf/VS_SETTINGS.rst +++ b/Help/prop_sf/VS_SETTINGS.rst @@ -3,7 +3,12 @@ VS_SETTINGS .. versionadded:: 3.18 -Set any item metadata on a non-built file. +Set any item metadata on a file. + +.. versionadded:: 3.22 + + This property is honored for all source file types. + Previously it worked only for non-built files. Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator to set ``Key`` to ``Value`` as item metadata on the file. diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 102c7922f..43bcdbe1b 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -5,5 +5,5 @@ Specify environment variables that should be defined for running a test. If set to a list of environment variables and values of the form ``MYVAR=value`` those environment variables will be defined while running -the test. The environment is restored to its previous state after the -test is done. +the test. The environment changes from this property do not affect other +tests. diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst new file mode 100644 index 000000000..0b3cd83a4 --- /dev/null +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -0,0 +1,36 @@ +ENVIRONMENT_MODIFICATION +------------------------ + +.. versionadded:: 3.22 + +Specify environment variables that should be modified for running a test. Note +that the operations performed by this property are performed after the +:prop_test:`ENVIRONMENT` property is already applied. + +If set to a list of environment variables and values of the form +``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an +environment variable to be modified. Entries are considered in the +order specified in the property's value. The ``OP`` may be one of: + + - ``reset``: Reset to the unmodified value, ignoring all modifications to + ``MYVAR`` prior to this entry. Note that this will reset the variable to + the value set by :prop_test:`ENVIRONMENT`, if it was set, and otherwise + to its state from the rest of the CTest execution. + - ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``. + - ``unset``: Unsets the current value of ``MYVAR``. + - ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``. + - ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``. + - ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using the platform-specific list separator. + - ``path_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using the platform-specific list separator. + - ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using ``;`` as the separator. + - ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator. + +Unrecognized ``OP`` values will result in the test failing before it is +executed. This is so that future operations may be added without changing +valid behavior of existing tests. + +The environment changes from this property do not affect other tests. diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst index 8d7557095..a06f15274 100644 --- a/Help/prop_test/LABELS.rst +++ b/Help/prop_test/LABELS.rst @@ -1,6 +1,10 @@ LABELS ------ -Specify a list of text labels associated with a test. +Specify a list of text labels associated with a test. The labels are +reported in both the ``ctest`` output summary and in dashboard submissions. +They can also be used to filter the set of tests to be executed (see the +``ctest -L`` and ``ctest -LE`` :ref:`CTest Options`). -The list is reported in dashboard submissions. +See :ref:`Additional Labels` for adding labels to a test dynamically during +test execution. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 52d96e02f..ed8b2626b 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -4,9 +4,9 @@ AUTOMOC Should the target be processed with auto-moc (for Qt projects). :prop_tgt:`AUTOMOC` is a boolean specifying whether CMake will handle the Qt -``moc`` preprocessor automatically, i.e. without having to use the -:module:`QT4_WRAP_CPP() <FindQt4>` or ``QT5_WRAP_CPP()`` macro. -Currently Qt4 and Qt5 are supported. +``moc`` preprocessor automatically, i.e. without having to use commands like +:module:`QT4_WRAP_CPP() <FindQt4>`, ``QT5_WRAP_CPP()``, etc. +Currently, Qt versions 4 to 6 are supported. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. @@ -148,10 +148,13 @@ Qt version detection :prop_tgt:`AUTOMOC` enabled targets need to know the Qt major and minor version they're working with. The major version usually is provided by the -``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[45]Core`` library, +``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[456]Core`` library, that the target links to. To find the minor version, CMake builds a list of available Qt versions from +- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` variables + (usually set by ``find_package(Qt6...)``) +- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` directory properties - ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` variables (usually set by ``find_package(Qt5...)``) - ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` directory properties @@ -167,13 +170,13 @@ version was found, an error is generated. If ``INTERFACE_QT_MAJOR_VERSION`` is not a valid number, the first entry in the list is taken. -A ``find_package(Qt[45]...)`` call sets the ``QT/Qt5Core_VERSION_MAJOR/MINOR`` +A ``find_package(Qt[456]...)`` call sets the ``QT/Qt[56]Core_VERSION_MAJOR/MINOR`` variables. If the call is in a different context than the :command:`add_executable` or :command:`add_library` call, e.g. in a function, then the version variables might not be available to the :prop_tgt:`AUTOMOC` enabled target. In that case the version variables can be forwarded from the -``find_package(Qt[45]...)`` calling context to the :command:`add_executable` +``find_package(Qt[456]...)`` calling context to the :command:`add_executable` or :command:`add_library` calling context as directory properties. The following Qt5 example demonstrates the procedure. diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index 9a98f440c..0a0c2a119 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -5,8 +5,8 @@ Should the target be processed with auto-rcc (for Qt projects). :prop_tgt:`AUTORCC` is a boolean specifying whether CMake will handle the Qt ``rcc`` code generator automatically, i.e. without having to use -the :module:`QT4_ADD_RESOURCES() <FindQt4>` or ``QT5_ADD_RESOURCES()`` -macro. Currently Qt4 and Qt5 are supported. +commands like :module:`QT4_ADD_RESOURCES() <FindQt4>`, ``QT5_ADD_RESOURCES()``, +etc. Currently, Qt versions 4 to 6 are supported. When this property is ``ON``, CMake will handle ``.qrc`` files added as target sources at build time and invoke ``rcc`` accordingly. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index cd24f5e59..e0cea97a0 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -5,8 +5,8 @@ Should the target be processed with auto-uic (for Qt projects). :prop_tgt:`AUTOUIC` is a boolean specifying whether CMake will handle the Qt ``uic`` code generator automatically, i.e. without having to use -the :module:`QT4_WRAP_UI() <FindQt4>` or ``QT5_WRAP_UI()`` macro. Currently -Qt4 and Qt5 are supported. +commands like :module:`QT4_WRAP_UI() <FindQt4>`, ``QT5_WRAP_UI()``, etc. +Currently, Qt versions 4 to 6 are supported. This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` variable if it is set when a target is created. diff --git a/Help/prop_tgt/CUDA_EXTENSIONS.rst b/Help/prop_tgt/CUDA_EXTENSIONS.rst index 2ddba0b41..ab467ac40 100644 --- a/Help/prop_tgt/CUDA_EXTENSIONS.rst +++ b/Help/prop_tgt/CUDA_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_CUDA_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_CUDA_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_CUDA_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst index 5ef57be70..950ba12e6 100644 --- a/Help/prop_tgt/CUDA_STANDARD.rst +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -12,21 +12,27 @@ flag such as ``-std=gnu++11`` to the compile line. Supported values are: ``98`` - CUDA C++98 + CUDA C++98. Note that this maps to the same as ``03`` internally. + +``03`` + CUDA C++03 ``11`` CUDA C++11 ``14`` - CUDA C++14 + CUDA C++14. While CMake 3.8 and later *recognize* ``14`` as a valid value, + CMake 3.9 was the first version to include support for any compiler. ``17`` - CUDA C++17 + CUDA C++17. While CMake 3.8 and later *recognize* ``17`` as a valid value, + CMake 3.18 was the first version to include support for any compiler. ``20`` .. versionadded:: 3.12 - CUDA C++20 + CUDA C++20. While CMake 3.12 and later *recognize* ``20`` as a valid value, + CMake 3.18 was the first version to include support for any compiler. ``23`` .. versionadded:: 3.20 @@ -43,7 +49,7 @@ means that using: with a compiler which does not support ``-std=gnu++11`` or an equivalent flag will not result in an error or warning, but will instead add the -``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +``-std=gnu++03`` flag if supported. This "decay" behavior may be controlled with the :prop_tgt:`CUDA_STANDARD_REQUIRED` target property. Additionally, the :prop_tgt:`CUDA_EXTENSIONS` target property may be used to control whether compiler-specific extensions are enabled on a per-target basis. diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst index bda531ec0..9b52504ef 100644 --- a/Help/prop_tgt/CXX_EXTENSIONS.rst +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_CXX_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_CXX_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_CXX_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst index b2abb462f..a53090c57 100644 --- a/Help/prop_tgt/C_EXTENSIONS.rst +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_C_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_C_EXTENSIONS` variable if set when a target is created and +otherwise by the value of +:variable:`CMAKE_C_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst new file mode 100644 index 000000000..3533ef9c8 --- /dev/null +++ b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst @@ -0,0 +1,16 @@ +Fortran_BUILDING_INSTRINSIC_MODULES +----------------------------------- + +.. versionadded:: 3.22 + +Instructs the CMake Fortran preprocessor that the target is building +Fortran intrinsics for building a Fortran compiler. + +This property is off by default and should be turned only on projects +that build a Fortran compiler. It should not be turned on for projects +that use a Fortran compiler. + +Turning this property on will correctly add dependencies for building +Fortran intrinsic modules whereas turning the property off will ignore +Fortran intrinsic modules in the dependency graph as they are supplied +by the compiler itself. diff --git a/Help/prop_tgt/HIP_EXTENSIONS.rst b/Help/prop_tgt/HIP_EXTENSIONS.rst new file mode 100644 index 000000000..d1475c964 --- /dev/null +++ b/Help/prop_tgt/HIP_EXTENSIONS.rst @@ -0,0 +1,21 @@ +HIP_EXTENSIONS +-------------- + +.. versionadded:: 3.21 + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic HIP/C++ standard level is +controlled by the :prop_tgt:`HIP_STANDARD` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_HIP_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/HIP_STANDARD.rst b/Help/prop_tgt/HIP_STANDARD.rst new file mode 100644 index 000000000..0c767c629 --- /dev/null +++ b/Help/prop_tgt/HIP_STANDARD.rst @@ -0,0 +1,48 @@ +HIP_STANDARD +------------ + +.. versionadded:: 3.21 + +The HIP/C++ standard requested to build this target. + +Supported values are: + +``98`` + HIP C++98 + +``11`` + HIP C++11 + +``14`` + HIP C++14 + +``17`` + HIP C++17 + +``20`` + HIP C++20 + +``23`` + HIP C++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 +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY HIP_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`HIP_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`HIP_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst b/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..e56209a3c --- /dev/null +++ b/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst @@ -0,0 +1,19 @@ +HIP_STANDARD_REQUIRED +--------------------- + +.. versionadded:: 3.21 + +Boolean describing whether the value of :prop_tgt:`HIP_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`HIP_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`HIP_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/LANG_EXTENSIONS.rst b/Help/prop_tgt/LANG_EXTENSIONS.rst new file mode 100644 index 000000000..afc2ad367 --- /dev/null +++ b/Help/prop_tgt/LANG_EXTENSIONS.rst @@ -0,0 +1,24 @@ +<LANG>_EXTENSIONS +----------------- + +The variations are: + +* :prop_tgt:`C_EXTENSIONS` +* :prop_tgt:`CXX_EXTENSIONS` +* :prop_tgt:`CUDA_EXTENSIONS` +* :prop_tgt:`HIP_EXTENSIONS` +* :prop_tgt:`OBJC_EXTENSIONS` +* :prop_tgt:`OBJCXX_EXTENSIONS` + +These properties specify whether compiler-specific extensions are requested. + +These properties are initialized by the value of the +:variable:`CMAKE_<LANG>_EXTENSIONS` variable if it is set when a target is +created and otherwise by the value of +:variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT` (see :policy:`CMP0128`). + +For supported CMake versions see the respective pages. +To control language standard versions see :prop_tgt:`<LANG>_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LANG_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst new file mode 100644 index 000000000..bd377eccd --- /dev/null +++ b/Help/prop_tgt/LANG_STANDARD.rst @@ -0,0 +1,26 @@ +<LANG>_STANDARD +--------------- + +The variations are: + +* :prop_tgt:`C_STANDARD` +* :prop_tgt:`CXX_STANDARD` +* :prop_tgt:`CUDA_STANDARD` +* :prop_tgt:`HIP_STANDARD` +* :prop_tgt:`OBJC_STANDARD` +* :prop_tgt:`OBJCXX_STANDARD` + +These properties specify language standard versions which are requested. When a +newer standard is specified than is supported by the compiler, then it will +fallback to the latest supported standard. This "decay" behavior may be +controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property. + +These properties are initialized by the value of the +:variable:`CMAKE_<LANG>_STANDARD` variable if it is set when a target is +created. + +For supported values and CMake versions see the respective pages. +To control compiler-specific extensions see :prop_tgt:`<LANG>_EXTENSIONS`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..56ecef85f --- /dev/null +++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst @@ -0,0 +1,26 @@ +<LANG>_STANDARD_REQUIRED +------------------------ + +The variations are: + +* :prop_tgt:`C_STANDARD_REQUIRED` +* :prop_tgt:`CXX_STANDARD_REQUIRED` +* :prop_tgt:`CUDA_STANDARD_REQUIRED` +* :prop_tgt:`HIP_STANDARD_REQUIRED` +* :prop_tgt:`OBJC_STANDARD_REQUIRED` +* :prop_tgt:`OBJCXX_STANDARD_REQUIRED` + +These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a +requirement. When ``OFF`` or unset, the :prop_tgt:`<LANG>_STANDARD` target +property is treated as optional and may "decay" to a previous standard if the +requested is not available. + +These properties are initialized by the value of the +:variable:`CMAKE_<LANG>_STANDARD_REQUIRED` variable if it is set when a target +is created. + +For supported CMake versions see the respective pages. +To control language standard versions see :prop_tgt:`<LANG>_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst index 2ed93adfd..d6de0d49c 100644 --- a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -1,16 +1,22 @@ LINK_WHAT_YOU_USE ---------------------------- +----------------- .. versionadded:: 3.7 -This is a boolean option that when set to ``TRUE`` will automatically run -``ldd -r -u`` on the target after it is linked. In addition, the linker flag -``-Wl,--no-as-needed`` will be passed to the target with the link command so -that all libraries specified on the command line will be linked into the -target. This will result in the link producing a list of libraries that -provide no symbols used by this target but are being linked to it. -This is only applicable to executable and shared library targets and -will only work when ld and ldd accept the flags used. +This is a boolean option that, when set to ``TRUE``, will automatically run +contents of variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` on the target +after it is linked. In addition, the linker flag specified by variable +:variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` will be passed to the target +with the link command so that all libraries specified on the command line will +be linked into the target. This will result in the link producing a list of +libraries that provide no symbols used by this target but are being linked to +it. + +.. note:: + + For now, it is only supported for ``ELF`` platforms and is only applicable to + executable and shared or module library targets. This property will be + ignored for any other targets and configurations. This property is initialized by the value of the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set diff --git a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst index 8a254f20a..2a15dec90 100644 --- a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -18,5 +18,7 @@ If the property is not set, and the project has set the :prop_tgt:`CXX_EXTENSION the value of :prop_tgt:`CXX_EXTENSIONS` is set for :prop_tgt:`OBJCXX_EXTENSIONS`. This property is initialized by the value of -the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if set when a target is +created and otherwise by the value of +:variable:`CMAKE_OBJCXX_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/OBJC_EXTENSIONS.rst b/Help/prop_tgt/OBJC_EXTENSIONS.rst index ef1c7543c..cd72e5fcc 100644 --- a/Help/prop_tgt/OBJC_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -18,5 +18,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_OBJC_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_OBJC_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_OBJC_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst index 462d2be81..e1c6172b2 100644 --- a/Help/release/3.21.rst +++ b/Help/release/3.21.rst @@ -334,10 +334,3 @@ Changes made since CMake 3.21.0 include the following. * The :generator:`Visual Studio 17 2022` generator is now based on the "Visual Studio 2022" release candidates. Previously it was based on preview versions. - -3.21.5, 3.21.6, 3.21.7 ----------------------- - -These versions made no changes to documented features or interfaces. -Some implementation updates were made to support ecosystem changes -and/or fix regressions. diff --git a/Help/release/3.22.rst b/Help/release/3.22.rst new file mode 100644 index 000000000..fcb655d19 --- /dev/null +++ b/Help/release/3.22.rst @@ -0,0 +1,144 @@ +CMake 3.22 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.21 include the following. + +New Features +============ + +Commands +-------- + +* The :command:`cmake_host_system_information` command can now query + `OS identification variables`_ from the :file:`/etc/os-release` file. + +* The :command:`string(TIMESTAMP)` command now supports the ``%V`` + specifier for ISO 8601 week numbers. + +.. _`OS identification variables`: https://www.freedesktop.org/software/systemd/man/os-release.html + +Variables +--------- + +* The :envvar:`CMAKE_BUILD_TYPE` environment variable was added to + provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable. + +* The :envvar:`CMAKE_CONFIGURATION_TYPES` environment variable was added to + provide a default value for the :variable:`CMAKE_CONFIGURATION_TYPES` + variable. + +* The :envvar:`CMAKE_INSTALL_MODE` environment variable was added to + tell :command:`install` rules (implemented by :command:`file(INSTALL)`) + to install symbolic links instead of copying of files. + +* The :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` and + :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` variables were added to + control the linker flag and check used by the + :prop_tgt:`LINK_WHAT_YOU_USE` target property. + +* The :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable + was added to turn a non-REQUIRED :command:`find_package` call into + a REQUIRED one. + +Properties +---------- + +* The :prop_tgt:`<LANG>_EXTENSIONS` target property is now initialized to + :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`, detected from the compiler. + See :policy:`CMP0128`. + +* The :prop_sf:`VS_SETTINGS` source file property is now supported for + all source file types. Previously it worked only for non-built sources. + +Modules +------- + +* The :module:`CMakeDependentOption` module :command:`cmake_dependent_option` + macro now supports full :ref:`Condition Syntax`. + See policy :policy:`CMP0127`. + +* The :module:`FetchContent` module now passes through the + :variable:`CMAKE_TLS_VERIFY`, :variable:`CMAKE_TLS_CAINFO`, + :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables (when + defined) to the underlying :module:`ExternalProject` sub-build. + Previously, those variables were silently ignored by :module:`FetchContent`. + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules gained + a ``BLA_SIZEOF_INTEGER`` option to find a BLAS/LAPACK whose ABI + uses a specific integer size. + +* The :module:`FindJasper` module now provides an imported target. + +* The :module:`FindMatlab` module now provides imported targets. + +* The :module:`FindPkgConfig` module gained a :variable:`PKG_CONFIG_ARGN` + variable to specify arguments to ``pkg-config`` calls. + +* The :module:`GoogleTest` module :command:`gtest_discover_tests` + function gained a ``TEST_FILTER`` option to filter tests using + ``--gtest_filter`` during test discovery. + +* The :module:`UseSWIG` module, for :ref:`Visual Studio Generators`, + can now use the ``swig`` tool to generate implicit dependencies. + +CTest +----- + +* :manual:`ctest(1)` learned to recognize labels attached to a test at run time. + Previously it was only possible to attach labels to tests at configure time + by using the :prop_test:`LABELS` test property. + See :ref:`Additional Test Measurements` for more information. + +* :manual:`ctest(1)` learned to be able to modify the environment for a test + through the :prop_test:`ENVIRONMENT_MODIFICATION` property. This is allows + for updates to environment variables based on the environment present at + test time. + +* The :command:`ctest_memcheck` command now also generates a + :file:`DynamicAnalysis-Test.xml` file which may be used to submit test + results to CDash. + +CPack +----- + +* The :cpack_gen:`CPack DEB Generator` gained the + option to set :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` to ``zstd``, + which enables Zstandard compression for deb packages. + +* The :cpack_gen:`CPack NSIS Generator` gained a new + :variable:`CPACK_NSIS_IGNORE_LICENSE_PAGE` variable to suppress + the license page in the installer. + +* The :cpack_gen:`CPack RPM Generator` gained the + :variable:`CPACK_RPM_REQUIRES_EXCLUDE_FROM` option to avoid scanning + specific paths for dependencies. + +Deprecated and Removed Features +=============================== + +* The :generator:`Visual Studio 10 2010` generator is now deprecated + and will be removed in a future version of CMake. + +Other Changes +============= + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality now + correctly disables or enables compiler extensions when no standard level is + specified and avoids unnecessarily adding language standard flags if the + requested settings match the compiler's defaults. See :policy:`CMP0128`. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now ignores features for languages that are not enabled. + +* The :ref:`Ninja Generators` now implement the ``edit_cache`` target + using :manual:`ccmake(1)` if available. + +* The :generator:`Ninja` and :generator:`NMake Makefiles` generators + now use the MSVC ``-external:I`` flag for system includes. + This became available as of VS 16.10 (toolchain version 14.29.30037). + +* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later. diff --git a/Help/release/index.rst b/Help/release/index.rst index 75667e54f..3d2ed4310 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,7 @@ Releases .. toctree:: :maxdepth: 1 + 3.22 <3.22> 3.21 <3.21> 3.20 <3.20> 3.19 <3.19> diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst index 405f7d590..bb95436ad 100644 --- a/Help/variable/CMAKE_BUILD_TYPE.rst +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -1,25 +1,21 @@ CMAKE_BUILD_TYPE ---------------- -Specifies the build type on single-configuration generators. +Specifies the build type on single-configuration generators (e.g. +:ref:`Makefile Generators` or :generator:`Ninja`). Typical values include +``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, but custom +build types can also be defined. -This statically specifies what build type (configuration) will be -built in this build tree. Possible values are empty, ``Debug``, ``Release``, -``RelWithDebInfo``, ``MinSizeRel``, ... This variable is only meaningful to -single-configuration generators (such as :ref:`Makefile Generators` and -:generator:`Ninja`) i.e. those which choose a single configuration when CMake -runs to generate a build tree as opposed to multi-configuration generators -which offer selection of the build configuration within the generated build -environment. There are many per-config properties and variables -(usually following clean ``SOME_VAR_<CONFIG>`` order conventions), such as -``CMAKE_C_FLAGS_<CONFIG>``, specified as uppercase: -``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL|...]``. For example, -in a build tree configured to build type ``Debug``, CMake will see to -having :variable:`CMAKE_C_FLAGS_DEBUG <CMAKE_<LANG>_FLAGS_DEBUG>` settings get -added to the :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` settings. See -also :variable:`CMAKE_CONFIGURATION_TYPES`. +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_BUILD_TYPE` environment +variable is set, its value is used. Otherwise, a toolchain-specific +default is chosen when a language is enabled. The default value is often +an empty string, but this is usually not desirable and one of the other +standard build types is usually more appropriate. -Note that configuration names are case-insensitive. The value of this -variable will be the same as it is specified when invoking CMake. -For instance, if ``-DCMAKE_BUILD_TYPE=ReLeAsE`` is specified, then the -value of ``CMAKE_BUILD_TYPE`` will be ``ReLeAsE``. +Depending on the situation, the value of this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For multi-config generators, see :variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst index 8fcc79869..75ff8a12a 100644 --- a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst +++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst @@ -1,12 +1,20 @@ CMAKE_CONFIGURATION_TYPES ------------------------- -Specifies the available build types on multi-config generators. +Specifies the available build types (configurations) on multi-config +generators (e.g. :ref:`Visual Studio <Visual Studio Generators>`, +:generator:`Xcode`, or :generator:`Ninja Multi-Config`). Typical values +include ``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, +but custom build types can also be defined. -This specifies what build types (configurations) will be available -such as ``Debug``, ``Release``, ``RelWithDebInfo`` etc. This has reasonable -defaults on most platforms, but can be extended to provide other build -types. +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_CONFIGURATION_TYPES` +environment variable is set, its value is used. Otherwise, the default +value is generator-specific. -See :variable:`CMAKE_BUILD_TYPE` for specifying the configuration with -single-config generators. +Depending on the situation, the values in this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For single-config generators, see :variable:`CMAKE_BUILD_TYPE`. diff --git a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst index b86c0ea39..12749ce59 100644 --- a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst +++ b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_EXTENSIONS .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst index 798ab1e74..ee9395aef 100644 --- a/Help/variable/CMAKE_CUDA_STANDARD.rst +++ b/Help/variable/CMAKE_CUDA_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_STANDARD .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst index ae2f52f8b..0c85a04d7 100644 --- a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_STANDARD_REQUIRED .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst index ea8c4be70..017f503ae 100644 --- a/Help/variable/CMAKE_CXX_EXTENSIONS.rst +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_CXX_EXTENSIONS .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst index 8ef8c80e3..33eb89e03 100644 --- a/Help/variable/CMAKE_CXX_STANDARD.rst +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_CXX_STANDARD .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_STANDARD` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst index f7b2ae92e..1c6c0cc96 100644 --- a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_CXX_STANDARD_REQUIRED .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` target property if set when +a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst index fce8fc722..668052111 100644 --- a/Help/variable/CMAKE_C_EXTENSIONS.rst +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_C_EXTENSIONS .. versionadded:: 3.1 -Default value for :prop_tgt:`C_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`C_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_EXTENSIONS` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst index 64ef8ce29..ec1e5131e 100644 --- a/Help/variable/CMAKE_C_STANDARD.rst +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_C_STANDARD .. versionadded:: 3.1 -Default value for :prop_tgt:`C_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`C_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_STANDARD` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst index e70b6bd26..2bd9d51b5 100644 --- a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_C_STANDARD_REQUIRED .. versionadded:: 3.1 -Default value for :prop_tgt:`C_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`C_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_STANDARD_REQUIRED` target property if set when +a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst index ed600202c..f77e93916 100644 --- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -14,3 +14,5 @@ the package has already been found in a previous CMake run, the variables which have been stored in the cache will still be there. In that case it is recommended to remove the cache variables for this package from the cache using the cache editor or :manual:`cmake(1)` ``-U`` + +See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst index 4a64e33e9..c2c2609df 100644 --- a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst +++ b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst @@ -5,5 +5,8 @@ Suffixes to append when looking for libraries. This specifies what suffixes to add to library names when the :command:`find_library` command looks for libraries. On Windows systems this -is typically ``.lib`` and ``.dll``, meaning that when trying to find the -``foo`` library it will look for ``foo.dll`` etc. +is typically ``.lib`` and, depending on the compiler, ``.dll.a``, ``.a`` +(e.g. GCC and Clang), so when it tries to find the ``foo`` library, it will +look for ``[<prefix>]foo.lib`` and/or ``[<prefix>]foo[.dll].a``, depending on +the compiler used and the ``<prefix>`` specified in the +:variable:`CMAKE_FIND_LIBRARY_PREFIXES`. diff --git a/Help/variable/CMAKE_HIP_EXTENSIONS.rst b/Help/variable/CMAKE_HIP_EXTENSIONS.rst new file mode 100644 index 000000000..13987dcda --- /dev/null +++ b/Help/variable/CMAKE_HIP_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_EXTENSIONS +-------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD.rst b/Help/variable/CMAKE_HIP_STANDARD.rst new file mode 100644 index 000000000..5f1514586 --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD +------------------ + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD` target property if set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..5d35e4e28 --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD_REQUIRED +--------------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD_REQUIRED` target property if set when +a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst new file mode 100644 index 000000000..128b1fbbe --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst @@ -0,0 +1,18 @@ +CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT +-------------------------------------- + +.. versionadded:: 3.14 + +Identification string of the compiler frontend variant. + +Some compilers have multiple, different frontends for accepting command +line options. (For example ``Clang`` originally only had a frontend +compatible with the ``GNU`` compiler but since its port to Windows +(``Clang-Cl``) it now also supports a frontend compatible with ``MSVC``.) +When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_ID` for +the compiler whose frontend it resembles. + +.. note:: + In other words, this variable describes what command line options + and language extensions the compiler frontend expects. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_EXTENSIONS.rst new file mode 100644 index 000000000..3a32002f6 --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS.rst @@ -0,0 +1,20 @@ +CMAKE_<LANG>_EXTENSIONS +----------------------- + +The variations are: + +* :variable:`CMAKE_C_EXTENSIONS` +* :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_CUDA_EXTENSIONS` +* :variable:`CMAKE_HIP_EXTENSIONS` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` + +Default values for :prop_tgt:`<LANG>_EXTENSIONS` target properties if set when +a target is created. For the compiler's default setting see +:variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst new file mode 100644 index 000000000..a66453acb --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_EXTENSIONS_DEFAULT +------------------------------- + +.. versionadded:: 3.22 + +Compiler's default extensions mode. Used as the default for the +:prop_tgt:`<LANG>_EXTENSIONS` target property when +:variable:`CMAKE_<LANG>_EXTENSIONS` is not set (see :policy:`CMP0128`). + +This variable is read-only. Modifying it is undefined behavior. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst index e9e04be6e..081c4da6b 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -6,8 +6,20 @@ Implicit linker search path detected for language ``<LANG>``. Compilers typically pass directories containing language runtime libraries and default library search paths when they invoke a linker. These paths are implicit linker search directories for the compiler's -language. CMake automatically detects these directories for each -language and reports the results in this variable. +language. For each language enabled by the :command:`project` or +:command:`enable_language` command, CMake automatically detects these +directories and reports the results in this variable. + +When linking to a static library, CMake adds the implicit link directories +from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. Some toolchains read implicit directories from an environment variable such as ``LIBRARY_PATH``. If using such an environment variable, keep its value @@ -18,3 +30,5 @@ If policy :policy:`CMP0060` is not set to ``NEW``, then when a library in one of these directories is given by full path to :command:`target_link_libraries` CMake will generate the ``-l<name>`` form on link lines for historical purposes. + +See also the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES` variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst index ec164774b..0c25489ca 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst @@ -5,6 +5,20 @@ Implicit link libraries and flags detected for language ``<LANG>``. Compilers typically pass language runtime library names and other flags when they invoke a linker. These flags are implicit link -options for the compiler's language. CMake automatically detects -these libraries and flags for each language and reports the results in -this variable. +options for the compiler's language. For each language enabled +by the :command:`project` or :command:`enable_language` command, +CMake automatically detects these libraries and flags and reports +the results in this variable. + +When linking to a static library, CMake adds the implicit link libraries and +flags from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. + +See also the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES` variable. diff --git a/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst new file mode 100644 index 000000000..500453039 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG +----------------------------------- + +.. versionadded:: 3.22 + +Linker flag to be used to configure linker so that all specified libraries on +the command line will be linked into the target. + +See also variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK`. diff --git a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst index 15c87a186..3226352a2 100644 --- a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst +++ b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst @@ -1,9 +1,13 @@ CMAKE_<LANG>_SIMULATE_ID ------------------------ -Identification string of "simulated" compiler. +Identification string of the "simulated" compiler. Some compilers simulate other compilers to serve as drop-in replacements. When CMake detects such a compiler it sets this variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_ID` for the simulated compiler. + +.. note:: + In other words, this variable describes the ABI compatibility + of the generated code. diff --git a/Help/variable/CMAKE_LANG_STANDARD.rst b/Help/variable/CMAKE_LANG_STANDARD.rst new file mode 100644 index 000000000..0c41e1968 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_STANDARD +--------------------- + +The variations are: + +* :variable:`CMAKE_C_STANDARD` +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CUDA_STANDARD` +* :variable:`CMAKE_HIP_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD` + +Default values for :prop_tgt:`<LANG>_STANDARD` target properties if set when a +target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst new file mode 100644 index 000000000..eb63d208a --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_STANDARD_DEFAULT +----------------------------- + +.. versionadded:: 3.9 + +The compiler's default standard for the language ``<LANG>``. Empty if the +compiler has no conception of standard levels. diff --git a/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst new file mode 100644 index 000000000..d7fa9b69b --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_STANDARD_REQUIRED +------------------------------ + +The variations are: + +* :variable:`CMAKE_C_STANDARD_REQUIRED` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :variable:`CMAKE_CUDA_STANDARD_REQUIRED` +* :variable:`CMAKE_HIP_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` + +Default values for :prop_tgt:`<LANG>_STANDARD_REQUIRED` target properties if +set when a target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst index 06b3aa89b..bca4519a8 100644 --- a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -1,5 +1,5 @@ CMAKE_LINK_WHAT_YOU_USE ---------------------------------- +----------------------- .. versionadded:: 3.7 diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst new file mode 100644 index 000000000..e626641bc --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_WHAT_YOU_USE_CHECK +----------------------------- + +.. versionadded:: 3.22 + +Defines the command executed after the link step to check libraries usage. +This check is currently only defined on ``ELF`` platforms with value +``ldd -u -r``. + +See also :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` variables. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst index 2c64a8149..bddfca555 100644 --- a/Help/variable/CMAKE_NETRC.rst +++ b/Help/variable/CMAKE_NETRC.rst @@ -3,9 +3,11 @@ CMAKE_NETRC .. versionadded:: 3.11 -This variable is used to initialize the ``NETRC`` option for -:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the -module :module:`ExternalProject`. See those commands for additional -information. +This variable is used to initialize the ``NETRC`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst index 97a645efe..af98170b9 100644 --- a/Help/variable/CMAKE_NETRC_FILE.rst +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -3,9 +3,11 @@ CMAKE_NETRC_FILE .. versionadded:: 3.11 -This variable is used to initialize the ``NETRC_FILE`` option for -:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the -module :module:`ExternalProject`. See those commands for additional -information. +This variable is used to initialize the ``NETRC_FILE`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst index b5225ea68..46736aa7d 100644 --- a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_EXTENSIONS .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD.rst b/Help/variable/CMAKE_OBJCXX_STANDARD.rst index 98e462414..0913382a4 100644 --- a/Help/variable/CMAKE_OBJCXX_STANDARD.rst +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_STANDARD .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst index 4b5e77cf0..9afc4eab4 100644 --- a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_STANDARD_REQUIRED .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst index d6e3c7dc0..9df11f1c8 100644 --- a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_EXTENSIONS .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD.rst b/Help/variable/CMAKE_OBJC_STANDARD.rst index fde367dfd..0b9b63ff2 100644 --- a/Help/variable/CMAKE_OBJC_STANDARD.rst +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_STANDARD .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst index 8d26d952a..c74db55c1 100644 --- a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_STANDARD_REQUIRED .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index b991db2df..02316682e 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -2,8 +2,9 @@ CMAKE_POLICY_WARNING_CMP<NNNN> ------------------------------ Explicitly enable or disable the warning when CMake Policy ``CMP<NNNN>`` -is not set. This is meaningful only for the few policies that do not -warn by default: +has not been set explicitly by :command:`cmake_policy` or implicitly +by :command:`cmake_minimum_required`. This is meaningful +only for the policies that do not warn by default: * ``CMAKE_POLICY_WARNING_CMP0025`` controls the warning for policy :policy:`CMP0025`. @@ -31,6 +32,8 @@ warn by default: policy :policy:`CMP0116`. * ``CMAKE_POLICY_WARNING_CMP0126`` controls the warning for policy :policy:`CMP0126`. +* ``CMAKE_POLICY_WARNING_CMP0128`` controls the warning for + policy :policy:`CMP0128`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 000000000..893f1aec8 --- /dev/null +++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,14 @@ +CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> +---------------------------------------- + +.. versionadded:: 3.22 + +Variable for making :command:`find_package` call ``REQUIRED``. + +Every non-``REQUIRED`` :command:`find_package` call in a project can be +turned into ``REQUIRED`` by setting the variable +``CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>`` to ``TRUE``. +This can be used to assert assumptions about build environment and to +ensure the build will fail early if they do not hold. + +See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_TLS_CAINFO.rst b/Help/variable/CMAKE_TLS_CAINFO.rst new file mode 100644 index 000000000..07f63660d --- /dev/null +++ b/Help/variable/CMAKE_TLS_CAINFO.rst @@ -0,0 +1,9 @@ +CMAKE_TLS_CAINFO +---------------- + +Specify the default value for the :command:`file(DOWNLOAD)` and +:command:`file(UPLOAD)` commands' ``TLS_CAINFO`` options. +It is unset by default. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. diff --git a/Help/variable/CMAKE_TLS_VERIFY.rst b/Help/variable/CMAKE_TLS_VERIFY.rst index 24f8a256a..b22f1cefc 100644 --- a/Help/variable/CMAKE_TLS_VERIFY.rst +++ b/Help/variable/CMAKE_TLS_VERIFY.rst @@ -5,8 +5,8 @@ Specify the default value for the :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands' ``TLS_VERIFY`` options. If not set, the default is *off*. -This setting is also used by the :module:`ExternalProject` module -for internal calls to :command:`file(DOWNLOAD)`. +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. TLS verification can help provide confidence that one is connecting to the desired server. When downloading known content, one should diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst new file mode 100644 index 000000000..5ad589719 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER +------------------------------------ + +.. versionadded:: 3.22 + +Visual Studio target framework identifier. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkIdentifier`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst new file mode 100644 index 000000000..8dcb3a72b --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION +----------------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework targets version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkTargetsVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 000000000..5489f7919 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,17 @@ +CMAKE_VS_TARGET_FRAMEWORK_VERSION +--------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See the :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable +and :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property to +specify custom ``TargetFrameworkVersion`` values for project targets. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst index 59479af69..c642a9f1d 100644 --- a/Help/variable/MSVC_TOOLSET_VERSION.rst +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst @@ -17,7 +17,6 @@ Known toolset version numbers are:: 140 = VS 2015 (14.0) 141 = VS 2017 (15.0) 142 = VS 2019 (16.0) - 143 = VS 2022 (17.0) Compiler versions newer than those known to CMake will be reported as the latest known toolset version. |