From 8fea95319bcaac741faf93bd66b3a1838b56a418 Mon Sep 17 00:00:00 2001 From: Nikita Nemkin Date: Thu, 12 Nov 2020 13:40:33 +0500 Subject: Help: Add `.. versionadded` directives to module docs Issue: #19715 --- Help/cpack_gen/ifw.rst | 4 + Help/envvar/CUDAHOSTCXX.rst | 7 +- Modules/BundleUtilities.cmake | 28 +++--- Modules/CMakeGraphVizOptions.cmake | 5 +- Modules/CMakePackageConfigHelpers.cmake | 46 +++++----- Modules/CPack.cmake | 12 +++ Modules/CPackIFW.cmake | 84 ++++++++++++++++-- Modules/CTestCoverageCollectGCOV.cmake | 13 ++- Modules/CTestUseLaunchers.cmake | 9 +- Modules/CheckCSourceCompiles.cmake | 4 + Modules/CheckCSourceRuns.cmake | 4 + Modules/CheckCXXSourceCompiles.cmake | 4 + Modules/CheckCXXSourceRuns.cmake | 4 + Modules/CheckCXXSymbolExists.cmake | 6 +- Modules/CheckFortranFunctionExists.cmake | 5 +- Modules/CheckFortranSourceCompiles.cmake | 2 + Modules/CheckFunctionExists.cmake | 6 +- Modules/CheckIPOSupported.cmake | 3 + Modules/CheckIncludeFile.cmake | 6 +- Modules/CheckIncludeFileCXX.cmake | 6 +- Modules/CheckIncludeFiles.cmake | 6 +- Modules/CheckLibraryExists.cmake | 19 ++-- Modules/CheckPrototypeDefinition.cmake | 22 +++-- Modules/CheckStructHasMember.cmake | 23 +++-- Modules/CheckSymbolExists.cmake | 6 +- Modules/CheckTypeSize.cmake | 26 +++--- Modules/CheckVariableExists.cmake | 19 ++-- Modules/Documentation.cmake | 3 + Modules/ExternalData.cmake | 36 +++++--- Modules/ExternalProject.cmake | 128 ++++++++++++++++++++++----- Modules/FeatureSummary.cmake | 26 ++++-- Modules/FetchContent.cmake | 7 ++ Modules/FindALSA.cmake | 2 + Modules/FindArmadillo.cmake | 3 + Modules/FindBISON.cmake | 16 +++- Modules/FindBLAS.cmake | 34 ++++++- Modules/FindBZip2.cmake | 5 +- Modules/FindBoost.cmake | 58 +++++++++--- Modules/FindCUDA.cmake | 57 ++++++++---- Modules/FindCUDAToolkit.cmake | 5 ++ Modules/FindCURL.cmake | 14 ++- Modules/FindCups.cmake | 2 + Modules/FindCurses.cmake | 8 +- Modules/FindDoxygen.cmake | 79 ++++++++++------- Modules/FindEXPAT.cmake | 2 + Modules/FindFLEX.cmake | 19 ++-- Modules/FindFLTK.cmake | 4 + Modules/FindFreetype.cmake | 7 +- Modules/FindGDAL.cmake | 5 +- Modules/FindGLEW.cmake | 5 ++ Modules/FindGLUT.cmake | 5 ++ Modules/FindGTK2.cmake | 24 ++++- Modules/FindGTest.cmake | 15 +++- Modules/FindGettext.cmake | 2 +- Modules/FindGit.cmake | 13 +-- Modules/FindGnuTLS.cmake | 2 + Modules/FindHDF5.cmake | 12 ++- Modules/FindHg.cmake | 3 +- Modules/FindICU.cmake | 3 + Modules/FindIce.cmake | 12 +++ Modules/FindImageMagick.cmake | 3 + Modules/FindIntl.cmake | 8 +- Modules/FindJPEG.cmake | 8 +- Modules/FindJava.cmake | 7 +- Modules/FindLAPACK.cmake | 21 +++++ Modules/FindLATEX.cmake | 4 + Modules/FindLibArchive.cmake | 4 + Modules/FindLibLZMA.cmake | 2 + Modules/FindLibXml2.cmake | 8 +- Modules/FindLibXslt.cmake | 5 +- Modules/FindLua.cmake | 5 +- Modules/FindMPI.cmake | 11 ++- Modules/FindMatlab.cmake | 38 +++++++- Modules/FindOpenACC.cmake | 17 ++-- Modules/FindOpenCL.cmake | 5 ++ Modules/FindOpenGL.cmake | 44 ++++++--- Modules/FindOpenMP.cmake | 10 ++- Modules/FindOpenSSL.cmake | 17 +++- Modules/FindPNG.cmake | 2 + Modules/FindPackageHandleStandardArgs.cmake | 18 +++- Modules/FindPkgConfig.cmake | 76 ++++++++++++---- Modules/FindPostgreSQL.cmake | 2 + Modules/FindProtobuf.cmake | 24 ++++- Modules/FindPython.cmake | 2 +- Modules/FindPython2.cmake | 2 +- Modules/FindPython3.cmake | 2 +- Modules/FindQt.cmake | 6 +- Modules/FindRuby.cmake | 12 ++- Modules/FindSDL.cmake | 8 ++ Modules/FindSWIG.cmake | 19 ++-- Modules/FindSquish.cmake | 3 +- Modules/FindSubversion.cmake | 9 +- Modules/FindTIFF.cmake | 7 ++ Modules/FindThreads.cmake | 4 + Modules/FindVulkan.cmake | 7 +- Modules/FindX11.cmake | 20 +++++ Modules/FindXercesC.cmake | 5 ++ Modules/FindZLIB.cmake | 5 ++ Modules/FindwxWidgets.cmake | 9 ++ Modules/GNUInstallDirs.cmake | 11 ++- Modules/GenerateExportHeader.cmake | 22 +++-- Modules/GetPrerequisites.cmake | 11 +-- Modules/GoogleTest.cmake | 10 +++ Modules/InstallRequiredSystemLibraries.cmake | 16 +++- Modules/ProcessorCount.cmake | 3 + Modules/UseJava.cmake | 44 ++++++--- Modules/UseSWIG.cmake | 70 +++++++++++++-- Modules/WriteCompilerDetectionHeader.cmake | 27 ++++-- 108 files changed, 1302 insertions(+), 366 deletions(-) diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index 3315411..160b976 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -203,6 +203,8 @@ Package .. variable:: CPACK_IFW_PACKAGE_RESOURCES + .. versionadded:: 3.7 + List of additional resources ('.qrc' files) to include in the installer binary. @@ -273,6 +275,8 @@ These variables are cached, and may be configured if needed. .. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE + .. versionadded:: 3.19 + The path to ``archivegen``. .. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst index 19b15e9..963f9d1 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -13,5 +13,8 @@ configuration run (including the first), the environment variable will be ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. This environment variable is primarily meant for use with projects that -enable ``CUDA`` as a first-class language. The :module:`FindCUDA` -module will also use it to initialize its ``CUDA_HOST_COMPILER`` setting. +enable ``CUDA`` as a first-class language. + +.. versionadded:: 3.13 + The :module:`FindCUDA` + module will use this variable to initialize its ``CUDA_HOST_COMPILER`` setting. diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake index f521d22..0beff04 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 ```` 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 be4a3be..7086722 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 1a7f9cf..372e9f4 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 ```` 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 ```` 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 7529a1f..eb1d43b 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 6ce0bfc..d57cf18 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 ('.ui' files) representing pages to load. ``TRANSLATIONS`` + .. versionadded:: 3.8 + is a list of ('.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 ('.ui' files) representing pages to load. ``TRANSLATIONS`` + .. versionadded:: 3.8 + is a list of ('.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 a01a2fe..a6fa3a4 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