Commit 8fea9531 authored by Nikita Nemkin's avatar Nikita Nemkin
Browse files

Help: Add `.. versionadded` directives to module docs

Issue: #19715
parent 8634561d
......@@ -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
......
......@@ -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.
......@@ -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
......
......@@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -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
......
......@@ -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
......
......@@ -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.
::
......
......@@ -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)
......
......@@ -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})
......
......@@ -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.
......
......@@ -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.
......
......@@ -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.
......
......@@ -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.
......
......@@ -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:
......
......@@ -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
......
......@@ -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).
......
......@@ -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::
......
......@@ -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
^^^^^^^^
......
......@@ -29,12 +29,14 @@ the way the check is run: