diff options
| author | Nikita Nemkin <nikita@nemkin.ru> | 2020-11-12 13:40:33 +0500 |
|---|---|---|
| committer | Nikita Nemkin <nikita@nemkin.ru> | 2020-12-02 21:00:30 +0500 |
| commit | 8fea95319bcaac741faf93bd66b3a1838b56a418 (patch) | |
| tree | 2bc107ce0cc4844e79f0baf93a394d93c27edaa8 /Modules | |
| parent | 8634561dcae9f5ff5128eaf7c83aa71170992ec2 (diff) | |
| download | cmake-8fea95319bcaac741faf93bd66b3a1838b56a418.tar.gz | |
Help: Add `.. versionadded` directives to module docs
Issue: #19715
Diffstat (limited to 'Modules')
106 files changed, 1293 insertions, 364 deletions
diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake index f521d22200..0beff04fdd 100644 --- a/Modules/BundleUtilities.cmake +++ b/Modules/BundleUtilities.cmake @@ -59,9 +59,10 @@ fix each one up according to its own list of prerequisites. Then clear all the keys and call ``verify_app`` on the final bundle to ensure that it is truly standalone. -As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, -which are then ignored -(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``). +.. versionadded:: 3.6 + As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, + which are then ignored + (e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``). .. code-block:: cmake @@ -78,9 +79,10 @@ Verifies that an application ``<app>`` appears valid based on running analysis tools on it. Calls :command:`message(FATAL_ERROR)` if the application is not verified. -As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, -which are then ignored -(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) +.. versionadded:: 3.6 + As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, + which are then ignored + (e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) .. code-block:: cmake @@ -155,9 +157,10 @@ them. Set values associated with each key such that we can loop over all of them and copy prerequisite libs into the bundle and then do appropriate ``install_name_tool`` fixups. -As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, -which are then ignored -(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) +.. versionadded:: 3.6 + As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, + which are then ignored + (e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) .. code-block:: cmake @@ -215,9 +218,10 @@ Verifies that the sum of all prerequisites of all files inside the bundle are contained within the bundle or are ``system`` libraries, presumed to exist everywhere. -As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, -which are then ignored -(e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) +.. versionadded:: 3.6 + As an optional parameter (``IGNORE_ITEM``) a list of file names can be passed, + which are then ignored + (e.g. ``IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe"``) .. code-block:: cmake diff --git a/Modules/CMakeGraphVizOptions.cmake b/Modules/CMakeGraphVizOptions.cmake index be4a3be365..708672258a 100644 --- a/Modules/CMakeGraphVizOptions.cmake +++ b/Modules/CMakeGraphVizOptions.cmake @@ -29,8 +29,9 @@ Graphviz package: dot -Tpng -o foo.png foo.dot -The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE`` -are represented as solid, dashed and dotted edges. +.. versionadded:: 3.10 + The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE`` + are represented as solid, dashed and dotted edges. Variables specific to the Graphviz support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake index 1a7f9cf2b1..372e9f4632 100644 --- a/Modules/CMakePackageConfigHelpers.cmake +++ b/Modules/CMakePackageConfigHelpers.cmake @@ -81,13 +81,14 @@ always relative to the installed location of the package. This works both for relative and also for absolute locations. For absolute locations it works only if the absolute location is a subdirectory of ``INSTALL_PREFIX``. -If the ``INSTALL_PREFIX`` argument is passed, this is used as base path to -calculate all the relative paths. The ``<path>`` argument must be an absolute -path. If this argument is not passed, the :variable:`CMAKE_INSTALL_PREFIX` -variable will be used instead. The default value is good when generating a -FooConfig.cmake file to use your package from the install tree. When -generating a FooConfig.cmake file to use your package from the build tree this -option should be used. +.. versionadded:: 3.1 + If the ``INSTALL_PREFIX`` argument is passed, this is used as base path to + calculate all the relative paths. The ``<path>`` argument must be an absolute + path. If this argument is not passed, the :variable:`CMAKE_INSTALL_PREFIX` + variable will be used instead. The default value is good when generating a + FooConfig.cmake file to use your package from the install tree. When + generating a FooConfig.cmake file to use your package from the build tree this + option should be used. By default ``configure_package_config_file`` also generates two helper macros, ``set_and_check()`` and ``check_required_components()`` into the @@ -159,22 +160,27 @@ If your project has more elaborated version matching rules, you will need to write your own custom ``ConfigVersion.cmake`` file instead of using this macro. -.. note:: ``COMPATIBILITY_MODE`` ``AnyNewerVersion`` handles the version range - if any is specified (see :command:`find_package` command for the details). - All other modes are incompatible with version ranges and will display an - author warning if one is specified. +.. versionadded:: 3.11 + The ``SameMinorVersion`` compatibility mode. -If ``ARCH_INDEPENDENT`` is given, the installed package version will be -considered compatible even if it was built for a different architecture than -the requested architecture. Otherwise, an architecture check will be performed, -and the package will be considered compatible only if the architecture matches -exactly. For example, if the package is built for a 32-bit architecture, the -package is only considered compatible if it is used on a 32-bit architecture, -unless ``ARCH_INDEPENDENT`` is given, in which case the package is considered -compatible on any architecture. +.. versionadded:: 3.14 + If ``ARCH_INDEPENDENT`` is given, the installed package version will be + considered compatible even if it was built for a different architecture than + the requested architecture. Otherwise, an architecture check will be performed, + and the package will be considered compatible only if the architecture matches + exactly. For example, if the package is built for a 32-bit architecture, the + package is only considered compatible if it is used on a 32-bit architecture, + unless ``ARCH_INDEPENDENT`` is given, in which case the package is considered + compatible on any architecture. .. note:: ``ARCH_INDEPENDENT`` is intended for header-only libraries or similar - packages with no binaries. + packages with no binaries. + +.. versionadded:: 3.19 + ``COMPATIBILITY_MODE`` ``AnyNewerVersion`` handles the version range + if any is specified (see :command:`find_package` command for the details). + All other modes are incompatible with version ranges and will display an + author warning if one is specified. Internally, this macro executes :command:`configure_file()` to create the resulting version file. Depending on the ``COMPATIBILITY``, the corresponding diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index 7529a1f431..eb1d43b515 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake @@ -194,6 +194,8 @@ installers. The most commonly-used variables are: .. variable:: CPACK_PACKAGE_CHECKSUM + .. versionadded:: 3.7 + An algorithm that will be used to generate an additional file with the checksum of the package. The output file name will be:: @@ -271,6 +273,8 @@ installers. The most commonly-used variables are: .. variable:: CPACK_VERBATIM_VARIABLES + .. versionadded:: 3.4 + If set to ``TRUE``, values of variables prefixed with ``CPACK_`` will be escaped before being written to the configuration files, so that the cpack program receives them exactly as they were specified. If not, characters @@ -356,6 +360,8 @@ The following variables are for advanced uses of CPack: .. variable:: CPACK_INSTALL_SCRIPTS + .. versionadded:: 3.16 + Extra CMake scripts executed by CPack during its local staging installation. They are executed before installing the files to be packaged. The scripts are not called by a standalone install (e.g.: ``make install``). @@ -372,6 +378,8 @@ The following variables are for advanced uses of CPack: .. variable:: CPACK_PRE_BUILD_SCRIPTS + .. versionadded:: 3.19 + List of CMake scripts to execute after CPack has installed the files to be packaged into a staging directory and before producing the package(s) from those files. See also :variable:`CPACK_INSTALL_SCRIPTS` and @@ -379,6 +387,8 @@ The following variables are for advanced uses of CPack: .. variable:: CPACK_POST_BUILD_SCRIPTS + .. versionadded:: 3.19 + List of CMake scripts to execute after CPack has produced the resultant packages and before copying them back to the build directory. See also :variable:`CPACK_INSTALL_SCRIPTS`, @@ -386,6 +396,8 @@ The following variables are for advanced uses of CPack: .. variable:: CPACK_PACKAGE_FILES + .. versionadded:: 3.19 + List of package files created in the staging directory, with each file provided as a full absolute path. This variable is populated by CPack just before invoking the post-build scripts listed in diff --git a/Modules/CPackIFW.cmake b/Modules/CPackIFW.cmake index 6ce0bfcc8a..d57cf18bac 100644 --- a/Modules/CPackIFW.cmake +++ b/Modules/CPackIFW.cmake @@ -51,20 +51,28 @@ The module defines the following commands: of a group to which it belongs. ``ESSENTIAL`` + .. versionadded:: 3.6 + if set, then the package manager stays disabled until that component is updated. ``VIRTUAL`` + .. versionadded:: 3.8 + if set, then the component will be hidden from the installer. It is a equivalent of the ``HIDDEN`` option from the :command:`cpack_add_component` command. ``FORCED_INSTALLATION`` + .. versionadded:: 3.8 + if set, then the component must always be installed. It is a equivalent of the ``REQUIRED`` option from the :command:`cpack_add_component` command. ``REQUIRES_ADMIN_RIGHTS`` + .. versionadded:: 3.8 + set it if the component needs to be installed with elevated permissions. ``NAME`` @@ -72,14 +80,20 @@ The module defines the following commands: By default used origin component name. ``DISPLAY_NAME`` + .. versionadded:: 3.8 + set to rewrite original name configured by :command:`cpack_add_component` command. ``DESCRIPTION`` + .. versionadded:: 3.8 + set to rewrite original description configured by :command:`cpack_add_component` command. ``UPDATE_TEXT`` + .. versionadded:: 3.8 + will be added to the component description if this is an update to the component. @@ -88,22 +102,32 @@ The module defines the following commands: By default used :variable:`CPACK_PACKAGE_VERSION`. ``RELEASE_DATE`` + .. versionadded:: 3.8 + keep empty to auto generate. ``SCRIPT`` is a relative or absolute path to operations script for this component. - ``PRIORITY`` | ``SORTING_PRIORITY`` + ``SORTING_PRIORITY`` + .. versionadded:: 3.8 + is priority of the component in the tree. - The ``PRIORITY`` option is deprecated and will be removed in a future - version of CMake. Please use ``SORTING_PRIORITY`` option instead. - ``DEPENDS`` | ``DEPENDENCIES`` + ``PRIORITY`` + .. deprecated:: 3.8 + Old name for ``SORTING_PRIORITY``. + + ``DEPENDS``, ``DEPENDENCIES`` + .. versionadded:: 3.8 + list of dependency component or component group identifiers in QtIFW style. ``AUTO_DEPEND_ON`` + .. versionadded:: 3.8 + list of identifiers of component or component group in QtIFW style that this component has an automatic dependency on. @@ -112,21 +136,31 @@ The module defines the following commands: component. You can specify more then one license. ``DEFAULT`` + .. versionadded:: 3.8 + Possible values are: TRUE, FALSE, and SCRIPT. Set to FALSE to disable the component in the installer or to SCRIPT to resolved during runtime (don't forget add the file of the script as a value of the ``SCRIPT`` option). ``USER_INTERFACES`` + .. versionadded:: 3.7 + is a list of <file_path> ('.ui' files) representing pages to load. ``TRANSLATIONS`` + .. versionadded:: 3.8 + is a list of <file_path> ('.qm' files) representing translations to load. ``REPLACES`` + .. versionadded:: 3.10 + list of identifiers of component or component group to replace. ``CHECKABLE`` + .. versionadded:: 3.10 + Possible values are: TRUE, FALSE. Set to FALSE if you want to hide the checkbox for an item. This is useful when only a few subcomponents should be selected @@ -162,13 +196,19 @@ The module defines the following commands: command. ``VIRTUAL`` + .. versionadded:: 3.8 + if set, then the group will be hidden from the installer. Note that setting this on a root component does not work. ``FORCED_INSTALLATION`` + .. versionadded:: 3.8 + if set, then the group must always be installed. ``REQUIRES_ADMIN_RIGHTS`` + .. versionadded:: 3.8 + set it if the component group needs to be installed with elevated permissions. @@ -177,14 +217,20 @@ The module defines the following commands: By default used origin component group name. ``DISPLAY_NAME`` + .. versionadded:: 3.8 + set to rewrite original name configured by :command:`cpack_add_component_group` command. ``DESCRIPTION`` + .. versionadded:: 3.8 + set to rewrite original description configured by :command:`cpack_add_component_group` command. ``UPDATE_TEXT`` + .. versionadded:: 3.8 + will be added to the component group description if this is an update to the component group. @@ -193,22 +239,30 @@ The module defines the following commands: By default used :variable:`CPACK_PACKAGE_VERSION`. ``RELEASE_DATE`` + .. versionadded:: 3.8 + keep empty to auto generate. ``SCRIPT`` is a relative or absolute path to operations script for this component group. - ``PRIORITY`` | ``SORTING_PRIORITY`` + ``SORTING_PRIORITY`` is priority of the component group in the tree. - The ``PRIORITY`` option is deprecated and will be removed in a future - version of CMake. Please use ``SORTING_PRIORITY`` option instead. - ``DEPENDS`` | ``DEPENDENCIES`` + ``PRIORITY`` + .. deprecated:: 3.8 + Old name for ``SORTING_PRIORITY``. + + ``DEPENDS``, ``DEPENDENCIES`` + .. versionadded:: 3.8 + list of dependency component or component group identifiers in QtIFW style. ``AUTO_DEPEND_ON`` + .. versionadded:: 3.8 + list of identifiers of component or component group in QtIFW style that this component group has an automatic dependency on. @@ -217,6 +271,8 @@ The module defines the following commands: component group. You can specify more then one license. ``DEFAULT`` + .. versionadded:: 3.8 + Possible values are: TRUE, FALSE, and SCRIPT. Set to TRUE to preselect the group in the installer (this takes effect only on groups that have no visible child components) @@ -224,15 +280,23 @@ The module defines the following commands: the script as a value of the ``SCRIPT`` option). ``USER_INTERFACES`` + .. versionadded:: 3.7 + is a list of <file_path> ('.ui' files) representing pages to load. ``TRANSLATIONS`` + .. versionadded:: 3.8 + is a list of <file_path> ('.qm' files) representing translations to load. ``REPLACES`` + .. versionadded:: 3.10 + list of identifiers of component or component group to replace. ``CHECKABLE`` + .. versionadded:: 3.10 + Possible values are: TRUE, FALSE. Set to FALSE if you want to hide the checkbox for an item. This is useful when only a few subcomponents should be selected @@ -272,6 +336,8 @@ The module defines the following commands: .. command:: cpack_ifw_update_repository + .. versionadded:: 3.6 + Update QtIFW specific repository from remote repository. :: @@ -307,6 +373,8 @@ The module defines the following commands: .. command:: cpack_ifw_add_package_resources + .. versionadded:: 3.7 + Add additional resources in the installer binary. :: diff --git a/Modules/CTestCoverageCollectGCOV.cmake b/Modules/CTestCoverageCollectGCOV.cmake index a01a2fea22..a6fa3a4c6c 100644 --- a/Modules/CTestCoverageCollectGCOV.cmake +++ b/Modules/CTestCoverageCollectGCOV.cmake @@ -39,7 +39,10 @@ After generating this tar file, it can be sent to CDash for display with the upload to CDash. Relative paths will be interpreted with respect to the top-level build directory. - ``TARBALL_COMPRESSION <option>`` Specify a compression algorithm for the + ``TARBALL_COMPRESSION <option>`` + .. versionadded:: 3.18 + + Specify a compression algorithm for the ``TARBALL`` data file. Using this option reduces the size of the data file before it is submitted to CDash. ``<option>`` must be one of ``GZIP``, ``BZIP2``, ``XZ``, ``ZSTD``, ``FROM_EXT``, or an expression that CMake @@ -68,15 +71,23 @@ After generating this tar file, it can be sent to CDash for display with the If not specified, the default option is just ``-b -x``. ``GLOB`` + .. versionadded:: 3.6 + Recursively search for .gcda files in build_dir rather than determining search locations by reading TargetDirectories.txt. ``DELETE`` + .. versionadded:: 3.6 + Delete coverage files after they've been packaged into the .tar. ``QUIET`` Suppress non-error messages that otherwise would have been printed out by this function. + + .. versionadded:: 3.3 + Added support for the :variable:`CTEST_CUSTOM_COVERAGE_EXCLUDE` variable. + #]=======================================================================] function(ctest_coverage_collect_gcov) diff --git a/Modules/CTestUseLaunchers.cmake b/Modules/CTestUseLaunchers.cmake index 3dff926052..23a206b2a5 100644 --- a/Modules/CTestUseLaunchers.cmake +++ b/Modules/CTestUseLaunchers.cmake @@ -24,9 +24,12 @@ long as your CMakeLists uses include(CTest) or include(CTestUseLaunchers), it will use the value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache variable. This cache variable initialization only occurs if CTEST_USE_LAUNCHERS is not -already defined. If CTEST_USE_LAUNCHERS is on in a ctest -S script -the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE -to the cmake command used to configure the project. +already defined. + +.. versionadded:: 3.8 + If CTEST_USE_LAUNCHERS is on in a ctest -S script + the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE + to the cmake command used to configure the project. #]=======================================================================] if(NOT DEFINED CTEST_USE_LAUNCHERS AND DEFINED ENV{CTEST_USE_LAUNCHERS_DEFAULT}) diff --git a/Modules/CheckCSourceCompiles.cmake b/Modules/CheckCSourceCompiles.cmake index 698a007ebc..b24da49bc0 100644 --- a/Modules/CheckCSourceCompiles.cmake +++ b/Modules/CheckCSourceCompiles.cmake @@ -44,6 +44,8 @@ Check if given C source compiles and links into an executable. directory property will be ignored. ``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + A :ref:`;-list <CMake Language Lists>` of options to add to the link command (see :command:`try_compile` for further details). @@ -54,6 +56,8 @@ Check if given C source compiles and links into an executable. further details). ``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. diff --git a/Modules/CheckCSourceRuns.cmake b/Modules/CheckCSourceRuns.cmake index a99e47e833..a6081ff46e 100644 --- a/Modules/CheckCSourceRuns.cmake +++ b/Modules/CheckCSourceRuns.cmake @@ -43,6 +43,8 @@ subsequently be run. directory property will be ignored. ``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + A :ref:`;-list <CMake Language Lists>` of options to add to the link command (see :command:`try_run` for further details). @@ -53,6 +55,8 @@ subsequently be run. further details). ``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. diff --git a/Modules/CheckCXXSourceCompiles.cmake b/Modules/CheckCXXSourceCompiles.cmake index dc209b2688..502bfa76e6 100644 --- a/Modules/CheckCXXSourceCompiles.cmake +++ b/Modules/CheckCXXSourceCompiles.cmake @@ -44,6 +44,8 @@ Check if given C++ source compiles and links into an executable. directory property will be ignored. ``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + A :ref:`;-list <CMake Language Lists>` of options to add to the link command (see :command:`try_compile` for further details). @@ -54,6 +56,8 @@ Check if given C++ source compiles and links into an executable. further details). ``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. diff --git a/Modules/CheckCXXSourceRuns.cmake b/Modules/CheckCXXSourceRuns.cmake index c8ff3d7bf5..af03453d98 100644 --- a/Modules/CheckCXXSourceRuns.cmake +++ b/Modules/CheckCXXSourceRuns.cmake @@ -43,6 +43,8 @@ subsequently be run. directory property will be ignored. ``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + A :ref:`;-list <CMake Language Lists>` of options to add to the link command (see :command:`try_run` for further details). @@ -53,6 +55,8 @@ subsequently be run. further details). ``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + If this variable evaluates to a boolean true value, all status messages associated with the check will be suppressed. diff --git a/Modules/CheckCXXSymbolExists.cmake b/Modules/CheckCXXSymbolExists.cmake index 5c9079dbf3..b4da4fac88 100644 --- a/Modules/CheckCXXSymbolExists.cmake +++ b/Modules/CheckCXXSymbolExists.cmake @@ -49,12 +49,14 @@ the way the check is run: a :ref:`;-list <CMake Language Lists>` of header search paths to pass to the compiler. ``CMAKE_REQUIRED_LINK_OPTIONS`` - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. + .. versionadded:: 3.14 + a :ref:`;-list <CMake Language Lists>` of options to add to the link command. ``CMAKE_REQUIRED_LIBRARIES`` a :ref:`;-list <CMake Language Lists>` of libraries to add to the link command. See policy :policy:`CMP0075`. ``CMAKE_REQUIRED_QUIET`` - execute quietly without messages. + .. versionadded:: 3.1 + execute quietly without messages. For example: diff --git a/Modules/CheckFortranFunctionExists.cmake b/Modules/CheckFortranFunctionExists.cmake index d06203fc23..ad72e2f09e 100644 --- a/Modules/CheckFortranFunctionExists.cmake +++ b/Modules/CheckFortranFunctionExists.cmake @@ -24,8 +24,9 @@ The following variables may be set before calling this macro to modify the way the check is run: ``CMAKE_REQUIRED_LINK_OPTIONS`` - A :ref:`;-list <CMake Language Lists>` of options to add to the link - command (see :command:`try_compile` for further details). + .. versionadded:: 3.14 + A :ref:`;-list <CMake Language Lists>` of options to add to the link + command (see :command:`try_compile` for further details). ``CMAKE_REQUIRED_LIBRARIES`` A :ref:`;-list <CMake Language Lists>` of libraries to add to the link diff --git a/Modules/CheckFortranSourceCompiles.cmake b/Modules/CheckFortranSourceCompiles.cmake index 5ede284572..e1343293b7 100644 --- a/Modules/CheckFortranSourceCompiles.cmake +++ b/Modules/CheckFortranSourceCompiles.cmake @@ -65,6 +65,8 @@ Check if given Fortran source compiles and links into an executable. directory property will be ignored. ``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + A :ref:`;-list <CMake Language Lists>` of options to add to the link command (see :command:`try_compile` for further details). diff --git a/Modules/CheckFunctionExists.cmake b/Modules/CheckFunctionExists.cmake index 136da89d9b..9efa132b43 100644 --- a/Modules/CheckFunctionExists.cmake +++ b/Modules/CheckFunctionExists.cmake @@ -28,12 +28,14 @@ way the check is run: a :ref:`;-list <CMake Language Lists>` of header search paths to pass to the compiler. ``CMAKE_REQUIRED_LINK_OPTIONS`` - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. + .. versionadded:: 3.14 + a :ref:`;-list <CMake Language Lists>` of options to add to the link command. ``CMAKE_REQUIRED_LIBRARIES`` a :ref:`;-list <CMake Language Lists>` of libraries to add to the link command. See policy :policy:`CMP0075`. ``CMAKE_REQUIRED_QUIET`` - execute quietly without messages. + .. versionadded:: 3.1 + execute quietly without messages. .. note:: diff --git a/Modules/CheckIPOSupported.cmake b/Modules/CheckIPOSupported.cmake index 1dd951d83c..0bc3c92338 100644 --- a/Modules/CheckIPOSupported.cmake +++ b/Modules/CheckIPOSupported.cmake @@ -33,6 +33,9 @@ property. It makes no sense to use this module when :policy:`CMP0069` is set to ``OLD`` so module will return error in this case. See policy :policy:`CMP0069` for details. +.. versionadded:: 3.13 + Add support for Visual Studio generators. + Examples ^^^^^^^^ diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake index 3a104736c6..71ddde7f21 100644 --- a/Modules/CheckIncludeFile.cmake +++ b/Modules/CheckIncludeFile.cmake @@ -29,12 +29,14 @@ the way the check is run: a :ref:`;-list <CMake Language Lists>` of header search paths to pass to the compiler. ``CMAKE_REQUIRED_LINK_OPTIONS`` - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. + .. versionadded:: 3.14 + a :ref:`;-list <CMake Language Lists>` of options to add to the link command. ``CMAKE_REQUIRED_LIBRARIES`` a :ref:`;-list <CMake Language Lists>` of libraries to add to the link command. See policy :policy:`CMP0075`. ``CMAKE_REQUIRED_QUIET`` - execute quietly without messages. + .. versionadded:: 3.1 + execute quietly without messages. See the :module:`CheckIncludeFiles` module to check for multiple headers at once. See the :module:`CheckIncludeFileCXX` module to check for headers diff --git a/Modules/CheckIncludeFileCXX.cmake b/Modules/CheckIncludeFileCXX.cmake index 496550fa86..953224e763 100644 --- a/Modules/CheckIncludeFileCXX.cmake +++ b/Modules/CheckIncludeFileCXX.cmake @@ -29,12 +29,14 @@ the way the check is run: a :ref:`;-list <CMake Language Lists>` of header search paths to pass to the compiler. ``CMAKE_REQUIRED_LINK_OPTIONS`` - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. + .. versionadded:: 3.14 + a :ref:`;-list <CMake Language Lists>` of options to add to the link command. ``CMAKE_REQUIRED_LIBRARIES`` a :ref:`;-list <CMake Language Lists>` of libraries to add to the link command. See policy :policy:`CMP0075`. ``CMAKE_REQUIRED_QUIET`` - execute quietly without messages. + .. versionadded:: 3.1 + execute quietly without messages. See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFiles` to check for one or more ``C`` headers. diff --git a/Modules/CheckIncludeFiles.cmake b/Modules/CheckIncludeFiles.cmake index 8e10cd6abb..1800ca888e 100644 --- a/Modules/CheckIncludeFiles.cmake +++ b/Modules/CheckIncludeFiles.cmake @@ -35,12 +35,14 @@ the way the check is run: a :ref:`;-list <CMake Language Lists>` of header search paths to pass to the compiler. ``CMAKE_REQUIRED_LINK_OPTIONS`` - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. + .. versionadded:: 3.14 + a :ref:`;-list <CMake Language Lists>` of options to add to the link command. ``CMAKE_REQUIRED_LIBRARIES`` a :ref:`;-list <CMake Language Lists>` of libraries to add to the link command. See policy :policy:`CMP0075`. ``CMAKE_REQUIRED_QUIET`` - execute quietly without messages. + .. versionadded:: 3.1 + execute quietly without messages. See modules :module:`CheckIncludeFile` and :module:`CheckIncludeFileCXX` to check for a single header file in ``C`` or ``CXX`` languages. diff --git a/Modules/CheckLibraryExists.cmake b/Modules/CheckLibraryExists.cmake index 6470dfd049..804e0cbba3 100644 --- a/Modules/CheckLibraryExists.cmake +++ b/Modules/CheckLibraryExists.cmake @@ -26,13 +26,18 @@ Check if the function exists. The following variables may be set before calling this macro to modify the way the check is run: -:: - - CMAKE_REQUIRED_FLAGS = string of compile command line flags - CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar) - CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command - CMAKE_REQUIRED_LIBRARIES = list of libraries to link - CMAKE_REQUIRED_QUIET = execute quietly without messages +``CMAKE_REQUIRED_FLAGS`` + string of compile command line flags. +``CMAKE_REQUIRED_DEFINITIONS`` + list of macros to define (-DFOO=bar). +``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + list of options to pass to link command. +``CMAKE_REQUIRED_LIBRARIES`` + list of libraries to link. +``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + execute quietly without messages. #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/CheckPrototypeDefinition.cmake b/Modules/CheckPrototypeDefinition.cmake index 8b06403d7e..d29c5e89f3 100644 --- a/Modules/CheckPrototypeDefinition.cmake +++ b/Modules/CheckPrototypeDefinition.cmake @@ -35,14 +35,20 @@ Check if the prototype we expect is correct. The following variables may be set before calling this function to modify the way the check is run: -:: - - CMAKE_REQUIRED_FLAGS = string of compile command line flags - CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar) - CMAKE_REQUIRED_INCLUDES = list of include directories - CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command - CMAKE_REQUIRED_LIBRARIES = list of libraries to link - CMAKE_REQUIRED_QUIET = execute quietly without messages +``CMAKE_REQUIRED_FLAGS`` + string of compile command line flags. +``CMAKE_REQUIRED_DEFINITIONS`` + list of macros to define (-DFOO=bar). +``CMAKE_REQUIRED_INCLUDES`` + list of include directories. +``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + list of options to pass to link command. +``CMAKE_REQUIRED_LIBRARIES`` + list of libraries to link. +``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + execute quietly without messages. #]=======================================================================] # diff --git a/Modules/CheckStructHasMember.cmake b/Modules/CheckStructHasMember.cmake index 842a8fdb72..8217c84c2a 100644 --- a/Modules/CheckStructHasMember.cmake +++ b/Modules/CheckStructHasMember.cmake @@ -23,18 +23,23 @@ Check if the given struct or class has the specified member variable <language> - the compiler to use (C or CXX) - The following variables may be set before calling this macro to modify the way the check is run: -:: - - CMAKE_REQUIRED_FLAGS = string of compile command line flags - CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar) - CMAKE_REQUIRED_INCLUDES = list of include directories - CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command - CMAKE_REQUIRED_LIBRARIES = list of libraries to link - CMAKE_REQUIRED_QUIET = execute quietly without messages +``CMAKE_REQUIRED_FLAGS`` + string of compile command line flags. +``CMAKE_REQUIRED_DEFINITIONS`` + list of macros to define (-DFOO=bar). +``CMAKE_REQUIRED_INCLUDES`` + list of include directories. +``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + list of options to pass to link command. +``CMAKE_REQUIRED_LIBRARIES`` + list of libraries to link. +``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + execute quietly without messages. Example: diff --git a/Modules/CheckSymbolExists.cmake b/Modules/CheckSymbolExists.cmake index 4f202c41d5..f8ca584026 100644 --- a/Modules/CheckSymbolExists.cmake +++ b/Modules/CheckSymbolExists.cmake @@ -39,12 +39,14 @@ the way the check is run: a :ref:`;-list <CMake Language Lists>` of header search paths to pass to the compiler. ``CMAKE_REQUIRED_LINK_OPTIONS`` - a :ref:`;-list <CMake Language Lists>` of options to add to the link command. + .. versionadded:: 3.14 + a :ref:`;-list <CMake Language Lists>` of options to add to the link command. ``CMAKE_REQUIRED_LIBRARIES`` a :ref:`;-list <CMake Language Lists>` of libraries to add to the link command. See policy :policy:`CMP0075`. ``CMAKE_REQUIRED_QUIET`` - execute quietly without messages. + .. versionadded:: 3.1 + execute quietly without messages. For example: diff --git a/Modules/CheckTypeSize.cmake b/Modules/CheckTypeSize.cmake index 17beadcb10..69f68f9d4a 100644 --- a/Modules/CheckTypeSize.cmake +++ b/Modules/CheckTypeSize.cmake @@ -57,19 +57,25 @@ member you can do something like this: check_type_size("((struct something*)0)->member" SIZEOF_MEMBER) - The following variables may be set before calling this macro to modify the way the check is run: -:: - - CMAKE_REQUIRED_FLAGS = string of compile command line flags - CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar) - CMAKE_REQUIRED_INCLUDES = list of include directories - CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command - CMAKE_REQUIRED_LIBRARIES = list of libraries to link - CMAKE_REQUIRED_QUIET = execute quietly without messages - CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include +``CMAKE_REQUIRED_FLAGS`` + string of compile command line flags. +``CMAKE_REQUIRED_DEFINITIONS`` + list of macros to define (-DFOO=bar). +``CMAKE_REQUIRED_INCLUDES`` + list of include directories. +``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + list of options to pass to link command. +``CMAKE_REQUIRED_LIBRARIES`` + list of libraries to link. +``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + execute quietly without messages. +``CMAKE_EXTRA_INCLUDE_FILES`` + list of extra headers to include. #]=======================================================================] include(CheckIncludeFile) diff --git a/Modules/CheckVariableExists.cmake b/Modules/CheckVariableExists.cmake index 8a93535249..7420124f48 100644 --- a/Modules/CheckVariableExists.cmake +++ b/Modules/CheckVariableExists.cmake @@ -26,13 +26,18 @@ Check if the variable exists. The following variables may be set before calling this macro to modify the way the check is run: -:: - - CMAKE_REQUIRED_FLAGS = string of compile command line flags - CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar) - CMAKE_REQUIRED_LINK_OPTIONS = list of options to pass to link command - CMAKE_REQUIRED_LIBRARIES = list of libraries to link - CMAKE_REQUIRED_QUIET = execute quietly without messages +``CMAKE_REQUIRED_FLAGS`` + string of compile command line flags. +``CMAKE_REQUIRED_DEFINITIONS`` + list of macros to define (-DFOO=bar). +``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + list of options to pass to link command. +``CMAKE_REQUIRED_LIBRARIES`` + list of libraries to link. +``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + execute quietly without messages. #]=======================================================================] include_guard(GLOBAL) diff --git a/Modules/Documentation.cmake b/Modules/Documentation.cmake index c297231e5b..2430f85a0c 100644 --- a/Modules/Documentation.cmake +++ b/Modules/Documentation.cmake @@ -5,6 +5,9 @@ Documentation ------------- +.. deprecated:: 3.18 + This module does nothing, unless policy :policy:`CMP0106` is set to ``OLD``. + This module provides support for the VTK documentation framework. It relies on several tools (Doxygen, Perl, etc). #]=======================================================================] diff --git a/Modules/ExternalData.cmake b/Modules/ExternalData.cmake index 294167c9ad..d6fbae9aaf 100644 --- a/Modules/ExternalData.cmake +++ b/Modules/ExternalData.cmake @@ -90,10 +90,11 @@ Module Functions in one of the paths specified in the ``ExternalData_OBJECT_STORES`` variable. - The ``SHOW_PROGRESS`` argument may be passed to suppress progress information - during the download of objects. If not provided, it defaults to ``OFF`` for - :generator:`Ninja` and :generator:`Ninja Multi-Config` generators and ``ON`` - otherwise. + .. versionadded:: 3.20 + The ``SHOW_PROGRESS`` argument may be passed to suppress progress information + during the download of objects. If not provided, it defaults to ``OFF`` for + :generator:`Ninja` and :generator:`Ninja Multi-Config` generators and ``ON`` + otherwise. Typically only one target is needed to manage all external data within a project. Call this function once at the end of configuration after @@ -114,6 +115,8 @@ calling any of the functions provided by this module. .. variable:: ExternalData_CUSTOM_SCRIPT_<key> + .. versionadded:: 3.2 + Specify a full path to a ``.cmake`` custom fetch script identified by ``<key>`` in entries of the ``ExternalData_URL_TEMPLATES`` list. See `Custom Fetch Scripts`_. @@ -132,6 +135,8 @@ calling any of the functions provided by this module. .. variable:: ExternalData_NO_SYMLINKS + .. versionadded:: 3.3 + The real data files named by expanded ``DATA{}`` references may be made available under ``ExternalData_BINARY_ROOT`` using symbolic links on some platforms. The ``ExternalData_NO_SYMLINKS`` variable may be set @@ -177,6 +182,8 @@ calling any of the functions provided by this module. .. variable:: ExternalData_URL_ALGO_<algo>_<key> + .. versionadded:: 3.3 + Specify a custom URL component to be substituted for URL template placeholders of the form ``%(algo:<key>)``, where ``<key>`` is a valid C identifier, when fetching an object referenced via hash @@ -207,10 +214,11 @@ For example, the argument ``DATA{img.png}`` may be satisfied by either a real ``img.png`` file in the current source directory or a ``img.png.md5`` file containing its MD5 sum. -Multiple content links of the same name with different hash algorithms -are supported (e.g. ``img.png.sha256`` and ``img.png.sha1``) so long as -they all correspond to the same real file. This allows objects to be -fetched from sources indexed by different hash algorithms. +.. versionadded:: 3.8 + Multiple content links of the same name with different hash algorithms + are supported (e.g. ``img.png.sha256`` and ``img.png.sha1``) so long as + they all correspond to the same real file. This allows objects to be + fetched from sources indexed by different hash algorithms. Referencing File Series """"""""""""""""""""""" @@ -269,8 +277,11 @@ associated file options. For example, the argument ``DATA{MyDataDir/,REGEX:.*}`` will pass the full path to a ``MyDataDir`` directory on the command line and ensure that the directory contains files corresponding to every file or content link in the ``MyDataDir`` -source directory. In order to match associated files in subdirectories, -specify a ``RECURSE:`` option, e.g. ``DATA{MyDataDir/,RECURSE:,REGEX:.*}``. +source directory. + +.. versionadded:: 3.3 + In order to match associated files in subdirectories, + specify a ``RECURSE:`` option, e.g. ``DATA{MyDataDir/,RECURSE:,REGEX:.*}``. Hash Algorithms ^^^^^^^^^^^^^^^ @@ -290,6 +301,9 @@ The following hash algorithms are supported:: SHA3_384 .sha3-384 Keccak SHA-3 SHA3_512 .sha3-512 Keccak SHA-3 +.. versionadded:: 3.8 + Added the ``SHA3_*`` hash algorithms. + Note that the hashes are used only for unique data identification and download verification. @@ -298,6 +312,8 @@ download verification. Custom Fetch Scripts ^^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 3.2 + When a data file must be fetched from one of the URL templates specified in the ``ExternalData_URL_TEMPLATES`` variable, it is normally downloaded using the :command:`file(DOWNLOAD)` command. diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 8bbaf5a38a..f0ce7d49cb 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -56,6 +56,8 @@ External Project Definition (see *Logging Options* below). ``LOG_DIR <dir>`` + .. versionadded:: 3.14 + Directory in which to store the logs of each step. ``DOWNLOAD_DIR <dir>`` @@ -144,6 +146,9 @@ External Project Definition is determined by inspecting the actual content rather than using logic based on the file extension. + .. versionchanged:: 3.7 + Multiple URLs are allowed. + ``URL_HASH <algo>=<hashValue>`` Hash of the archive file to be downloaded. The argument should be of the form ``<algo>=<hashValue>`` where ``algo`` can be any of the hashing @@ -164,6 +169,8 @@ External Project Definition of code internal to the ``ExternalProject`` module. ``DOWNLOAD_NO_EXTRACT <bool>`` + .. versionadded:: 3.6 + Allows the extraction part of the download step to be disabled by passing a boolean true value for this option. If this option is not given, the downloaded contents will be unpacked automatically if @@ -180,15 +187,23 @@ External Project Definition Maximum time allowed for file download operations. ``INACTIVITY_TIMEOUT <seconds>`` + .. versionadded:: 3.19 + Terminate the operation after a period of inactivity. ``HTTP_USERNAME <username>`` + .. versionadded:: 3.7 + Username for the download operation if authentication is required. ``HTTP_PASSWORD <password>`` + .. versionadded:: 3.7 + Password for the download operation if authentication is required. ``HTTP_HEADER <header1> [<header2>...]`` + .. versionadded:: 3.7 + Provides an arbitrary list of HTTP headers for the download operation. This can be useful for accessing content in systems like AWS, etc. @@ -201,6 +216,9 @@ External Project Definition cannot be provided, this option can be an alternative verification measure. + .. versionchanged:: 3.6 + This option also applies to ``git clone`` invocations. + ``TLS_CAINFO <file>`` Specify a custom certificate authority file to use if ``TLS_VERIFY`` is enabled. If this option is not specified, the value of the @@ -208,6 +226,8 @@ External Project Definition :command:`file(DOWNLOAD)`) ``NETRC <level>`` + .. 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 will be used instead (see :command:`file(DOWNLOAD)`) @@ -225,11 +245,16 @@ External Project Definition is ignored. ``NETRC_FILE <file>`` + .. versionadded:: 3.11 + 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 be used instead (see :command:`file(DOWNLOAD)`) + .. versionadded:: 3.1 + Added support for `tbz2`, `.tar.xz`, `.txz`, and `.7z` extensions. + *Git* NOTE: A git version of 1.6.5 or later is required if this download method is used. @@ -267,22 +292,30 @@ External Project Definition ``GIT_SUBMODULES <module>...`` Specific git submodules that should also be updated. If this option is - not provided, all git submodules will be updated. When :policy:`CMP0097` - is set to ``NEW`` if this value is set to an empty string then no submodules - are initialized or updated. + not provided, all git submodules will be updated. + + .. versionchanged:: 3.16 + When :policy:`CMP0097` is set to ``NEW``, if this value is set + to an empty string then no submodules are initialized or updated. ``GIT_SUBMODULES_RECURSE <bool>`` + .. versionadded:: 3.17 + Specify whether git submodules (if any) should update recursively by passing the ``--recursive`` flag to ``git submodule update``. If not specified, the default is on. ``GIT_SHALLOW <bool>`` + .. versionadded:: 3.6 + When this option is enabled, the ``git clone`` operation will be given the ``--depth 1`` option. This performs a shallow clone, which avoids downloading the whole history and instead retrieves just the commit denoted by the ``GIT_TAG`` option. ``GIT_PROGRESS <bool>`` + .. versionadded:: 3.8 + When enabled, this option instructs the ``git clone`` operation to report its progress by passing it the ``--progress`` option. Without this option, the clone step for large projects may appear to make the @@ -292,12 +325,16 @@ External Project Definition overly noisy if lots of external projects are used. ``GIT_CONFIG <option1> [<option2>...]`` + .. versionadded:: 3.8 + Specify a list of config options to pass to ``git clone``. Each option listed will be transformed into its own ``--config <option>`` on the ``git clone`` command line, with each option required to be in the form ``key=value``. ``GIT_REMOTE_UPDATE_STRATEGY <strategy>`` + .. versionadded:: 3.18 + When ``GIT_TAG`` refers to a remote branch, this option can be used to specify how the update step behaves. The ``<strategy>`` must be one of the following: @@ -379,6 +416,8 @@ External Project Definition :manual:`generator expressions <cmake-generator-expressions(7)>`. ``UPDATE_DISCONNECTED <bool>`` + .. versionadded:: 3.2 + When enabled, this option causes the update step to be skipped. It does not, however, prevent the download step. The update step can still be added as a step target (see :command:`ExternalProject_Add_StepTargets`) @@ -436,6 +475,8 @@ External Project Definition ``CONFIGURE_COMMAND`` option. ``CMAKE_GENERATOR_PLATFORM <platform>`` + .. versionadded:: 3.1 + Pass a generator-specific platform name to the CMake command (see :variable:`CMAKE_GENERATOR_PLATFORM`). It is an error to provide this option without the ``CMAKE_GENERATOR`` option. @@ -446,6 +487,8 @@ External Project Definition option without the ``CMAKE_GENERATOR`` option. ``CMAKE_GENERATOR_INSTANCE <instance>`` + .. versionadded:: 3.11 + Pass a generator-specific instance selection to the CMake command (see :variable:`CMAKE_GENERATOR_INSTANCE`). It is an error to provide this option without the ``CMAKE_GENERATOR`` option. @@ -454,8 +497,10 @@ External Project Definition The specified arguments are passed to the ``cmake`` command line. They can be any argument the ``cmake`` command understands, not just cache values defined by ``-D...`` arguments (see also - :manual:`CMake Options <cmake(1)>`). In addition, arguments may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. + :manual:`CMake Options <cmake(1)>`). + + .. versionadded:: 3.3 + Arguments may use :manual:`generator expressions <cmake-generator-expressions(7)>`. ``CMAKE_CACHE_ARGS <arg>...`` This is an alternate way of specifying cache variables where command line @@ -463,10 +508,14 @@ External Project Definition the form ``-Dvar:STRING=value``, which are then transformed into CMake :command:`set` commands with the ``FORCE`` option used. These ``set()`` commands are written to a pre-load script which is then applied - using the :manual:`cmake -C <cmake(1)>` command line option. Arguments - may use :manual:`generator expressions <cmake-generator-expressions(7)>`. + using the :manual:`cmake -C <cmake(1)>` command line option. + + .. versionadded:: 3.3 + Arguments may use :manual:`generator expressions <cmake-generator-expressions(7)>`. ``CMAKE_CACHE_DEFAULT_ARGS <arg>...`` + .. versionadded:: 3.2 + This is the same as the ``CMAKE_CACHE_ARGS`` option except the ``set()`` commands do not include the ``FORCE`` keyword. This means the values act as initial defaults only and will not override any variables already set @@ -474,20 +523,25 @@ External Project Definition different behavior depending on whether the build starts from a fresh build directory or re-uses previous build contents. - If the CMake generator is the ``Green Hills MULTI`` and not overridden then - the original project's settings for the GHS toolset and target system - customization cache variables are propagated into the external project. + .. versionadded:: 3.15 + If the CMake generator is the ``Green Hills MULTI`` and not overridden then + the original project's settings for the GHS toolset and target system + customization cache variables are propagated into the external project. ``SOURCE_SUBDIR <dir>`` + .. versionadded:: 3.7 + When no ``CONFIGURE_COMMAND`` option is specified, the configure step assumes the external project has a ``CMakeLists.txt`` file at the top of its source tree (i.e. in ``SOURCE_DIR``). The ``SOURCE_SUBDIR`` option can be used to point to an alternative directory within the source tree to use as the top of the CMake source tree instead. This must be a relative path and it will be interpreted as being relative to - ``SOURCE_DIR``. When ``BUILD_IN_SOURCE 1`` is specified, the - ``BUILD_COMMAND`` is used to point to an alternative directory within the - source tree. + ``SOURCE_DIR``. + + .. versionadded:: 3.14 + When ``BUILD_IN_SOURCE`` option is enabled, the ``BUILD_COMMAND`` + is used to point to an alternative directory within the source tree. **Build Step Options:** If the configure step assumed the external project uses CMake as its build @@ -524,6 +578,8 @@ External Project Definition developers might modify the sources in ``SOURCE_DIR``). ``BUILD_BYPRODUCTS <file>...`` + .. versionadded:: 3.2 + Specifies files that will be generated by the build command but which might or might not have their modification time updated by subsequent builds. These ultimately get passed through as ``BYPRODUCTS`` to the @@ -578,6 +634,8 @@ External Project Definition ``TEST_AFTER_INSTALL`` are enabled, the latter is silently ignored. ``TEST_EXCLUDE_FROM_MAIN <bool>`` + .. versionadded:: 3.2 + If enabled, the main build's default ALL target will not depend on the test step. This can be a useful way of ensuring the test step is defined but only gets invoked when manually requested. @@ -597,6 +655,8 @@ External Project Definition When enabled, the output of the update step is logged to files. ``LOG_PATCH <bool>`` + .. versionadded:: 3.14 + When enabled, the output of the patch step is logged to files. ``LOG_CONFIGURE <bool>`` @@ -612,10 +672,14 @@ External Project Definition When enabled, the output of the test step is logged to files. ``LOG_MERGED_STDOUTERR <bool>`` + .. versionadded:: 3.14 + When enabled, stdout and stderr will be merged for any step whose output is being logged to files. ``LOG_OUTPUT_ON_FAILURE <bool>`` + .. versionadded:: 3.14 + This option only has an effect if at least one of the other ``LOG_<step>`` options is enabled. If an error occurs for a step which has logging to file enabled, that step's output will be printed to the console if @@ -624,6 +688,8 @@ External Project Definition console. **Terminal Access Options:** + .. versionadded:: 3.4 + Steps can be given direct access to the terminal in some cases. Giving a step access to the terminal may allow it to receive terminal input if required, such as for authentication details not provided by other options. @@ -673,8 +739,9 @@ External Project Definition discussion of the effects of this option. ``INDEPENDENT_STEP_TARGETS <step-target>...`` - Deprecated. This is allowed only if policy :policy:`CMP0114` is not set - to ``NEW``. + .. deprecated:: 3.19 + This is allowed only if policy :policy:`CMP0114` is not set to ``NEW``. + Generates custom targets for the specified steps and prevent these targets from having the usual dependencies applied to them. If this option is not specified, the default value is taken from the @@ -780,6 +847,8 @@ control needed to implement such step-level capabilities. Files on which this custom step depends. ``INDEPENDENT <bool>`` + .. versionadded:: 3.19 + Specifies whether this step is independent of the external dependencies specified by the :command:`ExternalProject_Add`'s ``DEPENDS`` option. The default is ``FALSE``. Steps marked as independent may depend only @@ -795,6 +864,8 @@ control needed to implement such step-level capabilities. on the external targets, but may depend on targets for other steps. ``BYPRODUCTS <file>...`` + .. versionadded:: 3.2 + Files that will be generated by this custom step but which might or might not have their modification time updated by subsequent builds. This list of files will ultimately be passed through as the ``BYPRODUCTS`` option to the @@ -831,6 +902,12 @@ control needed to implement such step-level capabilities. corresponding property values defined in the original call to :command:`ExternalProject_Add`. + .. versionadded:: 3.3 + Token replacement is extended to byproducts. + + .. versionadded:: 3.11 + The ``<DOWNLOAD_DIR>`` substitution token. + .. command:: ExternalProject_Add_StepTargets The ``ExternalProject_Add_StepTargets()`` function generates targets for the @@ -868,15 +945,16 @@ control needed to implement such step-level capabilities. can save having to repeatedly specify the same set of step targets when multiple external projects are being defined. - If :policy:`CMP0114` is set to ``NEW``, step targets are fully responsible - for holding the custom commands implementing their steps. The primary target - created by ``ExternalProject_Add`` depends on the step targets, and the - step targets depend on each other. The target-level dependencies match - the file-level dependencies used by the custom commands for each step. - The targets for steps created with :command:`ExternalProject_Add_Step`'s - ``INDEPENDENT`` option do not depend on the external targets specified - by :command:`ExternalProject_Add`'s ``DEPENDS`` option. The predefined - steps ``mkdir``, ``download``, ``update``, and ``patch`` are independent. + .. versionadded:: 3.19 + If :policy:`CMP0114` is set to ``NEW``, step targets are fully responsible + for holding the custom commands implementing their steps. The primary target + created by ``ExternalProject_Add`` depends on the step targets, and the + step targets depend on each other. The target-level dependencies match + the file-level dependencies used by the custom commands for each step. + The targets for steps created with :command:`ExternalProject_Add_Step`'s + ``INDEPENDENT`` option do not depend on the external targets specified + by :command:`ExternalProject_Add`'s ``DEPENDS`` option. The predefined + steps ``mkdir``, ``download``, ``update``, and ``patch`` are independent. If :policy:`CMP0114` is not ``NEW``, the following deprecated behavior is available: @@ -901,6 +979,8 @@ control needed to implement such step-level capabilities. .. command:: ExternalProject_Add_StepDependencies + .. versionadded:: 3.2 + The ``ExternalProject_Add_StepDependencies()`` function can be used to add dependencies to a step. The dependencies added must be targets CMake already knows about (these can be ordinary executable or library targets, custom diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake index 4a3e83af31..77c66d14af 100644 --- a/Modules/FeatureSummary.cmake +++ b/Modules/FeatureSummary.cmake @@ -66,6 +66,8 @@ The default value for this global property is ``OPTIONAL``. .. variable:: FeatureSummary_<TYPE>_DESCRIPTION +.. versionadded:: 3.9 + The global property :variable:`FeatureSummary_<TYPE>_DESCRIPTION` can be defined for each type to replace the type name with the specified string whenever the package type is used in an output string. @@ -242,12 +244,13 @@ endfunction() ``<TYPE>_PACKAGES_NOT_FOUND`` only those packages which have not been found which have the type <TYPE> - With the exception of the ``ALL`` value, these values can be combined - in order to customize the output. For example: + .. versionchanged:: 3.1 + With the exception of the ``ALL`` value, these values can be combined + in order to customize the output. For example: - .. code-block:: cmake + .. code-block:: cmake - feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES) + feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES) If a ``FILENAME`` is given, the information is printed into this file. If ``APPEND`` is used, it is appended to this file, otherwise the file is @@ -268,14 +271,18 @@ endfunction() The default value for the :variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property is ``REQUIRED``. + .. versionadded:: 3.9 + The ``DEFAULT_DESCRIPTION`` option. + The :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global property can be modified to change the default package type assigned when not explicitly assigned by the user. - If the ``QUIET_ON_EMPTY`` option is used, if only one type of package was - requested, and no packages belonging to that category were found, then no - output (including the ``DESCRIPTION``) is printed or added to the ``VAR`` - variable. + .. versionadded:: 3.8 + If the ``QUIET_ON_EMPTY`` option is used, if only one type of package was + requested, and no packages belonging to that category were found, then no + output (including the ``DESCRIPTION``) is printed or added to the ``VAR`` + variable. Example 1, append everything to a file: @@ -617,6 +624,9 @@ endfunction() be displayed using ``feature_summary()`` for ``ENABLED_FEATURES`` and ``DISABLED_FEATURES`` respectively. + .. versionchanged:: 3.8 + ``<enabled>`` can be a list of conditions. + Example for setting the info for a feature: .. code-block:: cmake diff --git a/Modules/FetchContent.cmake b/Modules/FetchContent.cmake index 40cc362142..8fabcdc9e0 100644 --- a/Modules/FetchContent.cmake +++ b/Modules/FetchContent.cmake @@ -77,6 +77,9 @@ operation and would not normally be the way the module is used, but it is sometimes useful as part of implementing some higher level feature or to populate some content in CMake's script mode. +.. versionchanged:: 3.14 + ``FetchContent`` commands can access the terminal. This is necessary + for password prompts and real-time progress displays to work. Commands ^^^^^^^^ @@ -371,6 +374,8 @@ is simpler and provides additional features over the pattern above. :variable:`CMAKE_MAKE_PROGRAM` variables will need to be set appropriately on the command line invoking the script. + .. versionadded:: 3.18 + Added support for ``DOWNLOAD_NO_EXTRACT`` and ``SOURCE_SUBDIR`` options. .. command:: FetchContent_GetProperties @@ -416,6 +421,8 @@ is simpler and provides additional features over the pattern above. FetchContent_MakeAvailable( <name1> [<name2>...] ) + .. versionadded:: 3.14 + This command implements the common pattern typically needed for most dependencies. It iterates over each of the named dependencies in turn and for each one it loosely follows the diff --git a/Modules/FindALSA.cmake b/Modules/FindALSA.cmake index 88e2681eb5..627866a4d0 100644 --- a/Modules/FindALSA.cmake +++ b/Modules/FindALSA.cmake @@ -12,6 +12,8 @@ Find the alsa libraries (``asound``) IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.12 + This module defines :prop_tgt:`IMPORTED` target ``ALSA::ALSA``, if ALSA has been found. diff --git a/Modules/FindArmadillo.cmake b/Modules/FindArmadillo.cmake index c8a31a0386..f959356b27 100644 --- a/Modules/FindArmadillo.cmake +++ b/Modules/FindArmadillo.cmake @@ -8,6 +8,9 @@ FindArmadillo Find the Armadillo C++ library. Armadillo is a library for linear algebra & scientific computing. +.. versionadded:: 3.18 + Support for linking wrapped libraries directly (``ARMA_DONT_USE_WRAPPER``). + Using Armadillo: :: diff --git a/Modules/FindBISON.cmake b/Modules/FindBISON.cmake index 1e1a5a3b41..3515bf0ddd 100644 --- a/Modules/FindBISON.cmake +++ b/Modules/FindBISON.cmake @@ -35,21 +35,31 @@ the path to a yacc file. ``<CodeOutput>`` is the name of the source file generated by bison. A header file is also be generated, and contains the token list. +.. versionchanged:: 3.14 + When :policy:`CMP0088` is set to ``NEW``, ``bison`` runs in the + :variable:`CMAKE_CURRENT_BINARY_DIR` directory. + The options are: ``COMPILE_FLAGS <flags>`` Specify flags to be added to the ``bison`` command line. ``DEFINES_FILE <file>`` + .. versionadded:: 3.4 + Specify a non-default header ``<file>`` to be generated by ``bison``. ``VERBOSE [<file>]`` Tell ``bison`` to write a report file of the grammar and parser. - If ``<file>`` is given, it specifies path the report file is copied to. - ``[<file>]`` is left for backward compatibility of this module. - Use ``VERBOSE REPORT_FILE <file>``. + + .. deprecated:: 3.7 + If ``<file>`` is given, it specifies path the report file is copied to. + ``[<file>]`` is left for backward compatibility of this module. + Use ``VERBOSE REPORT_FILE <file>``. ``REPORT_FILE <file>`` + .. versionadded:: 3.7 + Specify a non-default report ``<file>``, if generated. The macro defines the following variables: diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index 715049bbab..93c0a1123c 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake @@ -55,16 +55,39 @@ The following variables may be set to influence this module's behavior: * ``Arm_ilp64_mp`` * ``Generic`` + .. versionadded:: 3.6 + ``OpenBLAS`` support. + + .. versionadded:: 3.11 + ``FLAME`` support. + + .. versionadded:: 3.13 + Added ILP64 MKL variants (``Intel10_64ilp``, ``Intel10_64ilp_seq``). + + .. versionadded:: 3.17 + Added single dynamic library MKL variant (``Intel10_64_dyn``). + + .. versionadded:: 3.18 + Arm Performance Libraries support (``Arm``, ``Arm_mp``, ``Arm_ilp64``, + ``Arm_ilp64_mp``). + + .. versionadded:: 3.19 + ``FlexiBLAS`` support. + ``BLA_F95`` if ``ON`` tries to find the BLAS95 interfaces ``BLA_PREFER_PKGCONFIG`` + .. versionadded:: 3.11 + if set ``pkg-config`` will be used to search for a BLAS library first and if one is found that is preferred Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.18 + This module defines the following :prop_tgt:`IMPORTED` target: ``BLAS::BLAS`` @@ -104,10 +127,13 @@ This module defines the following variables: Hints ^^^^^ -Set the ``MKLROOT`` environment variable to a directory that contains an MKL -installation, or add the directory to the dynamic library loader environment -variable for your platform (``LIB``, ``DYLD_LIBRARY_PATH`` or -``LD_LIBRARY_PATH``). +``MKLROOT`` + .. versionadded:: 3.15 + + Set this environment variable to a directory that contains an MKL + installation, or add the directory to the dynamic library loader environment + variable for your platform (``LIB``, ``DYLD_LIBRARY_PATH`` or + ``LD_LIBRARY_PATH``). #]=======================================================================] diff --git a/Modules/FindBZip2.cmake b/Modules/FindBZip2.cmake index 5704d1d83c..355c4bb96b 100644 --- a/Modules/FindBZip2.cmake +++ b/Modules/FindBZip2.cmake @@ -10,6 +10,8 @@ Try to find BZip2 IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.12 + This module defines :prop_tgt:`IMPORTED` target ``BZip2::BZip2``, if BZip2 has been found. @@ -21,7 +23,8 @@ This module defines the following variables: ``BZIP2_FOUND`` system has BZip2 ``BZIP2_INCLUDE_DIRS`` - the BZip2 include directories + .. versionadded:: 3.12 + the BZip2 include directories ``BZIP2_LIBRARIES`` Link these to use BZip2 ``BZIP2_NEED_PREFIX`` diff --git a/Modules/FindBoost.cmake b/Modules/FindBoost.cmake index 4683853749..e41e8643f4 100644 --- a/Modules/FindBoost.cmake +++ b/Modules/FindBoost.cmake @@ -24,6 +24,18 @@ This module finds headers and requested component libraries OR a CMake package configuration file provided by a "Boost CMake" build. For the latter case skip to the :ref:`Boost CMake` section below. +.. versionadded:: 3.7 + ``bzip2`` and ``zlib`` components (Windows only). + +.. versionadded:: 3.11 + The ``OPTIONAL_COMPONENTS`` option. + +.. versionadded:: 3.13 + ``stacktrace_*`` components. + +.. versionadded:: 3.19 + ``bzip2`` and ``zlib`` components on all platforms. + Result Variables ^^^^^^^^^^^^^^^^ @@ -55,8 +67,12 @@ This module defines the following variables: Boost version number in ``X.Y.Z`` format. ``Boost_VERSION`` - If :policy:`CMP0093` policy is set to ``NEW``, same as ``Boost_VERSION_STRING``. - If :policy:`CMP0093` policy is set to ``OLD`` or unset, same as ``Boost_VERSION_MACRO``. + Boost version number in ``X.Y.Z`` format (same as ``Boost_VERSION_STRING``). + + .. versionchanged:: 3.15 + In previous CMake versions, this variable used the raw version string + from the Boost header (same as ``Boost_VERSION_MACRO``). + See policy :policy:`CMP0093`. ``Boost_LIB_VERSION`` Version string appended to library filenames. @@ -78,14 +94,8 @@ This module defines the following variables: information about Boost's automatic linking displayed during compilation -Note that Boost Python components require a Python version suffix -(Boost 1.67 and later), e.g. ``python36`` or ``python27`` for the -versions built against Python 3.6 and 2.7, respectively. This also -applies to additional components using Python including -``mpi_python`` and ``numpy``. Earlier Boost releases may use -distribution-specific suffixes such as ``2``, ``3`` or ``2.7``. -These may also be used as suffixes, but note that they are not -portable. +.. versionadded:: 3.15 + The ``Boost_VERSION_<PART>`` variables. Cache variables ^^^^^^^^^^^^^^^ @@ -107,6 +117,10 @@ Search results are saved persistently in CMake cache entries: ``Boost_<COMPONENT>_LIBRARY_RELEASE`` Component ``<COMPONENT>`` library release variant. +.. versionadded:: 3.3 + Per-configuration variables ``Boost_LIBRARY_DIR_RELEASE`` and + ``Boost_LIBRARY_DIR_DEBUG``. + Hints ^^^^^ @@ -151,11 +165,16 @@ search results affected by the changes and searches again. Imported Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.5 + This module defines the following :prop_tgt:`IMPORTED` targets: -``Boost::headers`` +``Boost::boost`` Target for header-only dependencies. (Boost include directory). - ``Boost::boost`` is an alias. + +``Boost::headers`` + .. versionadded:: 3.15 + Alias for ``Boost::boost``. ``Boost::<component>`` Target for specific component dependency (shared or static library); @@ -193,10 +212,14 @@ Users or projects may tell this module which variant to find by setting variables: ``Boost_USE_DEBUG_LIBS`` + .. versionadded:: 3.10 + Set to ``ON`` or ``OFF`` to specify whether to search and use the debug libraries. Default is ``ON``. ``Boost_USE_RELEASE_LIBS`` + .. versionadded:: 3.10 + Set to ``ON`` or ``OFF`` to specify whether to search and use the release libraries. Default is ``ON``. @@ -229,15 +252,22 @@ setting variables: ``Boost_COMPILER`` Set to the compiler-specific library suffix (e.g. ``-gcc43``). Default is - auto-computed for the C++ compiler in use. A list may be used if multiple - compatible suffixes should be tested for, in decreasing order of preference. + auto-computed for the C++ compiler in use. + + .. versionchanged:: 3.9 + A list may be used if multiple compatible suffixes should be tested for, + in decreasing order of preference. ``Boost_LIB_PREFIX`` + .. versionadded:: 3.18 + Set to the platform-specific library name prefix (e.g. ``lib``) used by Boost static libs. This is needed only on platforms where CMake does not know the prefix by default. ``Boost_ARCHITECTURE`` + .. versionadded:: 3.13 + Set to the architecture-specific library suffix (e.g. ``-x64``). Default is auto-computed for the C++ compiler in use. diff --git a/Modules/FindCUDA.cmake b/Modules/FindCUDA.cmake index 34d5d24b6c..6daf81dcbb 100644 --- a/Modules/FindCUDA.cmake +++ b/Modules/FindCUDA.cmake @@ -4,12 +4,6 @@ FindCUDA .. deprecated:: 3.10 - Superseded by first-class support for the CUDA language in CMake. - Superseded by the :module:`FindCUDAToolkit` for CUDA toolkit libraries. - -Replacement -^^^^^^^^^^^ - It is no longer necessary to use this module or call ``find_package(CUDA)`` for compiling CUDA code. Instead, list ``CUDA`` among the languages named in the top-level call to the :command:`project` command, or call the @@ -17,9 +11,10 @@ in the top-level call to the :command:`project` command, or call the Then one can add CUDA (``.cu``) sources to programs directly in calls to :command:`add_library` and :command:`add_executable`. -To find and use the CUDA toolkit libraries the :module:`FindCUDAToolkit` -module has superseded this module. It works whether or not the ``CUDA`` -language is enabled. +.. versionadded:: 3.17 + To find and use the CUDA toolkit libraries the :module:`FindCUDAToolkit` + module has superseded this module. It works whether or not the ``CUDA`` + language is enabled. Documentation of Deprecated Usage ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -30,6 +25,9 @@ This script locates the NVIDIA CUDA C tools. It should work on Linux, Windows, and macOS and should be reasonably up to date with CUDA C releases. +.. versionadded:: 3.19 + QNX support. + This script makes use of the standard :command:`find_package` arguments of ``<VERSION>``, ``REQUIRED`` and ``QUIET``. ``CUDA_FOUND`` will report if an acceptable version of CUDA was found. @@ -94,6 +92,8 @@ or ``cuda_wrap_srcs()``: when ``CUDA_BUILD_EMULATION`` is ``TRUE``. ``CUDA_LINK_LIBRARIES_KEYWORD`` (Default: ``""``) + .. versionadded:: 3.9 + The ``<PRIVATE|PUBLIC|INTERFACE>`` keyword to use for internal :command:`target_link_libraries` calls. The default is to use no keyword which uses the old "plain" form of :command:`target_link_libraries`. Note that is matters @@ -116,13 +116,19 @@ or ``cuda_wrap_srcs()``: the host compiler is constructed with one or more visual studio macros such as ``$(VCInstallDir)``, that expands out to the path when the command is run from within VS. - If the :envvar:`CUDAHOSTCXX` environment variable is set it will - be used as the default. + + .. versionadded:: 3.13 + If the :envvar:`CUDAHOSTCXX` environment variable is set it will + be used as the default. ``CUDA_NVCC_FLAGS``, ``CUDA_NVCC_FLAGS_<CONFIG>`` Additional NVCC command line arguments. NOTE: multiple arguments must be semi-colon delimited (e.g. ``--compiler-options;-Wall``) + .. versionadded:: 3.6 + Contents of these variables may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``CUDA_PROPAGATE_HOST_FLAGS`` (Default: ``ON``) Set to ``ON`` to propagate :variable:`CMAKE_{C,CXX}_FLAGS <CMAKE_<LANG>_FLAGS>` and their configuration dependent counterparts (e.g. ``CMAKE_C_FLAGS_DEBUG``) automatically to the @@ -142,6 +148,8 @@ or ``cuda_wrap_srcs()``: ``cuda_link_separable_compilation_objects()`` should be called. ``CUDA_SOURCE_PROPERTY_FORMAT`` + .. versionadded:: 3.3 + If this source file property is set, it can override the format specified to ``cuda_wrap_srcs()`` (``OBJ``, ``PTX``, ``CUBIN``, or ``FATBIN``). If an input source file is not a ``.cu`` file, setting this file will cause it to be treated as a ``.cu`` @@ -149,6 +157,8 @@ or ``cuda_wrap_srcs()``: this property. ``CUDA_USE_STATIC_CUDA_RUNTIME`` (Default: ``ON``) + .. versionadded:: 3.3 + When enabled the static version of the CUDA runtime library will be used in ``CUDA_LIBRARIES``. If the version of CUDA configured doesn't support this option, then it will be silently disabled. @@ -227,12 +237,16 @@ Returns a list of ``PTX`` files generated from the input source files. cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...]) +.. versionadded:: 3.1 + Returns a list of ``FATBIN`` files generated from the input source files. .. code-block:: cmake cuda_compile_cubin(<generated_files> <file>... [OPTIONS ...]) +.. versionadded:: 3.1 + Returns a list of ``CUBIN`` files generated from the input source files. .. code-block:: cmake @@ -374,7 +388,8 @@ The script defines the following variables: Full version in the ``X.Y`` format. ``CUDA_HAS_FP16`` - Whether a short float (``float16``, ``fp16``) is supported. + .. versionadded:: 3.6 + Whether a short float (``float16``, ``fp16``) is supported. ``CUDA_TOOLKIT_ROOT_DIR`` Path to the CUDA Toolkit (defined if not set). @@ -407,7 +422,8 @@ The script defines the following variables: Only available for CUDA version 5.5+. ``CUDA_cudadevrt_LIBRARY`` - Device runtime library. Required for separable compilation. + .. versionadded:: 3.7 + Device runtime library. Required for separable compilation. ``CUDA_cupti_LIBRARY`` CUDA Profiling Tools Interface library. @@ -418,8 +434,9 @@ The script defines the following variables: Only available for CUDA version 3.2+. ``CUDA_cusolver_LIBRARY`` - CUDA Direct Solver library. - Only available for CUDA version 7.0+. + .. versionadded:: 3.2 + CUDA Direct Solver library. + Only available for CUDA version 7.0+. ``CUDA_cusparse_LIBRARY`` CUDA Sparse Matrix library. @@ -493,12 +510,14 @@ The script defines the following variables: Windows only. ``CUDA_nvToolsExt_LIBRARY`` - NVIDA CUDA Tools Extension library. - Available for CUDA version 5+. + .. versionadded:: 3.16 + NVIDA CUDA Tools Extension library. + Available for CUDA version 5+. ``CUDA_OpenCL_LIBRARY`` - NVIDA CUDA OpenCL library. - Available for CUDA version 5+. + .. versionadded:: 3.16 + NVIDA CUDA OpenCL library. + Available for CUDA version 5+. #]=======================================================================] diff --git a/Modules/FindCUDAToolkit.cmake b/Modules/FindCUDAToolkit.cmake index b3c8569bfa..61e264b61c 100644 --- a/Modules/FindCUDAToolkit.cmake +++ b/Modules/FindCUDAToolkit.cmake @@ -11,6 +11,9 @@ This script locates the NVIDIA CUDA toolkit and the associated libraries, but does not require the ``CUDA`` language be enabled for a given project. This module does not search for the NVIDIA CUDA Samples. +.. versionadded:: 3.19 + QNX support. + Search Behavior ^^^^^^^^^^^^^^^ @@ -426,6 +429,8 @@ Result variables Runtime library ``cudart``. ``CUDAToolkit_LIBRARY_ROOT`` + .. versionadded:: 3.18 + The path to the CUDA Toolkit directory containing the nvvm directory and version.txt. diff --git a/Modules/FindCURL.cmake b/Modules/FindCURL.cmake index 74b36c6f7c..e37d22591c 100644 --- a/Modules/FindCURL.cmake +++ b/Modules/FindCURL.cmake @@ -7,8 +7,11 @@ FindCURL Find the native CURL headers and libraries. -This module accept optional COMPONENTS to check supported features and -protocols:: +.. versionadded:: 3.14 + This module accept optional COMPONENTS to check supported features and + protocols: + +:: PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP @@ -18,6 +21,8 @@ protocols:: IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.12 + This module defines :prop_tgt:`IMPORTED` target ``CURL::libcurl``, if curl has been found. @@ -38,9 +43,14 @@ This module defines the following variables: ``CURL_VERSION_STRING`` The version of ``curl`` found. +.. versionadded:: 3.13 + Debug and Release variants are found separately. + CURL CMake ^^^^^^^^^^ +.. versionadded:: 3.17 + If CURL was built using the CMake buildsystem then it provides its own ``CURLConfig.cmake`` file for use with the :command:`find_package` command's config mode. This module looks for this file and, if found, diff --git a/Modules/FindCups.cmake b/Modules/FindCups.cmake index 4e8232d072..cf0d3416a7 100644 --- a/Modules/FindCups.cmake +++ b/Modules/FindCups.cmake @@ -13,6 +13,8 @@ features this function (i.e. at least ``1.1.19``) Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.15 + This module defines :prop_tgt:`IMPORTED` target ``Cups::Cups``, if Cups has been found. diff --git a/Modules/FindCurses.cmake b/Modules/FindCurses.cmake index cde3a4d2d7..5e25deb68e 100644 --- a/Modules/FindCurses.cmake +++ b/Modules/FindCurses.cmake @@ -19,6 +19,8 @@ This module defines the following variables: ``CURSES_LIBRARIES`` The libraries needed to use Curses. ``CURSES_CFLAGS`` + .. versionadded:: 3.16 + Parameters which ought be given to C/C++ compilers when using Curses. ``CURSES_HAVE_CURSES_H`` True if curses.h is available. @@ -31,8 +33,10 @@ This module defines the following variables: Set ``CURSES_NEED_NCURSES`` to ``TRUE`` before the ``find_package(Curses)`` call if NCurses functionality is required. -Set ``CURSES_NEED_WIDE`` to ``TRUE`` before the -``find_package(Curses)`` call if unicode functionality is required. + +.. versionadded:: 3.10 + Set ``CURSES_NEED_WIDE`` to ``TRUE`` before the + ``find_package(Curses)`` call if unicode functionality is required. Backward Compatibility ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Modules/FindDoxygen.cmake b/Modules/FindDoxygen.cmake index 81fbbb7585..bbf941efb1 100644 --- a/Modules/FindDoxygen.cmake +++ b/Modules/FindDoxygen.cmake @@ -6,8 +6,7 @@ FindDoxygen ----------- Doxygen is a documentation generation tool (see http://www.doxygen.org). -This module looks for Doxygen and some optional tools it supports. These -tools are enabled as components in the :command:`find_package` command: +This module looks for Doxygen and some optional tools it supports: ``dot`` `Graphviz <http://graphviz.org>`_ ``dot`` utility used to render various @@ -19,7 +18,9 @@ tools are enabled as components in the :command:`find_package` command: `Dia <https://wiki.gnome.org/Apps/Dia>`_ the diagram editor used by Doxygen's ``\diafile`` command. -Examples: +.. versionadded:: 3.9 + These tools are available as components in the :command:`find_package` command. + For example: .. code-block:: cmake @@ -38,12 +39,13 @@ The following variables are defined by this module: The version reported by ``doxygen --version``. -The module defines ``IMPORTED`` targets for Doxygen and each component found. -These can be used as part of custom commands, etc. and should be preferred over -old-style (and now deprecated) variables like ``DOXYGEN_EXECUTABLE``. The -following import targets are defined if their corresponding executable could be -found (the component import targets will only be defined if that component was -requested): +.. versionadded:: 3.9 + The module defines ``IMPORTED`` targets for Doxygen and each component found. + These can be used as part of custom commands, etc. and should be preferred over + old-style (and now deprecated) variables like ``DOXYGEN_EXECUTABLE``. The + following import targets are defined if their corresponding executable could be + found (the component import targets will only be defined if that component was + requested): :: @@ -58,6 +60,8 @@ Functions .. command:: doxygen_add_docs + .. versionadded:: 3.9 + This function is intended as a convenience for adding a target for generating documentation with Doxygen. It aims to provide sensible defaults so that projects can generally just provide the input files and directories and that @@ -93,19 +97,21 @@ Functions the :command:`add_custom_target` command used to create the custom target internally. - If ``ALL`` is set, the target will be added to the default build target. - - If ``USE_STAMP_FILE`` is set, the custom command defined by this function will - create a stamp file with the name ``<targetName>.stamp`` in the current - binary directory whenever doxygen is re-run. With this option present, all - items in ``<filesOrDirs>`` must be files (i.e. no directories, symlinks or - wildcards) and each of the files must exist at the time - ``doxygen_add_docs()`` is called. An error will be raised if any of the - items listed is missing or is not a file when ``USE_STAMP_FILE`` is given. - A dependency will be created on each of the files so that doxygen will only - be re-run if one of the files is updated. Without the ``USE_STAMP_FILE`` - option, doxygen will always be re-run if the ``<targetName>`` target is built - regardless of whether anything listed in ``<filesOrDirs>`` has changed. + .. versionadded:: 3.12 + If ``ALL`` is set, the target will be added to the default build target. + + .. versionadded:: 3.16 + If ``USE_STAMP_FILE`` is set, the custom command defined by this function will + create a stamp file with the name ``<targetName>.stamp`` in the current + binary directory whenever doxygen is re-run. With this option present, all + items in ``<filesOrDirs>`` must be files (i.e. no directories, symlinks or + wildcards) and each of the files must exist at the time + ``doxygen_add_docs()`` is called. An error will be raised if any of the + items listed is missing or is not a file when ``USE_STAMP_FILE`` is given. + A dependency will be created on each of the files so that doxygen will only + be re-run if one of the files is updated. Without the ``USE_STAMP_FILE`` + option, doxygen will always be re-run if the ``<targetName>`` target is built + regardless of whether anything listed in ``<filesOrDirs>`` has changed. The contents of the generated ``Doxyfile`` can be customized by setting CMake variables before calling ``doxygen_add_docs()``. Any variable with a name of @@ -308,18 +314,19 @@ if they contain at least one space: WARN_LOGFILE XML_OUTPUT -There are situations where it may be undesirable for a particular config option -to be automatically quoted by ``doxygen_add_docs()``, such as ``ALIASES`` which -may need to include its own embedded quoting. The ``DOXYGEN_VERBATIM_VARS`` -variable can be used to specify a list of Doxygen variables (including the -leading ``DOXYGEN_`` prefix) which should not be quoted. The project is then -responsible for ensuring that those variables' values make sense when placed -directly in the Doxygen input file. In the case of list variables, list items -are still separated by spaces, it is only the automatic quoting that is -skipped. For example, the following allows ``doxygen_add_docs()`` to apply -quoting to ``DOXYGEN_PROJECT_BRIEF``, but not each item in the -``DOXYGEN_ALIASES`` list (:ref:`bracket syntax <Bracket Argument>` can also -be used to make working with embedded quotes easier): +.. versionadded:: 3.11 + There are situations where it may be undesirable for a particular config option + to be automatically quoted by ``doxygen_add_docs()``, such as ``ALIASES`` which + may need to include its own embedded quoting. The ``DOXYGEN_VERBATIM_VARS`` + variable can be used to specify a list of Doxygen variables (including the + leading ``DOXYGEN_`` prefix) which should not be quoted. The project is then + responsible for ensuring that those variables' values make sense when placed + directly in the Doxygen input file. In the case of list variables, list items + are still separated by spaces, it is only the automatic quoting that is + skipped. For example, the following allows ``doxygen_add_docs()`` to apply + quoting to ``DOXYGEN_PROJECT_BRIEF``, but not each item in the + ``DOXYGEN_ALIASES`` list (:ref:`bracket syntax <Bracket Argument>` can also + be used to make working with embedded quotes easier): .. code-block:: cmake @@ -341,6 +348,8 @@ The resultant ``Doxyfile`` will contain the following lines: Deprecated Result Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. deprecated:: 3.9 + For compatibility with previous versions of CMake, the following variables are also defined but they are deprecated and should no longer be used: @@ -375,6 +384,8 @@ are also defined but they are deprecated and should no longer be used: Deprecated Hint Variables ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. deprecated:: 3.9 + .. variable:: DOXYGEN_SKIP_DOT This variable has no effect for the component form of ``find_package``. diff --git a/Modules/FindEXPAT.cmake b/Modules/FindEXPAT.cmake index b0bb02a566..f9cb432078 100644 --- a/Modules/FindEXPAT.cmake +++ b/Modules/FindEXPAT.cmake @@ -11,6 +11,8 @@ Expat is a stream-oriented XML parser library written in C. Imported Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.10 + This module defines the following :prop_tgt:`IMPORTED` targets: ``EXPAT::EXPAT`` diff --git a/Modules/FindFLEX.cmake b/Modules/FindFLEX.cmake index 13847367d0..e67e931125 100644 --- a/Modules/FindFLEX.cmake +++ b/Modules/FindFLEX.cmake @@ -37,11 +37,20 @@ If flex is found on the system, the module provides the macro: ) which creates a custom command to generate the ``FlexOutput`` file from -the ``FlexInput`` file. If ``COMPILE_FLAGS`` option is specified, the next -parameter is added to the flex command line. If flex is configured to -output a header file, the ``DEFINES_FILE`` option may be used to specify its -name. Name is an alias used to get details of this custom command. -Indeed the macro defines the following variables: +the ``FlexInput`` file. Name is an alias used to get details of this custom +command. If ``COMPILE_FLAGS`` option is specified, the next +parameter is added to the flex command line. + +.. versionadded:: 3.5 + If flex is configured to + output a header file, the ``DEFINES_FILE`` option may be used to specify its + name. + +.. versionchanged:: 3.17 + When :policy:`CMP0098` is set to ``NEW``, ``flex`` runs in the + :variable:`CMAKE_CURRENT_BINARY_DIR` directory. + +The macro defines the following variables: :: diff --git a/Modules/FindFLTK.cmake b/Modules/FindFLTK.cmake index e273642b5f..e1e239a662 100644 --- a/Modules/FindFLTK.cmake +++ b/Modules/FindFLTK.cmake @@ -77,6 +77,10 @@ The following cache variables are also available to set or use: ``FLTK_IMAGES_LIBRARY_DEBUG`` The FLTK Images library (debug) + +.. versionadded:: 3.11 + Debug and Release variants are found separately and use per-configuration + variables. #]=======================================================================] if(NOT FLTK_SKIP_OPENGL) diff --git a/Modules/FindFreetype.cmake b/Modules/FindFreetype.cmake index 3e6a177dcc..82885cb2f1 100644 --- a/Modules/FindFreetype.cmake +++ b/Modules/FindFreetype.cmake @@ -10,6 +10,8 @@ Find the FreeType font renderer includes and library. Imported Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.10 + This module defines the following :prop_tgt:`IMPORTED` target: ``Freetype::Freetype`` @@ -33,7 +35,10 @@ This module will set the following variables in your project: ``FREETYPE_LIBRARIES`` the library to link against ``FREETYPE_VERSION_STRING`` - the version of freetype found (since CMake 2.8.8) + the version of freetype found + +.. versionadded:: 3.7 + Debug and Release variants are found separately. Hints ^^^^^ diff --git a/Modules/FindGDAL.cmake b/Modules/FindGDAL.cmake index fde84d4889..406a7387f9 100644 --- a/Modules/FindGDAL.cmake +++ b/Modules/FindGDAL.cmake @@ -10,6 +10,8 @@ Find Geospatial Data Abstraction Library (GDAL). IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.14 + This module defines :prop_tgt:`IMPORTED` target ``GDAL::GDAL`` if GDAL has been found. @@ -25,7 +27,8 @@ This module will set the following variables in your project: ``GDAL_LIBRARIES`` Libraries to link to GDAL. ``GDAL_VERSION`` - The version of GDAL found. + .. versionadded:: 3.14 + The version of GDAL found. Cache variables ^^^^^^^^^^^^^^^ diff --git a/Modules/FindGLEW.cmake b/Modules/FindGLEW.cmake index 187b6a8d2f..b9ebe08bd6 100644 --- a/Modules/FindGLEW.cmake +++ b/Modules/FindGLEW.cmake @@ -21,6 +21,8 @@ The following variables may be set to influence this module's behavior: Imported Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.1 + This module defines the following :ref:`Imported Targets <Imported Targets>`: @@ -55,6 +57,9 @@ This module defines the following variables: ``GLEW_VERSION_MICRO`` GLEW micro version +.. versionadded:: 3.7 + Debug and Release variants are found separately. + #]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake) diff --git a/Modules/FindGLUT.cmake b/Modules/FindGLUT.cmake index a22bf5bca8..c81d97101e 100644 --- a/Modules/FindGLUT.cmake +++ b/Modules/FindGLUT.cmake @@ -10,6 +10,8 @@ Find OpenGL Utility Toolkit (GLUT) library and include files. IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.1 + This module defines the :prop_tgt:`IMPORTED` targets: ``GLUT::GLUT`` @@ -33,6 +35,9 @@ Also defined, but not for general use are: GLUT_glut_LIBRARY = the full path to the glut library. GLUT_Xmu_LIBRARY = the full path to the Xmu library. GLUT_Xi_LIBRARY = the full path to the Xi Library. + +.. versionadded:: 3.13 + Debug and Release variants are found separately. #]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/SelectLibraryConfigurations.cmake) diff --git a/Modules/FindGTK2.cmake b/Modules/FindGTK2.cmake index 62f1614f8c..7036b66d48 100644 --- a/Modules/FindGTK2.cmake +++ b/Modules/FindGTK2.cmake @@ -16,6 +16,23 @@ module. See example below. * ``glade`` * ``glademm`` +Imported Targets +^^^^^^^^^^^^^^^^ + +This module defines the following :prop_tgt:`IMPORTED` targets (subject to +component selection): + +``GTK2::atk``, ``GTK2::atkmm``, ``GTK2::cairo``, ``GTK2::cairomm``, +``GTK2::gdk_pixbuf``, ``GTK2::gdk``, ``GTK2::gdkmm``, ``GTK2::gio``, +``GTK2::giomm``, ``GTK2::glade``, ``GTK2::glademm``, ``GTK2::glib``, +``GTK2::glibmm``, ``GTK2::gmodule``, ``GTK2::gobject``, ``GTK2::gthread``, +``GTK2::gtk``, ``GTK2::gtkmm``, ``GTK2::harfbuzz``, ``GTK2::pango``, +``GTK2::pangocairo``, ``GTK2::pangoft2``, ``GTK2::pangomm``, +``GTK2::pangoxft``, ``GTK2::sigc``. + +.. versionadded:: 3.16.7 + Added the ``GTK2::harfbuzz`` target. + Result Variables ^^^^^^^^^^^^^^^^ @@ -28,7 +45,8 @@ The following variables will be defined for your use ``GTK2_LIBRARIES`` All libraries ``GTK2_TARGETS`` - All imported targets + .. versionadded:: 3.5 + All imported targets ``GTK2_DEFINITIONS`` Additional compiler flags ``GTK2_VERSION`` @@ -40,6 +58,10 @@ The following variables will be defined for your use ``GTK2_PATCH_VERSION`` The patch version of GTK2 +.. versionadded:: 3.5 + When ``GTK2_USE_IMPORTED_TARGETS`` is set to ``TRUE``, ``GTK2_LIBRARIES`` + will list imported targets instead of library paths. + Input Variables ^^^^^^^^^^^^^^^ diff --git a/Modules/FindGTest.cmake b/Modules/FindGTest.cmake index 43808646c0..8e22f79198 100644 --- a/Modules/FindGTest.cmake +++ b/Modules/FindGTest.cmake @@ -7,10 +7,14 @@ FindGTest Locate the Google C++ Testing Framework. +.. versionadded:: 3.20 + Upstream ``GTestConfig.cmake`` is used if possible. + Imported targets ^^^^^^^^^^^^^^^^ -This module defines the following :prop_tgt:`IMPORTED` targets: +.. versionadded:: 3.20 + This module defines the following :prop_tgt:`IMPORTED` targets: ``GTest::gtest`` The Google Test ``gtest`` library, if found; adds Thread::Thread @@ -18,8 +22,9 @@ This module defines the following :prop_tgt:`IMPORTED` targets: ``GTest::gtest_main`` The Google Test ``gtest_main`` library, if found -For backwards compatibility, this module defines additionally the -following deprecated :prop_tgt:`IMPORTED` targets: +.. deprecated:: 3.20 + For backwards compatibility, this module defines additionally the + following deprecated :prop_tgt:`IMPORTED` targets (available since 3.5): ``GTest::GTest`` The Google Test ``gtest`` library, if found; adds Thread::Thread @@ -81,6 +86,10 @@ Deeper integration with CTest See :module:`GoogleTest` for information on the :command:`gtest_add_tests` and :command:`gtest_discover_tests` commands. + +.. versionchanged:: 3.9 + Previous CMake versions defined :command:`gtest_add_tests` macro in this + module. #]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/GoogleTest.cmake) diff --git a/Modules/FindGettext.cmake b/Modules/FindGettext.cmake index 213ad13de0..252f2aea27 100644 --- a/Modules/FindGettext.cmake +++ b/Modules/FindGettext.cmake @@ -54,7 +54,7 @@ PO_FILES <po1> <po2> ... ) If ALL is specified, the po files are processed when building the all traget. It creates a custom target "pofiles". -.. note:: +.. versionadded:: 3.2 If you wish to use the Gettext library (libintl), use :module:`FindIntl`. #]=======================================================================] diff --git a/Modules/FindGit.cmake b/Modules/FindGit.cmake index 3491cdcc2f..f8346b61d0 100644 --- a/Modules/FindGit.cmake +++ b/Modules/FindGit.cmake @@ -5,12 +5,6 @@ FindGit ------- -The module defines the following ``IMPORTED`` targets (when -:prop_gbl:`CMAKE_ROLE` is ``PROJECT``): - -``Git::Git`` - Executable of the Git command-line client. - The module defines the following variables: ``GIT_EXECUTABLE`` @@ -20,6 +14,13 @@ The module defines the following variables: ``GIT_VERSION_STRING`` The version of Git found. +.. versionadded:: 3.14 + The module defines the following ``IMPORTED`` targets (when + :prop_gbl:`CMAKE_ROLE` is ``PROJECT``): + +``Git::Git`` + Executable of the Git command-line client. + Example usage: .. code-block:: cmake diff --git a/Modules/FindGnuTLS.cmake b/Modules/FindGnuTLS.cmake index 819f000121..782a72b2fe 100644 --- a/Modules/FindGnuTLS.cmake +++ b/Modules/FindGnuTLS.cmake @@ -10,6 +10,8 @@ Find the GNU Transport Layer Security library (gnutls) IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.16 + This module defines :prop_tgt:`IMPORTED` target ``GnuTLS::GnuTLS``, if gnutls has been found. diff --git a/Modules/FindHDF5.cmake b/Modules/FindHDF5.cmake index 0a92c71404..068edcf7ad 100644 --- a/Modules/FindHDF5.cmake +++ b/Modules/FindHDF5.cmake @@ -32,6 +32,9 @@ static link to a dynamic link for ``HDF5`` and all of it's dependencies. To use this feature, make sure that the ``HDF5_USE_STATIC_LIBRARIES`` variable is set before the call to find_package. +.. versionadded:: 3.10 + Support for ``HDF5_USE_STATIC_LIBRARIES`` on Windows. + Both the serial and parallel ``HDF5`` wrappers are considered and the first directory to contain either one will be used. In the event that both appear in the same directory the serial version is preferentially selected. This @@ -51,7 +54,8 @@ This module will set the following variables in your project: ``HDF5_FOUND`` HDF5 was found on the system ``HDF5_VERSION`` - HDF5 library version + .. versionadded:: 3.3 + HDF5 library version ``HDF5_INCLUDE_DIRS`` Location of the HDF5 header files ``HDF5_DEFINITIONS`` @@ -128,12 +132,18 @@ Hints The following variables can be set to guide the search for HDF5 libraries and includes: ``HDF5_PREFER_PARALLEL`` + .. versionadded:: 3.4 + set ``true`` to prefer parallel HDF5 (by default, serial is preferred) ``HDF5_FIND_DEBUG`` + .. versionadded:: 3.9 + Set ``true`` to get extra debugging output. ``HDF5_NO_FIND_PACKAGE_CONFIG_FILE`` + .. versionadded:: 3.8 + Set ``true`` to skip trying to find ``hdf5-config.cmake``. #]=======================================================================] diff --git a/Modules/FindHg.cmake b/Modules/FindHg.cmake index 1358363d2a..e9f2c8277c 100644 --- a/Modules/FindHg.cmake +++ b/Modules/FindHg.cmake @@ -15,7 +15,8 @@ The module defines the following variables: HG_FOUND - true if the command line client was found HG_VERSION_STRING - the version of mercurial found -If the command line client executable is found the following macro is defined: +.. versionadded:: 3.1 + If the command line client executable is found the following macro is defined: :: diff --git a/Modules/FindICU.cmake b/Modules/FindICU.cmake index fa0cba393b..2bb49adec1 100644 --- a/Modules/FindICU.cmake +++ b/Modules/FindICU.cmake @@ -18,6 +18,9 @@ Note that on Windows ``data`` is named ``dt`` and ``i18n`` is named ``in``; any of the names may be used, and the appropriate platform-specific library name will be automatically selected. +.. versionadded:: 3.11 + Added support for static libraries on Windows. + This module reports information about the ICU installation in several variables. General variables:: diff --git a/Modules/FindIce.cmake b/Modules/FindIce.cmake index 0f821e886f..543e10c38f 100644 --- a/Modules/FindIce.cmake +++ b/Modules/FindIce.cmake @@ -23,6 +23,15 @@ Ice 3.7 and later also include C++11-specific components: Note that the set of supported components is Ice version-specific. +.. versionadded:: 3.4 + Imported targets for components and most ``EXECUTABLE`` variables. + +.. versionadded:: 3.7 + Debug and Release variants are found separately. + +.. versionadded:: 3.10 + Ice 3.7 support, including new components, programs and the Nuget package. + This module reports information about the Ice installation in several variables. General variables:: @@ -56,6 +65,9 @@ Ice slice programs are reported in:: Ice_SLICE2PY_EXECUTABLE - path to slice2py executable Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable +.. versionadded:: 3.14 + Variables for ``slice2confluence`` and ``slice2matlab``. + Ice programs are reported in:: Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable diff --git a/Modules/FindImageMagick.cmake b/Modules/FindImageMagick.cmake index 8bf5123b76..d7de0ddccf 100644 --- a/Modules/FindImageMagick.cmake +++ b/Modules/FindImageMagick.cmake @@ -7,6 +7,9 @@ FindImageMagick Find ImageMagick binary suite. +.. versionadded:: 3.9 + Added support for ImageMagick 7. + This module will search for a set of ImageMagick tools specified as components in the :command:`find_package` call. Typical components include, but are not limited to (future versions of ImageMagick might have diff --git a/Modules/FindIntl.cmake b/Modules/FindIntl.cmake index d29f554eae..686c818010 100644 --- a/Modules/FindIntl.cmake +++ b/Modules/FindIntl.cmake @@ -15,7 +15,9 @@ installation in several variables. General variables:: Intl_FOUND - true if the libintl headers and libraries were found Intl_INCLUDE_DIRS - the directory containing the libintl headers Intl_LIBRARIES - libintl libraries to be linked - Intl::Intl - imported target for Intl + +.. versionadded:: 3.20 + This module defines :prop_tgt:`IMPORTED` target ``Intl::Intl``. The following cache variables may also be set:: @@ -26,6 +28,10 @@ The following cache variables may also be set:: Intl_IS_BUILTIN - whether intl is a part of the C library determined from the result of Intl_HAVE_GETTEXT_BUILTIN and Intl_HAVE_DCGETTEXT_BUILTIN +.. versionadded:: 3.20 + Added the ``Intl_HAVE_GETTEXT_BUILTIN``, ``Intl_HAVE_DCGETTEXT_BUILTIN`` and + ``Intl_IS_BUILTIN`` variables. + .. note:: On some platforms, such as Linux with GNU libc, the gettext functions are present in the C standard library and libintl diff --git a/Modules/FindJPEG.cmake b/Modules/FindJPEG.cmake index 632fc9aa0f..3f243ded57 100644 --- a/Modules/FindJPEG.cmake +++ b/Modules/FindJPEG.cmake @@ -10,6 +10,8 @@ Find the Joint Photographic Experts Group (JPEG) library (``libjpeg``) Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.12 + This module defines the following :prop_tgt:`IMPORTED` targets: ``JPEG::JPEG`` @@ -27,7 +29,8 @@ This module will set the following variables in your project: ``JPEG_LIBRARIES`` the libraries needed to use JPEG. ``JPEG_VERSION`` - the version of the JPEG library found + .. versionadded:: 3.12 + the version of the JPEG library found Cache variables ^^^^^^^^^^^^^^^ @@ -41,6 +44,9 @@ The following cache variables may also be set: ``JPEG_LIBRARY_DEBUG`` where to find the JPEG library (debug). +.. versionadded:: 3.12 + Debug and Release variand are found separately. + Obsolete variables ^^^^^^^^^^^^^^^^^^ diff --git a/Modules/FindJava.cmake b/Modules/FindJava.cmake index 9db740b4f8..4f0e0feafe 100644 --- a/Modules/FindJava.cmake +++ b/Modules/FindJava.cmake @@ -13,6 +13,9 @@ to specify a Java installation prefix explicitly. See also the :module:`FindJNI` module to find Java Native Interface (JNI). +.. versionadded:: 3.10 + Added support for Java 9+ version parsing. + Specify one or more of the following components as you call this find module. See example below. :: @@ -41,7 +44,9 @@ This module sets the following result variables: Java_VERSION_TWEAK = The tweak version of the package found (after '_') Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]] - +.. versionadded:: 3.4 + Added the ``Java_IDLJ_EXECUTABLE`` and ``Java_JARSIGNER_EXECUTABLE`` + variables. The minimum required version of Java can be specified using the :command:`find_package` syntax, e.g. diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index 4b71cee595..4f769ba819 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake @@ -45,12 +45,33 @@ The following variables may be set to influence this module's behavior: * ``Arm_ilp64_mp`` * ``Generic`` + .. versionadded:: 3.6 + ``OpenBLAS`` support. + + .. versionadded:: 3.11 + ``FLAME`` support. + + .. versionadded:: 3.13 + Added ILP64 MKL variants (``Intel10_64ilp``, ``Intel10_64ilp_seq``). + + .. versionadded:: 3.17 + Added single dynamic library MKL variant (``Intel10_64_dyn``). + + .. versionadded:: 3.18 + Arm Performance Libraries support (``Arm``, ``Arm_mp``, ``Arm_ilp64``, + ``Arm_ilp64_mp``). + + .. versionadded:: 3.19 + ``FlexiBLAS`` support. + ``BLA_F95`` if ``ON`` tries to find the BLAS95/LAPACK95 interfaces Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.18 + This module defines the following :prop_tgt:`IMPORTED` target: ``LAPACK::LAPACK`` diff --git a/Modules/FindLATEX.cmake b/Modules/FindLATEX.cmake index b0dad7da3a..1e82651fe1 100644 --- a/Modules/FindLATEX.cmake +++ b/Modules/FindLATEX.cmake @@ -11,6 +11,10 @@ This module finds an installed LaTeX and determines the location of the compiler. Additionally the module looks for Latex-related software like BibTeX. +.. versionadded:: 3.2 + Component processing; support for htlatex, pdftops, Biber, xindy, XeLaTeX, + LuaLaTeX. + This module sets the following result variables:: LATEX_FOUND: whether found Latex and requested components diff --git a/Modules/FindLibArchive.cmake b/Modules/FindLibArchive.cmake index ce3c8b8e8c..08078a295f 100644 --- a/Modules/FindLibArchive.cmake +++ b/Modules/FindLibArchive.cmake @@ -22,6 +22,10 @@ The module defines the following ``IMPORTED`` targets: :: LibArchive::LibArchive - target for linking against libarchive + +.. versionadded:: 3.6 + Support for new libarchive 3.2 version string format. + #]=======================================================================] find_path(LibArchive_INCLUDE_DIR diff --git a/Modules/FindLibLZMA.cmake b/Modules/FindLibLZMA.cmake index 4a79a1028b..9ec8f075df 100644 --- a/Modules/FindLibLZMA.cmake +++ b/Modules/FindLibLZMA.cmake @@ -11,6 +11,8 @@ Find LZMA compression algorithm headers and library. Imported Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.14 + This module defines :prop_tgt:`IMPORTED` target ``LibLZMA::LibLZMA``, if liblzma has been found. diff --git a/Modules/FindLibXml2.cmake b/Modules/FindLibXml2.cmake index 0631607129..ce28d03026 100644 --- a/Modules/FindLibXml2.cmake +++ b/Modules/FindLibXml2.cmake @@ -10,12 +10,16 @@ Find the XML processing library (libxml2). IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.12 + The following :prop_tgt:`IMPORTED` targets may be defined: ``LibXml2::LibXml2`` - If the libxml2 library has been found + libxml2 library. ``LibXml2::xmllint`` - If the xmllint command-line executable has been found + .. versionadded:: 3.17 + + xmllint command-line executable. Result variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindLibXslt.cmake b/Modules/FindLibXslt.cmake index fc7adeb0f7..97943d6d1d 100644 --- a/Modules/FindLibXslt.cmake +++ b/Modules/FindLibXslt.cmake @@ -11,6 +11,8 @@ Transformations (XSLT) library (LibXslt) IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.18 + The following :prop_tgt:`IMPORTED` targets may be defined: ``LibXslt::LibXslt`` @@ -35,7 +37,8 @@ Additionally, the following two variables are set (but not required for using xslt): ``LIBXSLT_EXSLT_INCLUDE_DIR`` - The include directory for exslt. + .. versionadded:: 3.18 + The include directory for exslt. ``LIBXSLT_EXSLT_LIBRARIES`` Link to these if you need to link against the exslt library. ``LIBXSLT_XSLTPROC_EXECUTABLE`` diff --git a/Modules/FindLua.cmake b/Modules/FindLua.cmake index c4361b74b1..32642fe239 100644 --- a/Modules/FindLua.cmake +++ b/Modules/FindLua.cmake @@ -5,10 +5,11 @@ FindLua ------- - - Locate Lua library. +.. versionadded:: 3.18 + Support for Lua 5.4. + This module defines:: :: diff --git a/Modules/FindMPI.cmake b/Modules/FindMPI.cmake index b531e4740b..19e6e57846 100644 --- a/Modules/FindMPI.cmake +++ b/Modules/FindMPI.cmake @@ -12,6 +12,10 @@ high-performance distributed-memory parallel applications, and is typically deployed on a cluster. MPI is a standard interface (defined by the MPI forum) for which many implementations are available. +.. versionadded:: 3.10 + Major overhaul of the module: many new variables, per-language components, + support for a wider variety of runtimes. + Variables for using MPI ^^^^^^^^^^^^^^^^^^^^^^^ @@ -50,7 +54,8 @@ project, where ``<lang>`` is one of C, CXX, or Fortran: ``MPI_<lang>_LIBRARIES`` All libraries to link MPI programs against. -Additionally, the following :prop_tgt:`IMPORTED` targets are defined: +.. versionadded:: 3.9 + Additionally, the following :prop_tgt:`IMPORTED` targets are defined: ``MPI::MPI_<lang>`` Target for using MPI from ``<lang>``. @@ -236,8 +241,10 @@ If the following variables are set to true, the respective search will be perfor Backward Compatibility ^^^^^^^^^^^^^^^^^^^^^^ +.. deprecated:: 3.10 + For backward compatibility with older versions of FindMPI, these -variables are set, but deprecated: +variables are set: :: diff --git a/Modules/FindMatlab.cmake b/Modules/FindMatlab.cmake index 01f04922f9..8b4c397161 100644 --- a/Modules/FindMatlab.cmake +++ b/Modules/FindMatlab.cmake @@ -17,6 +17,9 @@ can also be used: * to retrieve various information from Matlab (mex extensions, versions and release queries, ...) +.. versionadded:: 3.12 + Added Matlab Compiler Runtime (MCR) support. + The module supports the following components: * ``ENG_LIBRARY`` and ``MAT_LIBRARY``: respectively the ``ENG`` and ``MAT`` @@ -28,6 +31,17 @@ The module supports the following components: * ``MCC_COMPILER`` the MCC compiler, included with the Matlab Compiler add-on. * ``SIMULINK`` the Simulink environment. +.. versionadded:: 3.7 + Added the ``MAT_LIBRARY`` component. + +.. versionadded:: 3.13 + Added the ``ENGINE_LIBRARY``, ``DATAARRAY_LIBRARY`` and ``MCC_COMPILER`` + components. + +.. versionchanged:: 3.14 + Removed the ``MX_LIBRARY``, ``ENGINE_LIBRARY`` and ``DATAARRAY_LIBRARY`` + components. These libraries are found unconditionally. + .. note:: The version given to the :command:`find_package` directive is the Matlab @@ -107,8 +121,12 @@ Result variables Matlab matrix library. Available only if the component ``MAT_LIBRARY`` is requested. ``Matlab_ENGINE_LIBRARY`` + .. versionadded:: 3.13 + Matlab C++ engine library, always available for R2018a and newer. ``Matlab_DATAARRAY_LIBRARY`` + .. versionadded:: 3.13 + Matlab C++ data array library, always available for R2018a and newer. ``Matlab_LIBRARIES`` the whole set of libraries of Matlab @@ -116,6 +134,8 @@ Result variables the mex compiler of Matlab. Currently not used. Available only if the component ``MEX_COMPILER`` is requested. ``Matlab_MCC_COMPILER`` + .. versionadded:: 3.13 + the mcc compiler of Matlab. Included with the Matlab Compiler add-on. Available only if the component ``MCC_COMPILER`` is requested. @@ -923,14 +943,26 @@ endfunction() the same folder without any processing, with the same name as the final mex file, and with extension `.m`. In that case, typing ``help <name>`` in Matlab prints the documentation contained in this file. - ``R2017b`` or ``R2018a`` may be given to specify the version of the C API + ``R2017b`` or ``R2018a`` + .. versionadded:: 3.14 + + May be given to specify the version of the C API to use: ``R2017b`` specifies the traditional (separate complex) C API, and corresponds to the ``-R2017b`` flag for the `mex` command. ``R2018a`` specifies the new interleaved complex C API, and corresponds to the ``-R2018a`` flag for the `mex` command. Ignored if MATLAB version prior to R2018a. Defaults to ``R2017b``. - ``MODULE`` or ``SHARED`` may be given to specify the type of library to be - created. ``EXECUTABLE`` may be given to create an executable instead of + + ``MODULE`` or ``SHARED`` + .. versionadded:: 3.7 + + May be given to specify the type of library to be + created. + + ``EXECUTABLE`` + .. versionadded:: 3.7 + + May be given to create an executable instead of a library. If no type is given explicitly, the type is ``SHARED``. ``EXCLUDE_FROM_ALL`` This option has the same meaning as for :prop_tgt:`EXCLUDE_FROM_ALL` and diff --git a/Modules/FindOpenACC.cmake b/Modules/FindOpenACC.cmake index ed52e3591f..da050cd4fb 100644 --- a/Modules/FindOpenACC.cmake +++ b/Modules/FindOpenACC.cmake @@ -14,6 +14,16 @@ If the compiler supports OpenACC, the flags required to compile with OpenACC support are returned in variables for the different languages. Currently, only PGI, GNU and Cray compilers are supported. +Imported Targets +^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.16 + +The module provides :prop_tgt:`IMPORTED` targets: + +``OpenACC::OpenACC_<lang>`` + Target for using OpenACC from ``<lang>``. + Variables ^^^^^^^^^ @@ -25,14 +35,11 @@ project, where ``<lang>`` is one of C, CXX, or Fortran: ``OpenACC_<lang>_FLAGS`` OpenACC compiler flags for ``<lang>``, separated by spaces. ``OpenACC_<lang>_OPTIONS`` + .. versionadded:: 3.16 + OpenACC compiler flags for ``<lang>``, as a list. Suitable for usage with target_compile_options or target_link_options. -Additionally, the module provides :prop_tgt:`IMPORTED` targets: - -``OpenACC::OpenACC_<lang>`` - Target for using OpenACC from ``<lang>``. - The module will also try to provide the OpenACC version variables: ``OpenACC_<lang>_SPEC_DATE`` diff --git a/Modules/FindOpenCL.cmake b/Modules/FindOpenCL.cmake index b3e5a9f8de..1b4662b76f 100644 --- a/Modules/FindOpenCL.cmake +++ b/Modules/FindOpenCL.cmake @@ -9,9 +9,14 @@ FindOpenCL Finds Open Computing Language (OpenCL) +.. versionadded:: 3.10 + Detection of OpenCL 2.1 and 2.2. + IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.7 + This module defines :prop_tgt:`IMPORTED` target ``OpenCL::OpenCL``, if OpenCL has been found. diff --git a/Modules/FindOpenGL.cmake b/Modules/FindOpenGL.cmake index 110e7f9637..4766102082 100644 --- a/Modules/FindOpenGL.cmake +++ b/Modules/FindOpenGL.cmake @@ -7,27 +7,41 @@ FindOpenGL FindModule for OpenGL and OpenGL Utility Library (GLU). +.. versionchanged:: 3.2 + X11 is no longer added as a dependency on Unix/Linux systems. + +.. versionadded:: 3.10 + GLVND support on Linux. See the :ref:`Linux Specific` section below. + Optional COMPONENTS ^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 3.10 + This module respects several optional COMPONENTS: ``EGL``, ``GLX``, and ``OpenGL``. There are corresponding import targets for each of these flags. IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.8 + This module defines the :prop_tgt:`IMPORTED` targets: ``OpenGL::GL`` - Defined to the platform-specific OpenGL libraries if the system has OpenGL. -``OpenGL::OpenGL`` - Defined to libOpenGL if the system is GLVND-based. + Defined to the platform-specific OpenGL libraries if the system has OpenGL. ``OpenGL::GLU`` - Defined if the system has OpenGL Utility Library (GLU). + Defined if the system has OpenGL Utility Library (GLU). + +.. versionadded:: 3.10 + Additionally, the following GLVND-specific library targets are defined: + +``OpenGL::OpenGL`` + Defined to libOpenGL if the system is GLVND-based. ``OpenGL::GLX`` - Defined if the system has OpenGL Extension to the X Window System (GLX). + Defined if the system has OpenGL Extension to the X Window System (GLX). ``OpenGL::EGL`` - Defined if the system has EGL. + Defined if the system has EGL. Result Variables ^^^^^^^^^^^^^^^^ @@ -55,6 +69,9 @@ This module sets the following variables: On Linux, this assumes GLX and is never correct for EGL-based targets. Clients are encouraged to use the ``OpenGL::*`` import targets instead. +.. versionadded:: 3.10 + Variables for GLVND-specific libraries ``OpenGL``, ``EGL`` and ``GLX``. + Cache variables ^^^^^^^^^^^^^^^ @@ -72,6 +89,11 @@ The following cache variables may also be set: Path to the OpenGL library. New code should prefer the ``OpenGL::*`` import targets. +.. versionadded:: 3.10 + Variables for GLVND-specific libraries ``OpenGL``, ``EGL`` and ``GLX``. + +.. _`Linux Specific`: + Linux-specific ^^^^^^^^^^^^^^ @@ -97,14 +119,14 @@ The value may be one of: ``GLVND`` If the GLVND OpenGL and GLX libraries are available, prefer them. This forces ``OPENGL_gl_LIBRARY`` to be empty. - This is the default if components were requested (since components - correspond to GLVND libraries) or if policy :policy:`CMP0072` is - set to ``NEW``. + + .. versionchanged:: 3.11 + This is the default, unless policy :policy:`CMP0072` is set to ``OLD`` + and no components are requeted (since components + correspond to GLVND libraries). ``LEGACY`` Prefer to use the legacy libGL library, if available. - This is the default if no components were requested and - policy :policy:`CMP0072` is not set to ``NEW``. For EGL targets the client must rely on GLVND support on the user's system. Linking should use the ``OpenGL::OpenGL OpenGL::EGL`` targets. Using GLES* diff --git a/Modules/FindOpenMP.cmake b/Modules/FindOpenMP.cmake index bb38e28e1a..fc5bffa347 100644 --- a/Modules/FindOpenMP.cmake +++ b/Modules/FindOpenMP.cmake @@ -13,11 +13,15 @@ OpenMP support are returned in variables for the different languages. The variables may be empty if the compiler does not need a special flag to support OpenMP. +.. versionadded:: 3.5 + Clang support. + Variables ^^^^^^^^^ -The module exposes the components ``C``, ``CXX``, and ``Fortran``. -Each of these controls the various languages to search OpenMP support for. +.. versionadded:: 3.10 + The module exposes the components ``C``, ``CXX``, and ``Fortran``. + Each of these controls the various languages to search OpenMP support for. Depending on the enabled components the following variables will be set: @@ -65,6 +69,8 @@ Specifically for Fortran, the module sets the following variables: The module will also try to provide the OpenMP version variables: ``OpenMP_<lang>_SPEC_DATE`` + .. versionadded:: 3.7 + Date of the OpenMP specification implemented by the ``<lang>`` compiler. ``OpenMP_<lang>_VERSION_MAJOR`` Major version of OpenMP implemented by the ``<lang>`` compiler. diff --git a/Modules/FindOpenSSL.cmake b/Modules/FindOpenSSL.cmake index 91a65fddaa..03b699b2e0 100644 --- a/Modules/FindOpenSSL.cmake +++ b/Modules/FindOpenSSL.cmake @@ -7,15 +7,22 @@ FindOpenSSL Find the OpenSSL encryption library. +.. versionadded:: 3.18 + Support for OpenSSL 3.0. + Optional COMPONENTS ^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 3.12 + This module supports two optional COMPONENTS: ``Crypto`` and ``SSL``. Both components have associated imported targets, as described below. Imported Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.4 + This module defines the following :prop_tgt:`IMPORTED` targets: ``OpenSSL::SSL`` @@ -23,6 +30,8 @@ This module defines the following :prop_tgt:`IMPORTED` targets: ``OpenSSL::Crypto`` The OpenSSL ``crypto`` library, if found. ``OpenSSL::applink`` + .. versionadded:: 3.18 + The OpenSSL ``applink`` components that might be need to be compiled into projects under MSVC. This target is available only if found OpenSSL version is not less than 0.9.8. By linking this target the above OpenSSL targets can @@ -75,8 +84,12 @@ Hints ^^^^^ Set ``OPENSSL_ROOT_DIR`` to the root directory of an OpenSSL installation. -Set ``OPENSSL_USE_STATIC_LIBS`` to ``TRUE`` to look for static libraries. -Set ``OPENSSL_MSVC_STATIC_RT`` set ``TRUE`` to choose the MT version of the lib. + +.. versionadded:: 3.4 + Set ``OPENSSL_USE_STATIC_LIBS`` to ``TRUE`` to look for static libraries. + +.. versionadded:: 3.5 + Set ``OPENSSL_MSVC_STATIC_RT`` set ``TRUE`` to choose the MT version of the lib. #]=======================================================================] macro(_OpenSSL_test_and_find_dependencies ssl_library crypto_library) diff --git a/Modules/FindPNG.cmake b/Modules/FindPNG.cmake index fd0e4e93e9..51f2c7daf5 100644 --- a/Modules/FindPNG.cmake +++ b/Modules/FindPNG.cmake @@ -10,6 +10,8 @@ Find libpng, the official reference library for the PNG image format. Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.5 + This module defines the following :prop_tgt:`IMPORTED` target: ``PNG::PNG`` diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake index 7e172779e4..fbcf7cd88b 100644 --- a/Modules/FindPackageHandleStandardArgs.cmake +++ b/Modules/FindPackageHandleStandardArgs.cmake @@ -51,7 +51,9 @@ implementing :command:`find_package(<PackageName>)` calls. (recommended). Not valid in the full signature. ``FOUND_VAR <result-var>`` - Obsolete. Specifies either ``<PackageName>_FOUND`` or + .. deprecated:: 3.3 + + Specifies either ``<PackageName>_FOUND`` or ``<PACKAGENAME>_FOUND`` as the result variable. This exists only for compatibility with older versions of CMake and is now ignored. Result variables of both names are always set for compatibility. @@ -61,8 +63,10 @@ implementing :command:`find_package(<PackageName>)` calls. These may be named in the generated failure message asking the user to set the missing variable values. Therefore these should typically be cache entries such as ``FOO_LIBRARY`` and not output - variables like ``FOO_LIBRARIES``. This option is mandatory if - ``HANDLE_COMPONENTS`` is not specified. + variables like ``FOO_LIBRARIES``. + + .. versionchanged:: 3.18 + If ``HANDLE_COMPONENTS`` is specified, this option can be omitted. ``VERSION_VAR <version-var>`` Specify the name of a variable that holds the version of the package @@ -74,6 +78,8 @@ implementing :command:`find_package(<PackageName>)` calls. if the version is ok or not. ``HANDLE_VERSION_RANGE`` + .. versionadded:: 3.19 + Enable handling of a version range, if one is specified. Without this option, a developer warning will be displayed if a version range is specified. @@ -94,6 +100,8 @@ implementing :command:`find_package(<PackageName>)` calls. was found. ``REASON_FAILURE_MESSAGE <reason-failure-message>`` + .. versionadded:: 3.16 + Specify a custom message of the reason for the failure which will be appended to the default generated message. @@ -102,6 +110,8 @@ implementing :command:`find_package(<PackageName>)` calls. generated message. Not recommended. ``NAME_MISMATCHED`` + .. versionadded:: 3.17 + Indicate that the ``<PackageName>`` does not match ``${CMAKE_FIND_PACKAGE_NAME}``. This is usually a mistake and raises a warning, but it may be intentional for usage of the command for components @@ -163,6 +173,8 @@ message. .. command:: find_package_check_version + .. versionadded:: 3.19 + Helper function which can be used to check if a ``<version>`` is valid against version-related arguments of :command:`find_package`. diff --git a/Modules/FindPkgConfig.cmake b/Modules/FindPkgConfig.cmake index 2ad2c7e174..b41c2c3d2d 100644 --- a/Modules/FindPkgConfig.cmake +++ b/Modules/FindPkgConfig.cmake @@ -632,19 +632,38 @@ endmacro() When the ``QUIET`` argument is given, no status messages will be printed. - By default, if :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` is 3.1 or - later, or if :variable:`PKG_CONFIG_USE_CMAKE_PREFIX_PATH` is set to a - boolean ``True`` value, then the :variable:`CMAKE_PREFIX_PATH`, - :variable:`CMAKE_FRAMEWORK_PATH`, and :variable:`CMAKE_APPBUNDLE_PATH` cache - and environment variables will be added to the ``pkg-config`` search path. - The ``NO_CMAKE_PATH`` and ``NO_CMAKE_ENVIRONMENT_PATH`` arguments - disable this behavior for the cache variables and environment variables - respectively. - - The ``IMPORTED_TARGET`` argument will create an imported target named - ``PkgConfig::<prefix>`` that can be passed directly as an argument to - :command:`target_link_libraries`. The ``GLOBAL`` argument will make the - imported target available in global scope. + .. versionadded:: 3.1 + The :variable:`CMAKE_PREFIX_PATH`, + :variable:`CMAKE_FRAMEWORK_PATH`, and :variable:`CMAKE_APPBUNDLE_PATH` cache + and environment variables will be added to the ``pkg-config`` search path. + The ``NO_CMAKE_PATH`` and ``NO_CMAKE_ENVIRONMENT_PATH`` arguments + disable this behavior for the cache variables and environment variables + respectively. + The :variable:`PKG_CONFIG_USE_CMAKE_PREFIX_PATH` variable set to ``FALSE`` + disables this behavior globally. + + .. This didn't actually work until 3.3. + + .. versionadded:: 3.6 + The ``IMPORTED_TARGET`` argument will create an imported target named + ``PkgConfig::<prefix>`` that can be passed directly as an argument to + :command:`target_link_libraries`. + + .. This didn't actually work until 3.7. + + .. versionadded:: 3.13 + The ``GLOBAL`` argument will make the + imported target available in global scope. + + .. versionadded:: 3.15 + Non-library linker options reported by ``pkg-config`` are stored in the + :prop_tgt:`INTERFACE_LINK_OPTIONS` target property. + + .. versionchanged:: 3.18 + Include directories specified with ``-isystem`` are stored in the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. Previous + versions of CMake left them in the :prop_tgt:`INTERFACE_COMPILE_OPTIONS` + property. Each ``<moduleSpec>`` can be either a bare module name or it can be a module name with a version constraint (operators ``=``, ``<``, ``>``, @@ -683,6 +702,11 @@ endmacro() All but ``<XXX>_FOUND`` may be a :ref:`;-list <CMake Language Lists>` if the associated variable returned from ``pkg-config`` has multiple values. + .. versionchanged:: 3.18 + Include directories specified with ``-isystem`` are stored in the + ``<XXX>_INCLUDE_DIRS`` variable. Previous versions of CMake left them + in ``<XXX>_CFLAGS_OTHER``. + There are some special variables whose prefix depends on the number of ``<moduleSpec>`` given. When there is only one ``<moduleSpec>``, ``<YYY>`` will simply be ``<prefix>``, but if two or more ``<moduleSpec>`` @@ -697,6 +721,16 @@ endmacro() ``<YYY>_LIBDIR`` lib directory of the module + .. versionchanged:: 3.8 + For any given ``<prefix>``, ``pkg_check_modules()`` can be called multiple + times with different parameters. Previous versions of CMake cached and + returned the first successful result. + + .. versionchanged:: 3.16 + If a full path to the found library can't be determined, but it's still + visible to the linker, pass it through as ``-l<name>``. Previous versions + of CMake failed in this case. + Examples: .. code-block:: cmake @@ -768,9 +802,10 @@ endmacro() [IMPORTED_TARGET [GLOBAL]] <moduleSpec> [<moduleSpec>...]) - If a module is found, the ``<prefix>_MODULE_NAME`` variable will contain the - name of the matching module. This variable can be used if you need to run - :command:`pkg_get_variable`. + .. versionadded:: 3.16 + If a module is found, the ``<prefix>_MODULE_NAME`` variable will contain the + name of the matching module. This variable can be used if you need to run + :command:`pkg_get_variable`. Example: @@ -815,6 +850,8 @@ endmacro() #[========================================[.rst: .. command:: pkg_get_variable + .. versionadded:: 3.4 + Retrieves the value of a pkg-config variable ``varName`` and stores it in the result variable ``resultVar`` in the calling scope. @@ -849,10 +886,15 @@ Variables Affecting Behavior This can be set to the path of the pkg-config executable. If not provided, it will be set by the module as a result of calling :command:`find_program` - internally. The ``PKG_CONFIG`` environment variable can be used as a hint. + internally. + + .. versionadded:: 3.1 + The ``PKG_CONFIG`` environment variable can be used as a hint. .. variable:: PKG_CONFIG_USE_CMAKE_PREFIX_PATH + .. versionadded:: 3.1 + Specifies whether :command:`pkg_check_modules` and :command:`pkg_search_module` should add the paths in the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_FRAMEWORK_PATH` and diff --git a/Modules/FindPostgreSQL.cmake b/Modules/FindPostgreSQL.cmake index 1970b26a31..cd50d8c047 100644 --- a/Modules/FindPostgreSQL.cmake +++ b/Modules/FindPostgreSQL.cmake @@ -10,6 +10,8 @@ Find the PostgreSQL installation. IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.14 + This module defines :prop_tgt:`IMPORTED` target ``PostgreSQL::PostgreSQL`` if PostgreSQL has been found. diff --git a/Modules/FindProtobuf.cmake b/Modules/FindProtobuf.cmake index 0c9d695bd6..4b1e336893 100644 --- a/Modules/FindProtobuf.cmake +++ b/Modules/FindProtobuf.cmake @@ -7,6 +7,13 @@ FindProtobuf Locate and configure the Google Protocol Buffers library. +.. versionadded:: 3.6 + Support for :command:`find_package` version checks. + +.. versionchanged:: 3.6 + All input and output variables use the ``Protobuf_`` prefix. + Variables with ``PROTOBUF_`` prefix are still supported for compatibility. + The following variables can be set and are optional: ``Protobuf_SRC_ROOT_FOLDER`` @@ -19,8 +26,12 @@ The following variables can be set and are optional: List of additional directories to be searched for imported .proto files. ``Protobuf_DEBUG`` + .. versionadded:: 3.6 + Show debug messages. ``Protobuf_USE_STATIC_LIBS`` + .. versionadded:: 3.9 + Set to ON to force the use of the static libraries. Default is OFF. @@ -30,6 +41,8 @@ Defines the following variables: Found the Google Protocol Buffers library (libprotobuf & header files) ``Protobuf_VERSION`` + .. versionadded:: 3.6 + Version of package found. ``Protobuf_INCLUDE_DIRS`` Include directories for Google Protocol Buffers @@ -40,7 +53,8 @@ Defines the following variables: ``Protobuf_LITE_LIBRARIES`` The protobuf-lite libraries -The following :prop_tgt:`IMPORTED` targets are also defined: +.. versionadded:: 3.9 + The following :prop_tgt:`IMPORTED` targets are also defined: ``protobuf::libprotobuf`` The protobuf library. @@ -49,7 +63,8 @@ The following :prop_tgt:`IMPORTED` targets are also defined: ``protobuf::libprotoc`` The protoc library. ``protobuf::protoc`` - The protoc compiler. + .. versionadded:: 3.10 + The protoc compiler. The following cache variables are also available to set or use: @@ -101,7 +116,8 @@ Example: ``HDRS`` Variable to define with autogenerated header files ``DESCRIPTORS`` - Variable to define with autogenerated descriptor files, if requested. + .. versionadded:: 3.10 + Variable to define with autogenerated descriptor files, if requested. ``EXPORT_MACRO`` is a macro which should expand to ``__declspec(dllexport)`` or ``__declspec(dllimport)`` depending on what is being compiled. @@ -110,6 +126,8 @@ Example: .. command:: protobuf_generate_python + .. versionadded:: 3.4 + Add custom commands to process ``.proto`` files to Python:: protobuf_generate_python (<PY> [<ARGN>...]) diff --git a/Modules/FindPython.cmake b/Modules/FindPython.cmake index b8b32c061c..a4b7a0385c 100644 --- a/Modules/FindPython.cmake +++ b/Modules/FindPython.cmake @@ -34,7 +34,7 @@ The following components are supported: * ``NumPy``: search for NumPy include directories. .. versionadded:: 3.14 - Added ``NumPy`` component. + Added the ``NumPy`` component. If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed. diff --git a/Modules/FindPython2.cmake b/Modules/FindPython2.cmake index 6b722ff55c..bb965b9d3c 100644 --- a/Modules/FindPython2.cmake +++ b/Modules/FindPython2.cmake @@ -34,7 +34,7 @@ The following components are supported: * ``NumPy``: search for NumPy include directories. .. versionadded:: 3.14 - Added ``NumPy`` component. + Added the ``NumPy`` component. If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed. diff --git a/Modules/FindPython3.cmake b/Modules/FindPython3.cmake index 9e2133ddce..f826fcfe29 100644 --- a/Modules/FindPython3.cmake +++ b/Modules/FindPython3.cmake @@ -34,7 +34,7 @@ The following components are supported: * ``NumPy``: search for NumPy include directories. .. versionadded:: 3.14 - Added ``NumPy`` component. + Added the ``NumPy`` component. If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed. diff --git a/Modules/FindQt.cmake b/Modules/FindQt.cmake index d6a06628e6..44a1f414c5 100644 --- a/Modules/FindQt.cmake +++ b/Modules/FindQt.cmake @@ -5,14 +5,14 @@ FindQt ------ +.. deprecated:: 3.14 + This module is available only if policy :policy:`CMP0084` is not set to ``NEW``. + Searches for all installed versions of Qt3 or Qt4. This module cannot handle Qt5 or any later versions. For those, see :manual:`cmake-qt(7)`. -This module exists for the :command:`find_package` command only if -policy :policy:`CMP0084` is not set to ``NEW``. - This module should only be used if your project can work with multiple versions of Qt. If not, you should just directly use FindQt4 or FindQt3. If multiple versions of Qt are found on the machine, then diff --git a/Modules/FindRuby.cmake b/Modules/FindRuby.cmake index d12f8255d5..ee07f83451 100644 --- a/Modules/FindRuby.cmake +++ b/Modules/FindRuby.cmake @@ -37,7 +37,8 @@ This module will set the following variables in your project: ``Ruby_INCLUDE_DIRS`` include dirs to be used when using the ruby library ``Ruby_LIBRARIES`` - libraries needed to use ruby from C. + .. versionadded:: 3.18 + libraries needed to use ruby from C. ``Ruby_VERSION`` the version of ruby which was found, e.g. "1.8.7" ``Ruby_VERSION_MAJOR`` @@ -47,9 +48,10 @@ This module will set the following variables in your project: ``Ruby_VERSION_PATCH`` Ruby patch version. - -The following variables are also provided for compatibility reasons, -don't use them in new code: +.. versionchanged:: 3.18 + Previous versions of CMake used the ``RUBY_`` prefix for all variables. + The following variables are provided for compatibility reasons, + don't use them in new code: ``RUBY_EXECUTABLE`` same as Ruby_EXECUTABLE. @@ -67,6 +69,8 @@ don't use them in new code: Hints ^^^^^ +.. versionadded:: 3.18 + ``Ruby_ROOT_DIR`` Define the root directory of a Ruby installation. diff --git a/Modules/FindSDL.cmake b/Modules/FindSDL.cmake index 59eddbbc99..c68e18d96a 100644 --- a/Modules/FindSDL.cmake +++ b/Modules/FindSDL.cmake @@ -11,6 +11,8 @@ Locate the SDL library Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.19 + This module defines the following :prop_tgt:`IMPORTED` target: ``SDL::SDL`` @@ -36,6 +38,10 @@ This module will set the following variables in your project: ``SDL_VERSION_PATCH`` SDL patch version +.. versionadded:: 3.19 + Added the ``SDL_INCLUDE_DIRS``, ``SDL_LIBRARIES`` and ``SDL_VERSION[_<PART>]`` + variables. + Cache variables ^^^^^^^^^^^^^^^ @@ -63,6 +69,8 @@ This module responds to the flag: Obsolete variables ^^^^^^^^^^^^^^^^^^ +.. deprecated:: 3.19 + These variables are obsolete and provided for backwards compatibility: ``SDL_VERSION_STRING`` diff --git a/Modules/FindSWIG.cmake b/Modules/FindSWIG.cmake index 87a3894634..4c7ad89dca 100644 --- a/Modules/FindSWIG.cmake +++ b/Modules/FindSWIG.cmake @@ -7,14 +7,17 @@ FindSWIG Find the Simplified Wrapper and Interface Generator (SWIG_) executable. -This module finds an installed SWIG and determines its version. If a -``COMPONENTS`` or ``OPTIONAL_COMPONENTS`` argument is given to the -:command:`find_package` command, it will also determine supported target -languages. - -When a version is requested, it can be specified as a simple value or as a -range. For a detailed description of version range usage and capabilities, -refer to the :command:`find_package` command. +This module finds an installed SWIG and determines its version. + +.. versionadded:: 3.18 + If a ``COMPONENTS`` or ``OPTIONAL_COMPONENTS`` argument is given to the + :command:`find_package` command, it will also determine supported target + languages. + +.. versionadded:: 3.19 + When a version is requested, it can be specified as a simple value or as a + range. For a detailed description of version range usage and capabilities, + refer to the :command:`find_package` command. The module defines the following variables: diff --git a/Modules/FindSquish.cmake b/Modules/FindSquish.cmake index 91d1410086..9a17fdbafa 100644 --- a/Modules/FindSquish.cmake +++ b/Modules/FindSquish.cmake @@ -47,7 +47,8 @@ to cmake using Squish >= 4.x: AUT targetName SUITE suiteName TEST squishTestName [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] ) - +.. versionchanged:: 3.18 + In previous CMake versions, this function was named ``squish_v4_add_test``. The arguments have the following meaning: diff --git a/Modules/FindSubversion.cmake b/Modules/FindSubversion.cmake index 07cb770cf3..7a9c440f67 100644 --- a/Modules/FindSubversion.cmake +++ b/Modules/FindSubversion.cmake @@ -31,9 +31,12 @@ If the command line client executable is found two macros are defined: ``Subversion_WC_INFO`` extracts information of a subversion working copy at a given location. This macro defines the following variables if running Subversion's ``info`` command on ``<dir>`` succeeds; otherwise a -``SEND_ERROR`` message is generated. The error can be ignored by providing the -``IGNORE_SVN_FAILURE`` option, which causes these variables to remain -undefined. +``SEND_ERROR`` message is generated. + +.. versionadded:: 3.13 + The error can be ignored by providing the + ``IGNORE_SVN_FAILURE`` option, which causes these variables to remain + undefined. :: diff --git a/Modules/FindTIFF.cmake b/Modules/FindTIFF.cmake index 3b74c94f0c..ed2657c4ab 100644 --- a/Modules/FindTIFF.cmake +++ b/Modules/FindTIFF.cmake @@ -17,12 +17,16 @@ imported target, as described below. Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.5 + This module defines the following :prop_tgt:`IMPORTED` targets: ``TIFF::TIFF`` The TIFF library, if found. ``TIFF::CXX`` + .. versionadded:: 3.19 + The C++ wrapper libtiffxx, if requested by the `COMPONENTS CXX` option, if the compiler is not MSVC (which includes the C++ wrapper in libtiff), and if found. @@ -56,6 +60,9 @@ The following cache variables may also be set: the path to the TIFFXX library for release configurations ``TIFFXX_LIBRARY_DEBUG`` the path to the TIFFXX library for debug configurations + +.. versionadded:: 3.4 + Debug and Release variants are found separately. #]=======================================================================] cmake_policy(PUSH) diff --git a/Modules/FindThreads.cmake b/Modules/FindThreads.cmake index e3e6591a36..87e88bc318 100644 --- a/Modules/FindThreads.cmake +++ b/Modules/FindThreads.cmake @@ -10,6 +10,8 @@ This module determines the thread library of the system. Imported Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.1 + This module defines the following :prop_tgt:`IMPORTED` target: ``Threads::Threads`` @@ -38,6 +40,8 @@ Variables Affecting Behavior .. variable:: THREADS_PREFER_PTHREAD_FLAG + .. versionadded:: 3.1 + If the use of the -pthread compiler and linker flag is preferred then the caller can set this variable to TRUE. The compiler flag can only be used with the imported target. Use of both the imported target as well diff --git a/Modules/FindVulkan.cmake b/Modules/FindVulkan.cmake index 0ec60133ce..ceb1921e9e 100644 --- a/Modules/FindVulkan.cmake +++ b/Modules/FindVulkan.cmake @@ -16,8 +16,9 @@ IMPORTED Targets This module defines :prop_tgt:`IMPORTED` target ``Vulkan::Vulkan``, if Vulkan has been found. -This module defines :prop_tgt:`IMPORTED` target ``Vulkan::glslc``, if -Vulkan and the GLSLC SPIR-V compiler has been found. +.. versionadded:: 3.19 + This module defines :prop_tgt:`IMPORTED` target ``Vulkan::glslc``, if + Vulkan and the GLSLC SPIR-V compiler has been found. Result Variables ^^^^^^^^^^^^^^^^ @@ -37,6 +38,8 @@ The module will also define three cache variables:: Hints ^^^^^ +.. versionadded:: 3.18 + The ``VULKAN_SDK`` environment variable optionally specifies the location of the Vulkan SDK root directory for the given architecture. It is typically set by sourcing the toplevel diff --git a/Modules/FindX11.cmake b/Modules/FindX11.cmake index a865597afa..d480fc4803 100644 --- a/Modules/FindX11.cmake +++ b/Modules/FindX11.cmake @@ -17,6 +17,9 @@ Try to find X11 on UNIX systems. The following values are defined and also the following more fine grained variables and targets: +.. versionadded:: 3.14 + Imported targets. + :: X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE @@ -62,6 +65,23 @@ and also the following more fine grained variables and targets: X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw + +.. versionadded:: 3.14 + Renamed ``Xxf86misc``, ``X11_Xxf86misc``, ``X11_Xxf86vm``, ``X11_xkbfile``, + ``X11_Xtst``, and ``X11_Xss`` libraries to match their file names. + Deprecated the ``X11_Xinput`` library. Old names are still available + for compatibility. + +.. versionadded:: 3.14 + Added the ``X11_Xext_INCLUDE_PATH`` variable. + +.. versionadded:: 3.18 + Added the ``xcb``, ``X11-xcb``, ``xcb-icccm``, ``xcb-xkb``, ``xkbcommon``, + and ``xkbcommon-X11`` libraries. + +.. versionadded:: 3.19 + Added the ``Xaw``, ``xcb_util``, and ``xcb_xfixes`` libraries. + #]=======================================================================] if (UNIX) diff --git a/Modules/FindXercesC.cmake b/Modules/FindXercesC.cmake index abe18c0570..af1b0b438f 100644 --- a/Modules/FindXercesC.cmake +++ b/Modules/FindXercesC.cmake @@ -12,6 +12,8 @@ Find the Apache Xerces-C++ validating XML parser headers and libraries. Imported targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.5 + This module defines the following :prop_tgt:`IMPORTED` targets: ``XercesC::XercesC`` @@ -40,6 +42,9 @@ The following cache variables may also be set: the directory containing the Xerces headers ``XercesC_LIBRARY`` the Xerces library + +.. versionadded:: 3.4 + Debug and Release variants are found separately. #]=======================================================================] # Written by Roger Leigh <rleigh@codelibre.net> diff --git a/Modules/FindZLIB.cmake b/Modules/FindZLIB.cmake index 79e2313d5a..5778b031b3 100644 --- a/Modules/FindZLIB.cmake +++ b/Modules/FindZLIB.cmake @@ -10,6 +10,8 @@ Find the native ZLIB includes and library. IMPORTED Targets ^^^^^^^^^^^^^^^^ +.. versionadded:: 3.1 + This module defines :prop_tgt:`IMPORTED` target ``ZLIB::ZLIB``, if ZLIB has been found. @@ -32,6 +34,9 @@ This module defines the following variables: ZLIB_VERSION_PATCH - The patch version of zlib ZLIB_VERSION_TWEAK - The tweak version of zlib +.. versionadded:: 3.4 + Debug and Release variants are found separately. + Backward Compatibility ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Modules/FindwxWidgets.cmake b/Modules/FindwxWidgets.cmake index eab09f157a..63af9b68de 100644 --- a/Modules/FindwxWidgets.cmake +++ b/Modules/FindwxWidgets.cmake @@ -14,6 +14,12 @@ package: find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net ...) +.. versionadded:: 3.4 + Support for :command:`find_package` version argument; ``webview`` component. + +.. versionadded:: 3.14 + ``OPTIONAL_COMPONENTS`` support. + There are two search branches: a windows style and a unix style. For windows, the following variables are searched for and set to defaults in case of multiple choices. Change them if the defaults are not @@ -82,6 +88,9 @@ and unix style: "`wx-config --cxxflags`". wxWidgets_USE_FILE - Convenience include file. +.. versionadded:: 3.11 + The following environment variables can be used as hints: ``WX_CONFIG``, + ``WXRC_CMD``. Sample usage: diff --git a/Modules/GNUInstallDirs.cmake b/Modules/GNUInstallDirs.cmake index 888f7b1650..37869fbabd 100644 --- a/Modules/GNUInstallDirs.cmake +++ b/Modules/GNUInstallDirs.cmake @@ -46,7 +46,8 @@ where ``<dir>`` is one of: ``LOCALSTATEDIR`` modifiable single-machine data (``var``) ``RUNSTATEDIR`` - run-time variable data (``LOCALSTATEDIR/run``) + .. versionadded:: 3.9 + run-time variable data (``LOCALSTATEDIR/run``) ``LIBDIR`` object code libraries (``lib`` or ``lib64`` or ``lib/<multiarch-tuple>`` on Debian) @@ -73,6 +74,8 @@ used and the value will appear in the cache for editing by the user. Special Cases ^^^^^^^^^^^^^ +.. versionadded:: 3.4 + The following values of :variable:`CMAKE_INSTALL_PREFIX` are special: ``/`` @@ -115,6 +118,8 @@ Macros GNUInstallDirs_get_absolute_install_dir(absvar var dirname) + .. versionadded:: 3.7 + Set the given variable ``absvar`` to the absolute path contained within the variable ``var``. This is to allow the computation of an absolute path, accounting for all the special cases documented @@ -123,6 +128,10 @@ Macros allow users who create additional path variables to also compute absolute paths where necessary, using the same logic. ``dirname`` is the directory name to get, e.g. ``BINDIR``. + + .. versionchanged:: 3.20 + Added the ``<dirname>`` parameter. Previous versions of CMake passed + this value through the variable ``${dir}``. #]=======================================================================] cmake_policy(PUSH) diff --git a/Modules/GenerateExportHeader.cmake b/Modules/GenerateExportHeader.cmake index e4481f66d1..bc1eb1799f 100644 --- a/Modules/GenerateExportHeader.cmake +++ b/Modules/GenerateExportHeader.cmake @@ -9,6 +9,9 @@ Function for generation of export macros for libraries This module provides the function ``GENERATE_EXPORT_HEADER()``. +.. versionadded:: 3.12 + Added support for C projects. Previous versions supported C++ project only. + The ``GENERATE_EXPORT_HEADER`` function can be used to generate a file suitable for preprocessor inclusion which contains EXPORT macros to be used in library classes:: @@ -27,7 +30,6 @@ used in library classes:: [CUSTOM_CONTENT_FROM_VARIABLE <variable>] ) - The target properties :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` can be used to add the appropriate compile flags for targets. See the documentation of those target properties, @@ -170,20 +172,30 @@ For example: Generates the macros ``VTK_SOMELIB_EXPORT`` etc. +.. versionadded:: 3.1 + Library target can be an ``OBJECT`` library. + +.. versionadded:: 3.7 + Added the ``CUSTOM_CONTENT_FROM_VARIABLE`` option. + +.. versionadded:: 3.11 + Added the ``INCLUDE_GUARD_NAME`` option. + :: ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] ) +.. deprecated:: 3.0 + Set the target properties + :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and + :prop_tgt:`VISIBILITY_INLINES_HIDDEN` instead. + The ``ADD_COMPILER_EXPORT_FLAGS`` function adds ``-fvisibility=hidden`` to :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` if supported, and is a no-op on Windows which does not need extra compiler flags for exporting support. You may optionally pass a single argument to ``ADD_COMPILER_EXPORT_FLAGS`` that will be populated with the ``CXX_FLAGS`` required to enable visibility support for the compiler/architecture in use. - -This function is deprecated. Set the target properties -:prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and -:prop_tgt:`VISIBILITY_INLINES_HIDDEN` instead. #]=======================================================================] include(CheckCCompilerFlag) diff --git a/Modules/GetPrerequisites.cmake b/Modules/GetPrerequisites.cmake index c99c7725a9..f325cfb867 100644 --- a/Modules/GetPrerequisites.cmake +++ b/Modules/GetPrerequisites.cmake @@ -25,6 +25,9 @@ files: ldd (Linux/Unix) otool (Mac OSX) +.. versionchanged:: 3.16 + The tool specified by ``CMAKE_OBJDUMP`` will be used, if set. + The following functions are provided by this module: :: @@ -42,9 +45,6 @@ The following functions are provided by this module: (projects can override with gp_resolved_file_type_override) gp_file_type -Requires CMake 2.6 or greater because it uses function, break, return -and PARENT_SCOPE. - :: GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse> @@ -67,8 +67,9 @@ searched first when a target without any path info is given. Then standard system locations are also searched: PATH, Framework locations, /usr/lib... -The variable GET_PREREQUISITES_VERBOSE can be set to true to enable verbose -output. +.. versionadded:: 3.14 + The variable GET_PREREQUISITES_VERBOSE can be set to true to enable verbose + output. :: diff --git a/Modules/GoogleTest.cmake b/Modules/GoogleTest.cmake index 057b29d6da..2ea9e74250 100644 --- a/Modules/GoogleTest.cmake +++ b/Modules/GoogleTest.cmake @@ -101,6 +101,8 @@ same as the Google Test name (i.e. ``suite.testcase``); see also with the list of discovered test cases. This allows the caller to do things like manipulate test properties of the discovered tests. + Usage example: + .. code-block:: cmake include(GoogleTest) @@ -157,6 +159,8 @@ same as the Google Test name (i.e. ``suite.testcase``); see also [DISCOVERY_MODE <POST_BUILD|PRE_TEST>] ) + .. versionadded:: 3.10 + ``gtest_discover_tests()`` sets up a post-build command on the test executable that generates the list of tests by parsing the output from running the test with the ``--gtest_list_tests`` argument. Compared to the source parsing @@ -223,6 +227,8 @@ same as the Google Test name (i.e. ``suite.testcase``); see also Note that this variable is only available in CTest. ``DISCOVERY_TIMEOUT num`` + .. versionadded:: 3.10.3 + Specifies how long (in seconds) CMake will wait for the test to enumerate available tests. If the test takes longer than this, discovery (and your build) will fail. Most test executables will enumerate their tests very @@ -241,6 +247,8 @@ same as the Google Test name (i.e. ``suite.testcase``); see also and 3.10.2 has not been preserved. ``XML_OUTPUT_DIR dir`` + .. versionadded:: 3.18 + If specified, the parameter is passed along with ``--gtest_output=xml:`` to test executable. The actual file name is the same as the test target, including prefix and suffix. This should be used instead of @@ -248,6 +256,8 @@ same as the Google Test name (i.e. ``suite.testcase``); see also XML result output when using parallel test execution. ``DISCOVERY_MODE`` + .. versionadded:: 3.18 + Provides greater control over when ``gtest_discover_tests()`` performs test discovery. By default, ``POST_BUILD`` sets up a post-build command to perform test discovery at build time. In certain scenarios, like diff --git a/Modules/InstallRequiredSystemLibraries.cmake b/Modules/InstallRequiredSystemLibraries.cmake index caca6977ba..c34b8198aa 100644 --- a/Modules/InstallRequiredSystemLibraries.cmake +++ b/Modules/InstallRequiredSystemLibraries.cmake @@ -27,14 +27,17 @@ may be set prior to including the module to adjust behavior: tools even if the release runtime libraries are also available. ``CMAKE_INSTALL_UCRT_LIBRARIES`` + .. versionadded:: 3.6 + Set to TRUE to install the Windows Universal CRT libraries for app-local deployment (e.g. to Windows XP). This is meaningful only with MSVC from Visual Studio 2015 or higher. - One may set a ``CMAKE_WINDOWS_KITS_10_DIR`` *environment variable* - to an absolute path to tell CMake to look for Windows 10 SDKs in - a custom location. The specified directory is expected to contain - ``Redist/ucrt/DLLs/*`` directories. + .. versionadded:: 3.9 + One may set a ``CMAKE_WINDOWS_KITS_10_DIR`` *environment variable* + to an absolute path to tell CMake to look for Windows 10 SDKs in + a custom location. The specified directory is expected to contain + ``Redist/ucrt/DLLs/*`` directories. ``CMAKE_INSTALL_MFC_LIBRARIES`` Set to TRUE to install the MSVC MFC runtime libraries. @@ -53,8 +56,13 @@ may be set prior to including the module to adjust behavior: not provide the redistributable files.) ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` + .. versionadded:: 3.3 + Specify the :command:`install(PROGRAMS)` command ``COMPONENT`` option. If not specified, no such option will be used. + +.. versionadded:: 3.10 + Support for installing Intel compiler runtimes. #]=======================================================================] cmake_policy(PUSH) diff --git a/Modules/ProcessorCount.cmake b/Modules/ProcessorCount.cmake index 43ec889b66..bda23ab682 100644 --- a/Modules/ProcessorCount.cmake +++ b/Modules/ProcessorCount.cmake @@ -15,6 +15,9 @@ Otherwise it is set to 0. Currently this functionality is implemented for AIX, cygwin, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows. +.. versionchanged:: 3.15 + On Linux, returns the container CPU count instead of the host CPU count. + This function is guaranteed to return a positive integer (>=1) if it succeeds. It returns 0 if there's a problem determining the processor count. diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake index bbd469eb80..a5f8a08e42 100644 --- a/Modules/UseJava.cmake +++ b/Modules/UseJava.cmake @@ -36,17 +36,21 @@ compiling the java sources and also to the dependencies of the target. For backwards compatibility, jar files listed as sources are ignored (as they have been since the first version of this module). +.. versionadded:: 3.4 + Support fot response files (prefixed by ``@``) in the ``SOURCES`` list. + The default ``OUTPUT_DIR`` can also be changed by setting the variable ``CMAKE_JAVA_TARGET_OUTPUT_DIR``. -Optionally, using option ``GENERATE_NATIVE_HEADERS``, native header files can -be generated for methods declared as native. These files provide the -connective glue that allow your Java and C code to interact. An INTERFACE -target will be created for an easy usage of generated files. Sub-option -``DESTINATION`` can be used to specify the output directory for generated -header files. +.. versionadded:: 3.11 + Optionally, using option ``GENERATE_NATIVE_HEADERS``, native header files can + be generated for methods declared as native. These files provide the + connective glue that allow your Java and C code to interact. An INTERFACE + target will be created for an easy usage of generated files. Sub-option + ``DESTINATION`` can be used to specify the output directory for generated + header files. -``GENERATE_NATIVE_HEADERS`` option requires, at least, version 1.8 of the JDK. + ``GENERATE_NATIVE_HEADERS`` option requires, at least, version 1.8 of the JDK. The ``add_jar()`` function sets the following target properties on ``<target_name>``: @@ -77,6 +81,9 @@ described above, and is used by ``install_jar_exports()``. You can get this information with :command:`get_property` and the ``INSTALL_DESTINATION`` property key. +.. versionadded:: 3.4 + The second signature with ``DESTINATION`` and ``COMPONENT`` options. + .. code-block:: cmake install_jni_symlink(<target_name> <destination>) @@ -86,6 +93,14 @@ This command installs the ``<target_name>`` JNI symlinks to the given ``<destination>``. It should be called in the same scope as ``add_jar()`` or it will fail. +.. versionadded:: 3.4 + The second signature with ``DESTINATION`` and ``COMPONENT`` options. + +Exporting JAR Targets +^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.7 + .. code-block:: cmake install_jar_exports(TARGETS <jars>... @@ -97,6 +112,9 @@ This command installs a target export file ``<filename>`` for the named jar targets to the given ``<destination>`` directory. Its function is similar to that of :command:`install(EXPORTS)`. +.. versionadded:: 3.9 + The ``NAMESPACE`` option. + .. code-block:: cmake export_jars(TARGETS <jars>... @@ -106,6 +124,9 @@ that of :command:`install(EXPORTS)`. This command writes a target export file ``<filename>`` for the named ``<jars>`` targets. Its function is similar to that of :command:`export`. +.. versionadded:: 3.9 + The ``NAMESPACE`` option. + Examples """""""" @@ -316,17 +337,16 @@ Header Generation [OUTPUT_NAME <path>|OUTPUT_DIR <path>] ) -Create C header files from java classes. These files provide the connective glue -that allow your Java and C code to interact. +.. versionadded:: 3.4 .. deprecated:: 3.11 - -.. note:: - This command will no longer be supported starting with version 10 of the JDK due to the `suppression of javah tool <http://openjdk.java.net/jeps/313>`_. The ``add_jar(GENERATE_NATIVE_HEADERS)`` command should be used instead. +Create C header files from java classes. These files provide the connective glue +that allow your Java and C code to interact. + There are two main signatures for ``create_javah()``. The first signature returns generated files through variable specified by the ``GENERATED_FILES`` option. For example: diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake index 757e5392b1..9b0025a8fc 100644 --- a/Modules/UseSWIG.cmake +++ b/Modules/UseSWIG.cmake @@ -12,6 +12,8 @@ Defines the following command for use with ``SWIG``: .. command:: swig_add_library + .. versionadded:: 3.8 + Define swig module with given name and specified language:: swig_add_library(<name> @@ -28,13 +30,16 @@ Defines the following command for use with ``SWIG``: those targets can be used with any command expecting a target (e.g. :command:`target_link_libraries`). - .. note:: - + .. versionchanged:: 3.13 This command creates a target with the specified ``<name>`` when policy :policy:`CMP0078` is set to ``NEW``. Otherwise, the legacy behavior will choose a different target name and store it in the ``SWIG_MODULE_<name>_REAL_NAME`` variable. + .. versionchanged:: 3.15 + Alternate library name (set with the :prop_tgt:`OUTPUT_NAME` property, + for example) will be passed on to Python and CSharp wrapper libraries. + .. note:: For multi-config generators, this module does not support @@ -59,10 +64,23 @@ Defines the following command for use with ``SWIG``: ``LANGUAGE`` Specify the target language. + .. versionadded:: 3.1 + Go and Lua language support. + + .. versionadded:: 3.2 + R language support. + + .. versionadded:: 3.18 + Fortran language support. + ``NO_PROXY`` + .. versionadded:: 3.12 + Prevent the generation of the wrapper layer (swig ``-noproxy`` option). ``OUTPUT_DIR`` + .. versionadded:: 3.12 + Specify where to write the language specific files (swig ``-outdir`` option). If not given, the ``CMAKE_SWIG_OUTDIR`` variable will be used. If neither is specified, the default depends on the value of the @@ -75,6 +93,8 @@ Defines the following command for use with ``SWIG``: ``SWIG_SUPPORT_FILES_DIRECTORY`` target property. ``OUTFILE_DIR`` + .. versionadded:: 3.12 + Specify an output directory name where the generated source file will be placed (swig ``-o`` option). If not specified, the ``SWIG_OUTFILE_DIR`` variable will be used. If neither is specified, ``OUTPUT_DIR`` or @@ -83,8 +103,11 @@ Defines the following command for use with ``SWIG``: ``SOURCES`` List of sources for the library. Files with extension ``.i`` will be identified as sources for the ``SWIG`` tool. Other files will be handled in - the standard way. This behavior can be overridden by specifying the variable - ``SWIG_SOURCE_FILE_EXTENSIONS``. + the standard way. + + .. versionadded:: 3.14 + This behavior can be overridden by specifying the variable + ``SWIG_SOURCE_FILE_EXTENSIONS``. .. note:: @@ -122,12 +145,22 @@ ensure generated files will receive the required settings. set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) swig_add_library(mymod LANGUAGE python SOURCES mymod.i) +``SWIG_FLAGS`` + .. deprecated:: 3.12 + Replaced with the fine-grained properties that follow. + + Pass custom flags to the SWIG executable. + ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS`` and ``COMPILE_OPTIONS`` + .. versionadded:: 3.12 + Add custom flags to SWIG compiler and have same semantic as properties :prop_sf:`INCLUDE_DIRECTORIES`, :prop_sf:`COMPILE_DEFINITIONS` and :prop_sf:`COMPILE_OPTIONS`. ``USE_TARGET_INCLUDE_DIRECTORIES`` + .. versionadded:: 3.13 + If set to ``TRUE``, contents of target property :prop_tgt:`INCLUDE_DIRECTORIES` will be forwarded to ``SWIG`` compiler. If set to ``FALSE`` target property :prop_tgt:`INCLUDE_DIRECTORIES` will be @@ -135,11 +168,15 @@ ensure generated files will receive the required settings. will be considered. ``GENERATED_INCLUDE_DIRECTORIES``, ``GENERATED_COMPILE_DEFINITIONS`` and ``GENERATED_COMPILE_OPTIONS`` + .. versionadded:: 3.12 + Add custom flags to the C/C++ generated source. They will fill, respectively, properties :prop_sf:`INCLUDE_DIRECTORIES`, :prop_sf:`COMPILE_DEFINITIONS` and :prop_sf:`COMPILE_OPTIONS` of generated C/C++ file. ``DEPENDS`` + .. versionadded:: 3.12 + Specify additional dependencies to the source file. ``SWIG_MODULE_NAME`` @@ -151,18 +188,21 @@ ensure generated files will receive the required settings. set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname) - .. note:: - + .. versionchanged:: 3.14 If policy :policy:`CMP0086` is set to ``NEW``, ``-module <module_name>`` is passed to ``SWIG`` compiler. ``OUTPUT_DIR`` + .. versionadded:: 3.19 + Specify where to write the language specific files (swig ``-outdir`` option) for the considered source file. If not specified, the other ways to define the output directory applies (see ``OUTPUT_DIR`` option of ``swig_add_library()`` command). ``OUTFILE_DIR`` + .. versionadded:: 3.19 + Specify an output directory where the generated source file will be placed (swig ``-o`` option) for the considered source file. If not specified, ``OUTPUT_DIR`` source property will be used. If neither are specified, the @@ -173,6 +213,8 @@ Target library properties can be set to apply same configuration to all SWIG input files. ``SWIG_INCLUDE_DIRECTORIES``, ``SWIG_COMPILE_DEFINITIONS`` and ``SWIG_COMPILE_OPTIONS`` + .. versionadded:: 3.12 + These properties will be applied to all SWIG input files and have same semantic as target properties :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS`. @@ -185,6 +227,8 @@ input files. set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb) ``SWIG_USE_TARGET_INCLUDE_DIRECTORIES`` + .. versionadded:: 3.13 + If set to ``TRUE``, contents of target property :prop_tgt:`INCLUDE_DIRECTORIES` will be forwarded to ``SWIG`` compiler. If set to ``FALSE`` or not defined, target property @@ -192,17 +236,23 @@ input files. overridden by specifying source property ``USE_TARGET_INCLUDE_DIRECTORIES``. ``SWIG_GENERATED_INCLUDE_DIRECTORIES``, ``SWIG_GENERATED_COMPILE_DEFINITIONS`` and ``SWIG_GENERATED_COMPILE_OPTIONS`` + .. versionadded:: 3.12 + These properties will populate, respectively, properties :prop_sf:`INCLUDE_DIRECTORIES`, :prop_sf:`COMPILE_DEFINITIONS` and :prop_sf:`COMPILE_FLAGS` of all generated C/C++ files. ``SWIG_DEPENDS`` + .. versionadded:: 3.12 + Add dependencies to all SWIG input files. The following target properties are output properties and can be used to get information about support files generated by ``SWIG`` interface compilation. ``SWIG_SUPPORT_FILES`` + .. versionadded:: 3.12 + This output property list of wrapper files generated during SWIG compilation. .. code-block:: cmake @@ -219,6 +269,8 @@ information about support files generated by ``SWIG`` interface compilation. ``SWIG_SUPPORT_FILES_DIRECTORY`` property to handle support files. ``SWIG_SUPPORT_FILES_DIRECTORY`` + .. versionadded:: 3.12 + This output property specifies the directory where support files will be generated. @@ -231,6 +283,8 @@ Some variables can be set to customize the behavior of ``swig_add_library`` as well as ``SWIG``: ``UseSWIG_MODULE_VERSION`` + .. versionadded:: 3.12 + Specify different behaviors for ``UseSWIG`` module. * Set to 1 or undefined: Legacy behavior is applied. @@ -244,6 +298,8 @@ as well as ``SWIG``: Specify where to write the language specific files (swig ``-outdir`` option). ``SWIG_OUTFILE_DIR`` + .. versionadded:: 3.8 + Specify an output directory name where the generated source file will be placed. If not specified, ``CMAKE_SWIG_OUTDIR`` is used. @@ -251,6 +307,8 @@ as well as ``SWIG``: Specify extra dependencies for the generated module for ``<name>``. ``SWIG_SOURCE_FILE_EXTENSIONS`` + .. versionadded:: 3.14 + Specify a list of source file extensions to override the default behavior of considering only ``.i`` files as sources for the ``SWIG`` tool. For example: diff --git a/Modules/WriteCompilerDetectionHeader.cmake b/Modules/WriteCompilerDetectionHeader.cmake index 5100035b39..650c02e595 100644 --- a/Modules/WriteCompilerDetectionHeader.cmake +++ b/Modules/WriteCompilerDetectionHeader.cmake @@ -80,19 +80,28 @@ Possible compiler identifiers are documented with the Available features in this version of CMake are listed in the :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties. -The ``{c,cxx}_std_*`` meta-features are ignored if requested. - See the :manual:`cmake-compile-features(7)` manual for information on compile features. -``BARE_FEATURES`` will define the compatibility macros with the name used in -newer versions of the language standard, so the code can use the new feature -name unconditionally. +.. versionadded:: 3.2 + Added ``MSVC`` and ``AppleClang`` compiler support. + +.. versionadded:: 3.6 + Added ``Intel`` compiler support. + +.. versionchanged:: 3.8 + The ``{c,cxx}_std_*`` meta-features are ignored if requested. + +.. versionadded:: 3.8 + ``ALLOW_UNKNOWN_COMPILERS`` and ``ALLOW_UNKNOWN_COMPILER_VERSIONS`` cause + the module to generate conditions that treat unknown compilers as simply + lacking all features. Without these options the default behavior is to + generate a ``#error`` for unknown compilers and versions. -``ALLOW_UNKNOWN_COMPILERS`` and ``ALLOW_UNKNOWN_COMPILER_VERSIONS`` cause -the module to generate conditions that treat unknown compilers as simply -lacking all features. Without these options the default behavior is to -generate a ``#error`` for unknown compilers and versions. +.. versionadded:: 3.12 + ``BARE_FEATURES`` will define the compatibility macros with the name used in + newer versions of the language standard, so the code can use the new feature + name unconditionally. Feature Test Macros =================== |