diff options
Diffstat (limited to 'Help')
62 files changed, 835 insertions, 322 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index 96a55ee..5a3fd88 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -1073,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: @@ -1092,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 8388709..1a79a8a 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,10 +81,14 @@ 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. @@ -78,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 @@ -145,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 @@ -166,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 -^^^^^^^^^^^^^^^^^ - -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: +.. _`search procedure`: -``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``. +Config Mode Search Procedure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``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 @@ -474,6 +390,145 @@ Every non-REQUIRED ``find_package`` call can be disabled or made 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index 41e8479..cf1ec01 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 e5ab6a2..3bd6d64 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 Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst index 26aae4f..c6e0fd0 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 7210a8d..e149110 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 1806361..ed03448 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 4d8a3ad..ec6ff16 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -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/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index 34ae70c..f4f9e05 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -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 4763951..30580e6 100644 --- a/Help/guide/tutorial/Step11/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -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 1b0c826..53dccd7 100644 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -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 c3b375a..fb10f57 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -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 c3b375a..fb10f57 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -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 c3b375a..fb10f57 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -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 19b9913..89972fb 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -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 0000000..73efdb1 --- /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 d5f1cc8..d67209a 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -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-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 2b0de11..a0459fa 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -118,14 +118,13 @@ 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 +The :prop_tgt:`<LANG>_EXTENSIONS` target property defaults to the compiler's +efault. Note that because most compilers enable extensions by default, this +may expose cross-platform 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-policies.7.rst b/Help/manual/cmake-policies.7.rst index 0f0c0ab..3df4f9f 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ 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 c71e8ff..bb5dba3 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -215,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 @@ -274,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 diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7cfa0c8..17f04ab 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -247,6 +247,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 @@ -528,6 +529,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 @@ -549,6 +553,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 @@ -577,8 +583,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/policy/CMP0128.rst b/Help/policy/CMP0128.rst new file mode 100644 index 0000000..f341f24 --- /dev/null +++ b/Help/policy/CMP0128.rst @@ -0,0 +1,78 @@ +CMP0128 +------- + +.. versionadded:: 3.22 + +When this policy is set to ``NEW``: + +* :prop_tgt:`<LANG>_EXTENSIONS` is initialized to + :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`. + +* Extensions are correctly disabled/enabled if :prop_tgt:`<LANG>_STANDARD` is + unset. + +* Standard mode-affecting flags aren't added unless necessary to achieve the + specified mode. + +The ``OLD`` behavior: + +* Initializes :prop_tgt:`<LANG>_EXTENSIONS` 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 :prop_tgt:`<LANG>_EXTENSIONS` matches + :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT` or is unset and the compiler's + default satisfies :prop_tgt:`<LANG>_STANDARD` but the compiled code requires + the exact standard specified. + Such code should set :prop_tgt:`<LANG>_STANDARD_REQUIRED` to ``ON``. + + For example: + + .. code-block:: cmake + + cmake_minimum_required(VERSION |release|) + project(example C) + + add_executable(exe main.c) + set_property(TARGET exe PROPERTY C_STANDARD 99) + + If the compiler defaults to C11 then the standard specification for C99 is + satisfied and CMake will pass no flags. ``main.c`` will no longer compile if + it is incompatible with C11. + +* 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 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 6bbb870..3a17973 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 73c0b34..1a913fb 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 2bd0feb..97da697 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_tgt/HIP_EXTENSIONS.rst b/Help/prop_tgt/HIP_EXTENSIONS.rst new file mode 100644 index 0000000..b731753 --- /dev/null +++ b/Help/prop_tgt/HIP_EXTENSIONS.rst @@ -0,0 +1,19 @@ +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 it is set when a target +is created. diff --git a/Help/prop_tgt/HIP_STANDARD.rst b/Help/prop_tgt/HIP_STANDARD.rst new file mode 100644 index 0000000..0c767c6 --- /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 0000000..e56209a --- /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 0000000..2add21d --- /dev/null +++ b/Help/prop_tgt/LANG_EXTENSIONS.rst @@ -0,0 +1,23 @@ +<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. + +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 0000000..bd377ec --- /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 0000000..56ecef8 --- /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/release/dev/compile-features-standard-logic-rework.rst b/Help/release/dev/compile-features-standard-logic-rework.rst new file mode 100644 index 0000000..432a756 --- /dev/null +++ b/Help/release/dev/compile-features-standard-logic-rework.rst @@ -0,0 +1,10 @@ +compile-features-standard-logic-rework +-------------------------------------- + +* 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`. + +* :prop_tgt:`<LANG>_EXTENSIONS` is initialized to + :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`. See :policy:`CMP0128`. diff --git a/Help/release/dev/fetchcontent-CMAKE-vars-passthrough.rst b/Help/release/dev/fetchcontent-CMAKE-vars-passthrough.rst new file mode 100644 index 0000000..842c016 --- /dev/null +++ b/Help/release/dev/fetchcontent-CMAKE-vars-passthrough.rst @@ -0,0 +1,8 @@ +fetchcontent-CMAKE-vars-passthrough.rst +--------------------------------------- + +* 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`. diff --git a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst index b86c0ea..12749ce 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 798ab1e..ee9395a 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 ae2f52f..0c85a04d 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 ea8c4be..017f503 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 8ef8c80..33eb89e 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 f7b2ae9..1c6c0cc 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 fce8fc7..6680521 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 64ef8ce..ec1e513 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 e70b6bd..2bd9d51 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_FIND_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst index 4a64e33..c2c2609 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 0000000..13987dc --- /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 0000000..5f15145 --- /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 0000000..5d35e4e --- /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_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_EXTENSIONS.rst new file mode 100644 index 0000000..84e5e3a --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS.rst @@ -0,0 +1,19 @@ +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 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 0000000..6783eb5 --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_EXTENSIONS_DEFAULT +------------------------------- + +.. versionadded:: 3.22 + +Default value used when the :prop_tgt:`<LANG>_EXTENSIONS` target property is +not set. Initialized during compiler detection to the compiler's default. diff --git a/Help/variable/CMAKE_LANG_STANDARD.rst b/Help/variable/CMAKE_LANG_STANDARD.rst new file mode 100644 index 0000000..0c41e19 --- /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 0000000..eb63d20 --- /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 0000000..d7fa9b6 --- /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_NETRC.rst b/Help/variable/CMAKE_NETRC.rst index 2c64a81..bddfca5 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 97a645e..af98170 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 b5225ea..46736aa 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 98e4624..0913382 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 4b5e77c..9afc4ea 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 d6e3c7d..9df11f1 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 fde367d..0b9b63f 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 8d26d95..c74db55 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 11dd194..0231668 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -32,6 +32,8 @@ only for the policies that do not 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_TLS_CAINFO.rst b/Help/variable/CMAKE_TLS_CAINFO.rst new file mode 100644 index 0000000..07f6366 --- /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 24f8a25..b22f1ce 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 |