mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-04 21:00:17 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'versionadded'

Browse Source 
5000f93a91 Help: Fix grammar in `.. versionadded` directives
8fea95319b Help: Add `.. versionadded` directives to module docs
8634561dca Help: Improve formatting for FindBoost and FindCUDA
ea59b0cd34 Help: Fix version note for CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
05c3060b10 Help: Fix cmake_parse_arguments version note
dafcef8b50 Help: Improve styling for versionadded/deprecated directives
6ae216daef Tests: Make RunCMake.CMP0106 expected output robust to line number changes

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5560
This commit is contained in:
Brad King
2020-12-03 13:48:57 +00:00
committed by Kitware Robot
parent d4992ca605 5000f93a91
commit 0eead931a3
124 changed files with 1955 additions and 798 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Help/command/cmake_parse_arguments.rst
View File

@@ -1,8 +1,6 @@
cmake_parse_arguments
---------------------
.. versionadded:: 3.5
Parse function or macro arguments.
.. code-block:: cmake
@@ -13,6 +11,10 @@ Parse function or macro arguments.
cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
<one_value_keywords> <multi_value_keywords>)
.. versionadded:: 3.5
This command is implemented natively. Previously, it has been defined in the
module :module:`CMakeParseArguments`.
This command is for use in macros or functions.
It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the

10
Help/command/ctest_submit.rst
View File

@@ -115,16 +115,16 @@ to tell CDash which handler to use to process the data.
This signature interprets options in the same way as the first one.
.. versionadded:: 3.8
Added ``RETRY_COUNT``, ``RETRY_DELAY``, ``QUIET`` options.
Added the ``RETRY_COUNT``, ``RETRY_DELAY``, ``QUIET`` options.
.. versionadded:: 3.9
Added ``HTTPHEADER`` option.
Added the ``HTTPHEADER`` option.
.. versionadded:: 3.13
Added ``RETURN_VALUE`` option.
Added the ``RETURN_VALUE`` option.
.. versionadded:: 3.14
Added ``SUBMIT_URL`` option.
Added the ``SUBMIT_URL`` option.
.. versionadded:: 3.15
Added ``BUILD_ID`` option.
Added the ``BUILD_ID`` option.

2
Help/command/file.rst
View File

@@ -126,7 +126,7 @@ Parse a list of ASCII strings from ``<filename>`` and store it in
the ``ENCODING`` option will be defaulted to respect the Byte Order Mark.
.. versionadded:: 3.2
Added ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings.
Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings.
For example, the code

2
Help/command/find_package.rst
View File

@@ -432,7 +432,7 @@ enabled.
hard-coded guesses.
.. versionadded:: 3.16
Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
Added the ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
various search locations.
.. |FIND_XXX| replace:: find_package

2
Help/command/get_filename_component.rst
View File

@@ -25,7 +25,7 @@ Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
.. versionadded:: 3.14
Added ``LAST_EXT`` and ``NAME_WLE`` modes.
Added the ``LAST_EXT`` and ``NAME_WLE`` modes.
Paths are returned with forward slashes and have no trailing slashes.
If the optional ``CACHE`` argument is specified, the result variable is

4
Help/command/list.rst
View File

@@ -318,10 +318,10 @@ Reverses the contents of the list in-place.
Sorts the list in-place alphabetically.
.. versionadded:: 3.13
Added ``COMPARE``, ``CASE``, and ``ORDER`` options.
Added the ``COMPARE``, ``CASE``, and ``ORDER`` options.
.. versionadded:: 3.18
Added ``COMPARE NATURAL`` option.
Added the ``COMPARE NATURAL`` option.
Use the ``COMPARE`` keyword to select the comparison method for sorting.
The ``<compare>`` option should be one of:

2
Help/command/message.rst
View File

@@ -72,7 +72,7 @@ influences the way the message is handled:
removed before releasing the project, packaging up the files, etc.
.. versionadded:: 3.15
Added ``NOTICE``, ``VERBOSE``, ``DEBUG``, and ``TRACE`` levels.
Added the ``NOTICE``, ``VERBOSE``, ``DEBUG``, and ``TRACE`` levels.
The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout
with the message preceded by two hyphens and a space. All other message types

10
Help/command/project.rst
View File

@@ -76,7 +76,7 @@ The options are:
then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`.
.. versionadded:: 3.12
Added ``<PROJECT-NAME>_DESCRIPTION`` variable.
Added the ``<PROJECT-NAME>_DESCRIPTION`` variable.
``HOMEPAGE_URL <url-string>``
.. versionadded:: 3.12
@@ -120,8 +120,6 @@ options are intended for use as default values in package metadata and documenta
Code Injection
^^^^^^^^^^^^^^
.. versionadded:: 3.15
If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set,
the files they point to will be included as the first step of the
@@ -135,8 +133,12 @@ they point to will be included as the last step of the ``project()`` command.
If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`.
.. versionadded:: 3.15
Added the ``CMAKE_PROJECT_INCLUDE`` and ``CMAKE_PROJECT_INCLUDE_BEFORE``
variables.
.. versionadded:: 3.17
Added ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`` variable.
Added the ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`` variable.
Usage
^^^^^

4
Help/command/string.rst
View File

@@ -335,7 +335,7 @@ Comparison
Compare the strings and store true or false in the ``<output_variable>``.
.. versionadded:: 3.7
Added ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
.. _`Supported Hash Algorithms`:
@@ -373,7 +373,7 @@ The supported ``<HASH>`` algorithm names are:
Keccak SHA-3.
.. versionadded:: 3.8
Added ``SHA3`` hash algorithms.
Added the ``SHA3_*`` hash algorithms.
Generation
^^^^^^^^^^

4
Help/cpack_gen/deb.rst
View File

@@ -224,7 +224,7 @@ List of CPack DEB generator specific variables:
Per-component ``CPACK_DEBIAN_<COMPONENT>_DESCRIPTION`` variables.
.. versionadded:: 3.16
``CPACK_PACKAGE_DESCRIPTION_FILE`` variable.
The ``CPACK_PACKAGE_DESCRIPTION_FILE`` variable.
.. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description
@@ -303,7 +303,7 @@ List of CPack DEB generator specific variables:
* Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
.. versionadded:: 3.12
``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
.. note::

2
Help/cpack_gen/freebsd.rst
View File

@@ -90,7 +90,7 @@ the RPM information (e.g. package license).
for Debian packaging, so we may as well re-use it).
.. versionadded:: 3.12
``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE

4
Help/cpack_gen/ifw.rst
View File

@@ -209,6 +209,8 @@ Package
.. variable:: CPACK_IFW_PACKAGE_RESOURCES
.. versionadded:: 3.7
List of additional resources ('.qrc' files) to include in the installer
binary.
@@ -279,6 +281,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

6
Help/cpack_gen/rpm.rst
View File

@@ -210,7 +210,7 @@ List of CPack RPM generator specific variables:
* Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
.. versionadded:: 3.12
``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
.. variable:: CPACK_RPM_PACKAGE_DESCRIPTION
CPACK_RPM_<component>_PACKAGE_DESCRIPTION
@@ -527,7 +527,7 @@ List of CPack RPM generator specific variables:
rpm -qp --scripts package.rpm
.. versionadded:: 3.18
``CPACK_RPM_PRE_TRANS_SCRIPT_FILE`` variable.
The ``CPACK_RPM_PRE_TRANS_SCRIPT_FILE`` variable.
.. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
@@ -551,7 +551,7 @@ List of CPack RPM generator specific variables:
rpm -qp --scripts package.rpm
.. versionadded:: 3.18
``CPACK_RPM_POST_TRANS_SCRIPT_FILE`` variable.
The ``CPACK_RPM_POST_TRANS_SCRIPT_FILE`` variable.
.. variable:: CPACK_RPM_USER_FILELIST
CPACK_RPM_<COMPONENT>_USER_FILELIST

7
Help/envvar/CUDAHOSTCXX.rst
View File

@@ -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.

2
Help/generator/Green Hills MULTI.rst
View File

@@ -65,7 +65,7 @@ Cache variables that are used for toolset and target system customization:
| ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``.
.. versionadded:: 3.15
``GHS_OS_DIR_OPTION`` variable.
The ``GHS_OS_DIR_OPTION`` variable.
* ``GHS_BSP_NAME``

28
Modules/BundleUtilities.cmake
View File

@@ -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

5
Modules/CMakeGraphVizOptions.cmake
View File

@@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

46
Modules/CMakePackageConfigHelpers.cmake
View File

@@ -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,23 +160,28 @@ 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
.. versionadded:: 3.11
The ``SameMinorVersion`` compatibility mode.
.. 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.
.. 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.
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.
Internally, this macro executes :command:`configure_file()` to create the
resulting version file. Depending on the ``COMPATIBILITY``, the corresponding
``BasicConfigVersion-<COMPATIBILITY>.cmake.in`` file is used.

12
Modules/CPack.cmake
View File

@@ -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

86
Modules/CPackIFW.cmake
View File

@@ -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``
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.
``SORTING_PRIORITY``
.. versionadded:: 3.8
is priority of the component in the tree.
``PRIORITY``
.. deprecated:: 3.8
Old name for ``SORTING_PRIORITY``.
``DEPENDS``, ``DEPENDENCIES``
.. versionadded:: 3.8
``DEPENDS`` | ``DEPENDENCIES``
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.
::

13
Modules/CTestCoverageCollectGCOV.cmake
View File

@@ -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)

9
Modules/CTestUseLaunchers.cmake
View File

@@ -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})

4
Modules/CheckCSourceCompiles.cmake
View File

@@ -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.

4
Modules/CheckCSourceRuns.cmake
View File

@@ -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.

4
Modules/CheckCXXSourceCompiles.cmake
View File

@@ -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.

4
Modules/CheckCXXSourceRuns.cmake
View File

@@ -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.

6
Modules/CheckCXXSymbolExists.cmake
View File

@@ -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:

5
Modules/CheckFortranFunctionExists.cmake
View File

@@ -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

2
Modules/CheckFortranSourceCompiles.cmake
View File

@@ -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).

6
Modules/CheckFunctionExists.cmake
View File

@@ -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::

3
Modules/CheckIPOSupported.cmake
View File

@@ -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
^^^^^^^^

6
Modules/CheckIncludeFile.cmake
View File

@@ -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

6
Modules/CheckIncludeFileCXX.cmake
View File

@@ -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.

6
Modules/CheckIncludeFiles.cmake
View File

@@ -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.

19
Modules/CheckLibraryExists.cmake
View File

@@ -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)

22
Modules/CheckPrototypeDefinition.cmake
View File

@@ -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.
#]=======================================================================]
#

23
Modules/CheckStructHasMember.cmake
View File

@@ -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:

6
Modules/CheckSymbolExists.cmake
View File

@@ -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:

26
Modules/CheckTypeSize.cmake
View File

@@ -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)

19
Modules/CheckVariableExists.cmake
View File

@@ -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)

3
Modules/Documentation.cmake
View File

@@ -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).
#]=======================================================================]

36
Modules/ExternalData.cmake
View File

@@ -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.

128
Modules/ExternalProject.cmake
View File

@@ -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

26
Modules/FeatureSummary.cmake
View File

@@ -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

7
Modules/FetchContent.cmake
View File

@@ -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

2
Modules/FindALSA.cmake
View File

@@ -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.

3
Modules/FindArmadillo.cmake
View File

@@ -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:
::

16
Modules/FindBISON.cmake
View File

@@ -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:

34
Modules/FindBLAS.cmake
View File

@@ -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``).
#]=======================================================================]

5
Modules/FindBZip2.cmake
View File

@@ -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``

414
Modules/FindBoost.cmake
View File

@@ -7,7 +7,9 @@ FindBoost
Find Boost include dirs and libraries
Use this module by invoking find_package with the form::
Use this module by invoking :command:`find_package` with the form:
.. code-block:: cmake
find_package(Boost
[version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
@@ -20,77 +22,175 @@ Use this module by invoking find_package with the form::
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 "Boost CMake" section below. For the former
case results are reported in variables::
latter case skip to the :ref:`Boost CMake` section below.
Boost_FOUND - True if headers and requested libraries were found
Boost_INCLUDE_DIRS - Boost include directories
Boost_LIBRARY_DIRS - Link directories for Boost libraries
Boost_LIBRARIES - Boost component libraries to be linked
Boost_<C>_FOUND - True if component <C> was found (<C> is upper-case)
Boost_<C>_LIBRARY - Libraries to link for component <C> (may include
target_link_libraries debug/optimized keywords)
Boost_VERSION_MACRO - BOOST_VERSION value from boost/version.hpp
Boost_VERSION_STRING - Boost version number in x.y.z format
Boost_VERSION - if CMP0093 NEW => same as Boost_VERSION_STRING
if CMP0093 OLD or unset => same as Boost_VERSION_MACRO
Boost_LIB_VERSION - Version string appended to library filenames
Boost_VERSION_MAJOR - Boost major version number (X in X.y.z)
alias: Boost_MAJOR_VERSION
Boost_VERSION_MINOR - Boost minor version number (Y in x.Y.z)
alias: Boost_MINOR_VERSION
Boost_VERSION_PATCH - Boost subminor version number (Z in x.y.Z)
alias: Boost_SUBMINOR_VERSION
Boost_VERSION_COUNT - Amount of version components (3)
Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
- Pass to add_definitions() to have diagnostic
information about Boost's automatic linking
displayed during compilation
.. versionadded:: 3.7
``bzip2`` and ``zlib`` components (Windows only).
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.11
The ``OPTIONAL_COMPONENTS`` option.
This module reads hints about search locations from variables::
.. versionadded:: 3.13
``stacktrace_*`` components.
BOOST_ROOT - Preferred installation prefix
(or BOOSTROOT)
BOOST_INCLUDEDIR - Preferred include directory e.g. <prefix>/include
BOOST_LIBRARYDIR - Preferred library directory e.g. <prefix>/lib
Boost_NO_SYSTEM_PATHS - Set to ON to disable searching in locations not
specified by these hint variables. Default is OFF.
Boost_ADDITIONAL_VERSIONS
- List of Boost versions not known to this module
(Boost install locations may contain the version)
.. versionadded:: 3.19
``bzip2`` and ``zlib`` components on all platforms.
and saves search results persistently in CMake cache entries::
Result Variables
^^^^^^^^^^^^^^^^
Boost_INCLUDE_DIR - Directory containing Boost headers
Boost_LIBRARY_DIR_RELEASE - Directory containing release Boost libraries
Boost_LIBRARY_DIR_DEBUG - Directory containing debug Boost libraries
Boost_<C>_LIBRARY_DEBUG - Component <C> library debug variant
Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
This module defines the following variables:
The following :prop_tgt:`IMPORTED` targets are also defined::
``Boost_FOUND``
True if headers and requested libraries were found.
Boost::headers - Target for header-only dependencies
(Boost include directory)
alias: Boost::boost
Boost::<C> - Target for specific component dependency
(shared or static library); <C> is lower-
case
Boost::diagnostic_definitions - interface target to enable diagnostic
information about Boost's automatic linking
during compilation (adds BOOST_LIB_DIAGNOSTIC)
Boost::disable_autolinking - interface target to disable automatic
linking with MSVC (adds BOOST_ALL_NO_LIB)
Boost::dynamic_linking - interface target to enable dynamic linking
linking with MSVC (adds BOOST_ALL_DYN_LINK)
``Boost_INCLUDE_DIRS``
Boost include directories.
``Boost_LIBRARY_DIRS``
Link directories for Boost libraries.
``Boost_LIBRARIES``
Boost component libraries to be linked.
``Boost_<COMPONENT>_FOUND``
True if component ``<COMPONENT>`` was found (``<COMPONENT>`` name is upper-case).
``Boost_<COMPONENT>_LIBRARY``
Libraries to link for component ``<COMPONENT>`` (may include
:command:`target_link_libraries` debug/optimized keywords).
``Boost_VERSION_MACRO``
``BOOST_VERSION`` value from ``boost/version.hpp``.
``Boost_VERSION_STRING``
Boost version number in ``X.Y.Z`` format.
``Boost_VERSION``
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.
``Boost_VERSION_MAJOR``, ``Boost_MAJOR_VERSION``
Boost major version number (``X`` in ``X.Y.Z``).
``Boost_VERSION_MINOR``, ``Boost_MINOR_VERSION``
Boost minor version number (``Y`` in ``X.Y.Z``).
``Boost_VERSION_PATCH``, ``Boost_SUBMINOR_VERSION``
Boost subminor version number (``Z`` in ``X.Y.Z``).
``Boost_VERSION_COUNT``
Amount of version components (3).
``Boost_LIB_DIAGNOSTIC_DEFINITIONS`` (Windows-specific)
Pass to :command:`add_definitions` to have diagnostic
information about Boost's automatic linking
displayed during compilation
.. versionadded:: 3.15
The ``Boost_VERSION_<PART>`` variables.
Cache variables
^^^^^^^^^^^^^^^
Search results are saved persistently in CMake cache entries:
``Boost_INCLUDE_DIR``
Directory containing Boost headers.
``Boost_LIBRARY_DIR_RELEASE``
Directory containing release Boost libraries.
``Boost_LIBRARY_DIR_DEBUG``
Directory containing debug Boost libraries.
``Boost_<COMPONENT>_LIBRARY_DEBUG``
Component ``<COMPONENT>`` library debug variant.
``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
^^^^^
This module reads hints about search locations from variables:
``BOOST_ROOT``, ``BOOSTROOT``
Preferred installation prefix.
``BOOST_INCLUDEDIR``
Preferred include directory e.g. ``<prefix>/include``.
``BOOST_LIBRARYDIR``
Preferred library directory e.g. ``<prefix>/lib``.
``Boost_NO_SYSTEM_PATHS``
Set to ``ON`` to disable searching in locations not
specified by these hint variables. Default is ``OFF``.
``Boost_ADDITIONAL_VERSIONS``
List of Boost versions not known to this module.
(Boost install locations may contain the version).
Users may set these hints or results as ``CACHE`` entries. Projects
should not read these entries directly but instead use the above
result variables. Note that some hint names start in upper-case
``BOOST``. One may specify these as environment variables if they are
not specified as CMake variables or cache entries.
This module first searches for the Boost header files using the above
hint variables (excluding ``BOOST_LIBRARYDIR``) and saves the result in
``Boost_INCLUDE_DIR``. Then it searches for requested component libraries
using the above hints (excluding ``BOOST_INCLUDEDIR`` and
``Boost_ADDITIONAL_VERSIONS``), "lib" directories near ``Boost_INCLUDE_DIR``,
and the library name configuration settings below. It saves the
library directories in ``Boost_LIBRARY_DIR_DEBUG`` and
``Boost_LIBRARY_DIR_RELEASE`` and individual library
locations in ``Boost_<COMPONENT>_LIBRARY_DEBUG`` and ``Boost_<COMPONENT>_LIBRARY_RELEASE``.
When one changes settings used by previous searches in the same build
tree (excluding environment variables) this module discards previous
search results affected by the changes and searches again.
Imported Targets
^^^^^^^^^^^^^^^^
.. versionadded:: 3.5
This module defines the following :prop_tgt:`IMPORTED` targets:
``Boost::boost``
Target for header-only dependencies. (Boost include directory).
``Boost::headers``
.. versionadded:: 3.15
Alias for ``Boost::boost``.
``Boost::<component>``
Target for specific component dependency (shared or static library);
``<component>`` name is lower-case.
``Boost::diagnostic_definitions``
Interface target to enable diagnostic information about Boost's automatic
linking during compilation (adds ``-DBOOST_LIB_DIAGNOSTIC``).
``Boost::disable_autolinking``
Interface target to disable automatic linking with MSVC
(adds ``-DBOOST_ALL_NO_LIB``).
``Boost::dynamic_linking``
Interface target to enable dynamic linking linking with MSVC
(adds ``-DBOOST_ALL_DYN_LINK``).
Implicit dependencies such as ``Boost::filesystem`` requiring
``Boost::system`` will be automatically detected and satisfied, even
@@ -104,97 +204,117 @@ than variables created by this module: multiple calls to
different options (e.g. static or shared) will not override the
values of the targets created by the first call.
Users may set these hints or results as ``CACHE`` entries. Projects
should not read these entries directly but instead use the above
result variables. Note that some hint names start in upper-case
"BOOST". One may specify these as environment variables if they are
not specified as CMake variables or cache entries.
This module first searches for the ``Boost`` header files using the above
hint variables (excluding ``BOOST_LIBRARYDIR``) and saves the result in
``Boost_INCLUDE_DIR``. Then it searches for requested component libraries
using the above hints (excluding ``BOOST_INCLUDEDIR`` and
``Boost_ADDITIONAL_VERSIONS``), "lib" directories near ``Boost_INCLUDE_DIR``,
and the library name configuration settings below. It saves the
library directories in ``Boost_LIBRARY_DIR_DEBUG`` and
``Boost_LIBRARY_DIR_RELEASE`` and individual library
locations in ``Boost_<C>_LIBRARY_DEBUG`` and ``Boost_<C>_LIBRARY_RELEASE``.
When one changes settings used by previous searches in the same build
tree (excluding environment variables) this module discards previous
search results affected by the changes and searches again.
Other Variables
^^^^^^^^^^^^^^^
Boost libraries come in many variants encoded in their file name.
Users or projects may tell this module which variant to find by
setting variables::
setting variables:
Boost_USE_DEBUG_LIBS - Set to ON or OFF to specify whether to search
and use the debug libraries. Default is ON.
Boost_USE_RELEASE_LIBS - Set to ON or OFF to specify whether to search
and use the release libraries. Default is ON.
Boost_USE_MULTITHREADED - Set to OFF to use the non-multithreaded
libraries ('mt' tag). Default is ON.
Boost_USE_STATIC_LIBS - Set to ON to force the use of the static
libraries. Default is OFF.
Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
libraries linked statically to the C++ runtime
('s' tag). Default is platform dependent.
Boost_USE_DEBUG_RUNTIME - Set to ON or OFF to specify whether to use
libraries linked to the MS debug C++ runtime
('g' tag). Default is ON.
Boost_USE_DEBUG_PYTHON - Set to ON to use libraries compiled with a
debug Python build ('y' tag). Default is OFF.
Boost_USE_STLPORT - Set to ON to use libraries compiled with
STLPort ('p' tag). Default is OFF.
Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
- Set to ON to use libraries compiled with
STLPort deprecated "native iostreams"
('n' tag). Default is OFF.
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.
Boost_LIB_PREFIX - 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 - Set to the architecture-specific library suffix
(e.g. "-x64"). Default is auto-computed for the
C++ compiler in use.
Boost_THREADAPI - Suffix for "thread" component library name,
such as "pthread" or "win32". Names with
and without this suffix will both be tried.
Boost_NAMESPACE - Alternate namespace used to build boost with
e.g. if set to "myboost", will search for
myboost_thread instead of boost_thread.
``Boost_USE_DEBUG_LIBS``
.. versionadded:: 3.10
Other variables one may set to control this module are::
Set to ``ON`` or ``OFF`` to specify whether to search and use the debug
libraries. Default is ``ON``.
Boost_DEBUG - Set to ON to enable debug output from FindBoost.
Please enable this before filing any bug report.
Boost_REALPATH - Set to ON to resolve symlinks for discovered
libraries to assist with packaging. For example,
the "system" component library may be resolved to
"/usr/lib/libboost_system.so.1.67.0" instead of
"/usr/lib/libboost_system.so". This does not
affect linking and should not be enabled unless
the user needs this information.
Boost_LIBRARY_DIR - Default value for Boost_LIBRARY_DIR_RELEASE and
Boost_LIBRARY_DIR_DEBUG.
``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``.
``Boost_USE_MULTITHREADED``
Set to OFF to use the non-multithreaded libraries ("mt" tag). Default is
``ON``.
``Boost_USE_STATIC_LIBS``
Set to ON to force the use of the static libraries. Default is ``OFF``.
``Boost_USE_STATIC_RUNTIME``
Set to ``ON`` or ``OFF`` to specify whether to use libraries linked
statically to the C++ runtime ("s" tag). Default is platform dependent.
``Boost_USE_DEBUG_RUNTIME``
Set to ``ON`` or ``OFF`` to specify whether to use libraries linked to the
MS debug C++ runtime ("g" tag). Default is ``ON``.
``Boost_USE_DEBUG_PYTHON``
Set to ``ON`` to use libraries compiled with a debug Python build ("y"
tag). Default is ``OFF``.
``Boost_USE_STLPORT``
Set to ``ON`` to use libraries compiled with STLPort ("p" tag). Default is
``OFF``.
``Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS``
Set to ON to use libraries compiled with STLPort deprecated "native
iostreams" ("n" tag). Default is ``OFF``.
``Boost_COMPILER``
Set to the compiler-specific library suffix (e.g. ``-gcc43``). Default is
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.
``Boost_THREADAPI``
Suffix for ``thread`` component library name, such as ``pthread`` or
``win32``. Names with and without this suffix will both be tried.
``Boost_NAMESPACE``
Alternate namespace used to build boost with e.g. if set to ``myboost``,
will search for ``myboost_thread`` instead of ``boost_thread``.
Other variables one may set to control this module are:
``Boost_DEBUG``
Set to ``ON`` to enable debug output from ``FindBoost``.
Please enable this before filing any bug report.
``Boost_REALPATH``
Set to ``ON`` to resolve symlinks for discovered libraries to assist with
packaging. For example, the "system" component library may be resolved to
``/usr/lib/libboost_system.so.1.67.0`` instead of
``/usr/lib/libboost_system.so``. This does not affect linking and should
not be enabled unless the user needs this information.
``Boost_LIBRARY_DIR``
Default value for ``Boost_LIBRARY_DIR_RELEASE`` and
``Boost_LIBRARY_DIR_DEBUG``.
On Visual Studio and Borland compilers Boost headers request automatic
linking to corresponding libraries. This requires matching libraries
to be linked explicitly or available in the link library search path.
In this case setting ``Boost_USE_STATIC_LIBS`` to ``OFF`` may not achieve
dynamic linking. Boost automatic linking typically requests static
libraries with a few exceptions (such as ``Boost.Python``). Use::
libraries with a few exceptions (such as ``Boost.Python``). Use:
.. code-block:: cmake
add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
to ask Boost to report information about automatic linking requests.
Example to find Boost headers only::
Examples
^^^^^^^^
Find Boost headers only:
.. code-block:: cmake
find_package(Boost 1.36.0)
if(Boost_FOUND)
@@ -202,7 +322,9 @@ Example to find Boost headers only::
add_executable(foo foo.cc)
endif()
Example to find Boost libraries and use imported targets::
Find Boost libraries and use imported targets:
.. code-block:: cmake
find_package(Boost 1.56 REQUIRED COMPONENTS
date_time filesystem iostreams)
@@ -210,17 +332,21 @@ Example to find Boost libraries and use imported targets::
target_link_libraries(foo Boost::date_time Boost::filesystem
Boost::iostreams)
Example to find Boost Python 3.6 libraries and use imported targets::
Find Boost Python 3.6 libraries and use imported targets:
.. code-block:: cmake
find_package(Boost 1.67 REQUIRED COMPONENTS
python36 numpy36)
add_executable(foo foo.cc)
target_link_libraries(foo Boost::python36 Boost::numpy36)
Example to find Boost headers and some *static* (release only) libraries::
Find Boost headers and some *static* (release only) libraries:
.. code-block:: cmake
set(Boost_USE_STATIC_LIBS ON) # only find static libs
set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
set(Boost_USE_RELEASE_LIBS ON) # only find release libs
set(Boost_USE_MULTITHREADED ON)
set(Boost_USE_STATIC_RUNTIME OFF)
@@ -231,6 +357,8 @@ Example to find Boost headers and some *static* (release only) libraries::
target_link_libraries(foo ${Boost_LIBRARIES})
endif()
.. _`Boost CMake`:
Boost CMake
^^^^^^^^^^^
@@ -238,7 +366,7 @@ If Boost was built using the boost-cmake project or from Boost 1.70.0 on
it provides a package configuration file for use with find_package's config mode.
This module looks for the package configuration file called
``BoostConfig.cmake`` or ``boost-config.cmake`` and stores the result in
``CACHE`` entry "Boost_DIR". If found, the package configuration file is loaded
``CACHE`` entry ``Boost_DIR``. If found, the package configuration file is loaded
and this module returns with no further action. See documentation of
the Boost CMake package configuration for details on what it provides.

722
Modules/FindCUDA.cmake
View File

@@ -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.
@@ -50,342 +48,476 @@ location. In newer versions of the toolkit the CUDA library is
included with the graphics driver -- be sure that the driver version
matches what is needed by the CUDA runtime version.
Input Variables
"""""""""""""""
The following variables affect the behavior of the macros in the
script (in alphabetical order). Note that any of these flags can be
changed multiple times in the same directory before calling
``CUDA_ADD_EXECUTABLE``, ``CUDA_ADD_LIBRARY``, ``CUDA_COMPILE``,
``CUDA_COMPILE_PTX``, ``CUDA_COMPILE_FATBIN``, ``CUDA_COMPILE_CUBIN``
or ``CUDA_WRAP_SRCS``::
``cuda_add_executable()``, ``cuda_add_library()``, ``cuda_compile()``,
``cuda_compile_ptx()``, ``cuda_compile_fatbin()``, ``cuda_compile_cubin()``
or ``cuda_wrap_srcs()``:
CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
-- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
Note that making this different from the host code when generating object
or C files from CUDA code just won't work, because size_t gets defined by
nvcc in the generated source. If you compile to PTX and then load the
file yourself, you can mix bit sizes between device and host.
``CUDA_64_BIT_DEVICE_CODE`` (Default: host bit size)
Set to ``ON`` to compile for 64 bit device code, OFF for 32 bit device code.
Note that making this different from the host code when generating object
or C files from CUDA code just won't work, because size_t gets defined by
nvcc in the generated source. If you compile to PTX and then load the
file yourself, you can mix bit sizes between device and host.
CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
-- Set to ON if you want the custom build rule to be attached to the source
file in Visual Studio. Turn OFF if you add the same cuda file to multiple
targets.
``CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE`` (Default: ``ON``)
Set to ``ON`` if you want the custom build rule to be attached to the source
file in Visual Studio. Turn OFF if you add the same cuda file to multiple
targets.
This allows the user to build the target from the CUDA file; however, bad
things can happen if the CUDA source file is added to multiple targets.
When performing parallel builds it is possible for the custom build
command to be run more than once and in parallel causing cryptic build
errors. VS runs the rules for every source file in the target, and a
source can have only one rule no matter how many projects it is added to.
When the rule is run from multiple targets race conditions can occur on
the generated file. Eventually everything will get built, but if the user
is unaware of this behavior, there may be confusion. It would be nice if
this script could detect the reuse of source files across multiple targets
and turn the option off for the user, but no good solution could be found.
This allows the user to build the target from the CUDA file; however, bad
things can happen if the CUDA source file is added to multiple targets.
When performing parallel builds it is possible for the custom build
command to be run more than once and in parallel causing cryptic build
errors. VS runs the rules for every source file in the target, and a
source can have only one rule no matter how many projects it is added to.
When the rule is run from multiple targets race conditions can occur on
the generated file. Eventually everything will get built, but if the user
is unaware of this behavior, there may be confusion. It would be nice if
this script could detect the reuse of source files across multiple targets
and turn the option off for the user, but no good solution could be found.
CUDA_BUILD_CUBIN (Default OFF)
-- Set to ON to enable and extra compilation pass with the -cubin option in
Device mode. The output is parsed and register, shared memory usage is
printed during build.
``CUDA_BUILD_CUBIN`` (Default: ``OFF``)
Set to ``ON`` to enable and extra compilation pass with the ``-cubin`` option in
Device mode. The output is parsed and register, shared memory usage is
printed during build.
CUDA_BUILD_EMULATION (Default OFF for device mode)
-- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
when CUDA_BUILD_EMULATION is TRUE.
``CUDA_BUILD_EMULATION`` (Default: ``OFF`` for device mode)
Set to ``ON`` for Emulation mode. ``-D_DEVICEEMU`` is defined for CUDA C files
when ``CUDA_BUILD_EMULATION`` is ``TRUE``.
CUDA_LINK_LIBRARIES_KEYWORD (Default "")
-- The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
target_link_libraries calls. The default is to use no keyword which
uses the old "plain" form of target_link_libraries. Note that is matters
because whatever is used inside the FindCUDA module must also be used
outside - the two forms of target_link_libraries cannot be mixed.
``CUDA_LINK_LIBRARIES_KEYWORD`` (Default: ``""``)
.. versionadded:: 3.9
CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
-- Set to the path you wish to have the generated files placed. If it is
blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
Intermediate files will always be placed in
CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
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
because whatever is used inside the ``FindCUDA`` module must also be used
outside - the two forms of :command:`target_link_libraries` cannot be mixed.
CUDA_HOST_COMPILATION_CPP (Default ON)
-- Set to OFF for C compilation of host code.
``CUDA_GENERATED_OUTPUT_DIR`` (Default: :variable:`CMAKE_CURRENT_BINARY_DIR`)
Set to the path you wish to have the generated files placed. If it is
blank output files will be placed in :variable:`CMAKE_CURRENT_BINARY_DIR`.
Intermediate files will always be placed in
``CMAKE_CURRENT_BINARY_DIR/CMakeFiles``.
CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER)
-- Set the host compiler to be used by nvcc. Ignored if -ccbin or
--compiler-bindir is already present in the CUDA_NVCC_FLAGS or
CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
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 CUDAHOSTCXX environment variable is set it will
be used as the default.
``CUDA_HOST_COMPILATION_CPP`` (Default: ``ON``)
Set to ``OFF`` for C compilation of host code.
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)
``CUDA_HOST_COMPILER`` (Default: ``CMAKE_C_COMPILER``)
Set the host compiler to be used by nvcc. Ignored if ``-ccbin`` or
``--compiler-bindir`` is already present in the ``CUDA_NVCC_FLAGS`` or
``CUDA_NVCC_FLAGS_<CONFIG>`` variables. For Visual Studio targets,
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.
CUDA_PROPAGATE_HOST_FLAGS (Default ON)
-- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
host compiler through nvcc's -Xcompiler flag. This helps make the
generated host code match the rest of the system better. Sometimes
certain flags give nvcc problems, and this will help you turn the flag
propagation off. This does not affect the flags supplied directly to nvcc
via CUDA_NVCC_FLAGS or through the OPTION flags specified through
CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS. Flags used for
shared library compilation are not affected by this flag.
.. versionadded:: 3.13
If the :envvar:`CUDAHOSTCXX` environment variable is set it will
be used as the default.
CUDA_SEPARABLE_COMPILATION (Default OFF)
-- If set this will enable separable compilation for all CUDA runtime object
files. If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
(e.g. calling CUDA_WRAP_SRCS directly),
CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.
``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``)
CUDA_SOURCE_PROPERTY_FORMAT
-- 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
file. See documentation for set_source_files_properties on how to set
this property.
.. versionadded:: 3.6
Contents of these variables may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
CUDA_USE_STATIC_CUDA_RUNTIME (Default ON)
-- 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.
``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
host compiler through nvcc's ``-Xcompiler`` flag. This helps make the
generated host code match the rest of the system better. Sometimes
certain flags give nvcc problems, and this will help you turn the flag
propagation off. This does not affect the flags supplied directly to nvcc
via ``CUDA_NVCC_FLAGS`` or through the ``OPTION`` flags specified through
``cuda_add_library()``, ``cuda_add_executable()``, or ``cuda_wrap_srcs()``. Flags used for
shared library compilation are not affected by this flag.
CUDA_VERBOSE_BUILD (Default OFF)
-- Set to ON to see all the commands used when building the CUDA file. When
using a Makefile generator the value defaults to VERBOSE (run make
VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
always print the output.
``CUDA_SEPARABLE_COMPILATION`` (Default: ``OFF``)
If set this will enable separable compilation for all CUDA runtime object
files. If used outside of ``cuda_add_executable()`` and ``cuda_add_library()``
(e.g. calling ``cuda_wrap_srcs()`` directly),
``cuda_compute_separable_compilation_object_file_name()`` and
``cuda_link_separable_compilation_objects()`` should be called.
The script creates the following macros (in alphabetical order)::
``CUDA_SOURCE_PROPERTY_FORMAT``
.. versionadded:: 3.3
CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
-- Adds the cufft library to the target (can be any target). Handles whether
you are in emulation mode or not.
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``
file. See documentation for set_source_files_properties on how to set
this property.
CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
-- Adds the cublas library to the target (can be any target). Handles
whether you are in emulation mode or not.
``CUDA_USE_STATIC_CUDA_RUNTIME`` (Default: ``ON``)
.. versionadded:: 3.3
CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
[WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
-- Creates an executable "cuda_target" which is made up of the files
specified. All of the non CUDA C files are compiled using the standard
build rules specified by CMAKE and the cuda files are compiled to object
files using nvcc and the host compiler. In addition CUDA_INCLUDE_DIRS is
added automatically to include_directories(). Some standard CMake target
calls can be used on the target after calling this macro
(e.g. set_target_properties and target_link_libraries), but setting
properties that adjust compilation flags will not affect code compiled by
nvcc. Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.
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.
CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
[STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
-- Same as CUDA_ADD_EXECUTABLE except that a library is created.
``CUDA_VERBOSE_BUILD`` (Default: ``OFF``)
Set to ``ON`` to see all the commands used when building the CUDA file. When
using a Makefile generator the value defaults to ``VERBOSE`` (run
``make VERBOSE=1`` to see output), although setting ``CUDA_VERBOSE_BUILD`` to ``ON`` will
always print the output.
CUDA_BUILD_CLEAN_TARGET()
-- Creates a convenience target that deletes all the dependency files
generated. You should make clean after running this target to ensure the
dependency files get regenerated.
Commands
""""""""
CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
[OPTIONS ...] )
-- Returns a list of generated files from the input source files to be used
with ADD_LIBRARY or ADD_EXECUTABLE.
The script creates the following functions and macros (in alphabetical order):
CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
-- Returns a list of PTX files generated from the input source files.
.. code-block:: cmake
CUDA_COMPILE_FATBIN( generated_files file0 file1 ... [OPTIONS ...] )
-- Returns a list of FATBIN files generated from the input source files.
cuda_add_cufft_to_target(<cuda_target>)
CUDA_COMPILE_CUBIN( generated_files file0 file1 ... [OPTIONS ...] )
-- Returns a list of CUBIN files generated from the input source files.
Adds the cufft library to the target (can be any target). Handles whether
you are in emulation mode or not.
CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
cuda_target
object_files )
-- Compute the name of the intermediate link file used for separable
compilation. This file name is typically passed into
CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS. output_file_var is produced
based on cuda_target the list of objects files that need separable
compilation as specified by object_files. If the object_files list is
empty, then output_file_var will be empty. This function is called
automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE. Note that
this is a function and not a macro.
.. code-block:: cmake
CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
-- Sets the directories that should be passed to nvcc
(e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
files.
cuda_add_cublas_to_target(<cuda_target>)
Adds the cublas library to the target (can be any target). Handles
whether you are in emulation mode or not.
CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
nvcc_flags object_files)
-- Generates the link object required by separable compilation from the given
object files. This is called automatically for CUDA_ADD_EXECUTABLE and
CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
directly. When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
nvcc_flags passed in are the same as the flags passed in via the OPTIONS
argument. The only nvcc flag added automatically is the bitness flag as
specified by CUDA_64_BIT_DEVICE_CODE. Note that this is a function
instead of a macro.
.. code-block:: cmake
CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable [target_CUDA_architectures])
-- Selects GPU arch flags for nvcc based on target_CUDA_architectures
target_CUDA_architectures : Auto | Common | All | LIST(ARCH_AND_PTX ...)
- "Auto" detects local machine GPU compute arch at runtime.
- "Common" and "All" cover common and entire subsets of architectures
ARCH_AND_PTX : NAME | NUM.NUM | NUM.NUM(NUM.NUM) | NUM.NUM+PTX
NAME: Fermi Kepler Maxwell Kepler+Tegra Kepler+Tesla Maxwell+Tegra Pascal
NUM: Any number. Only those pairs are currently accepted by NVCC though:
2.0 2.1 3.0 3.2 3.5 3.7 5.0 5.2 5.3 6.0 6.2
Returns LIST of flags to be added to CUDA_NVCC_FLAGS in ${out_variable}
Additionally, sets ${out_variable}_readable to the resulting numeric list
Example:
CUDA_SELECT_NVCC_ARCH_FLAGS(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
LIST(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
cuda_add_executable(<cuda_target> <file>...
[WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA
Note that this is a function instead of a macro.
Creates an executable ``<cuda_target>`` which is made up of the files
specified. All of the non CUDA C files are compiled using the standard
build rules specified by CMake and the CUDA files are compiled to object
files using nvcc and the host compiler. In addition ``CUDA_INCLUDE_DIRS`` is
added automatically to :command:`include_directories`. Some standard CMake target
calls can be used on the target after calling this macro
(e.g. :command:`set_target_properties` and :command:`target_link_libraries`), but setting
properties that adjust compilation flags will not affect code compiled by
nvcc. Such flags should be modified before calling ``cuda_add_executable()``,
``cuda_add_library()`` or ``cuda_wrap_srcs()``.
CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
[STATIC | SHARED | MODULE] [OPTIONS ...] )
-- This is where all the magic happens. CUDA_ADD_EXECUTABLE,
CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
function under the hood.
.. code-block:: cmake
Given the list of files (file0 file1 ... fileN) this macro generates
custom commands that generate either PTX or linkable objects (use "PTX" or
"OBJ" for the format argument to switch). Files that don't end with .cu
or have the HEADER_FILE_ONLY property are ignored.
cuda_add_library(<cuda_target> <file>...
[STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
The arguments passed in after OPTIONS are extra command line options to
give to nvcc. You can also specify per configuration options by
specifying the name of the configuration followed by the options. General
options must precede configuration specific options. Not all
configurations need to be specified, only the ones provided will be used.
Same as ``cuda_add_executable()`` except that a library is created.
OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
DEBUG -g
RELEASE --use_fast_math
RELWITHDEBINFO --use_fast_math;-g
MINSIZEREL --use_fast_math
.. code-block:: cmake
For certain configurations (namely VS generating object files with
CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
be produced for the given cuda file. This is because when you add the
cuda file to Visual Studio it knows that this file produces an object file
and will link in the resulting object file automatically.
cuda_build_clean_target()
This script will also generate a separate cmake script that is used at
build time to invoke nvcc. This is for several reasons.
Creates a convenience target that deletes all the dependency files
generated. You should make clean after running this target to ensure the
dependency files get regenerated.
1. nvcc can return negative numbers as return values which confuses
Visual Studio into thinking that the command succeeded. The script now
checks the error codes and produces errors when there was a problem.
.. code-block:: cmake
2. nvcc has been known to not delete incomplete results when it
encounters problems. This confuses build systems into thinking the
target was generated when in fact an unusable file exists. The script
now deletes the output files if there was an error.
cuda_compile(<generated_files> <file>... [STATIC | SHARED | MODULE]
[OPTIONS ...])
3. By putting all the options that affect the build into a file and then
make the build rule dependent on the file, the output files will be
regenerated when the options change.
Returns a list of generated files from the input source files to be used
with :command:`add_library` or :command:`add_executable`.
This script also looks at optional arguments STATIC, SHARED, or MODULE to
determine when to target the object compilation for a shared library.
BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
CUDA_ADD_LIBRARY. On some systems special flags are added for building
objects intended for shared libraries. A preprocessor macro,
<target_name>_EXPORTS is defined when a shared library compilation is
detected.
.. code-block:: cmake
Flags passed into add_definitions with -D or /D are passed along to nvcc.
cuda_compile_ptx(<generated_files> <file>... [OPTIONS ...])
Returns a list of ``PTX`` files generated from the input source files.
.. code-block:: cmake
The script defines the following variables::
cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...])
CUDA_VERSION_MAJOR -- The major version of cuda as reported by nvcc.
CUDA_VERSION_MINOR -- The minor version.
CUDA_VERSION
CUDA_VERSION_STRING -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
CUDA_HAS_FP16 -- Whether a short float (float16,fp16) is supported.
.. versionadded:: 3.1
CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
CUDA_SDK_ROOT_DIR -- Path to the CUDA SDK. Use this to find files in the
SDK. This script will not directly support finding
specific libraries or headers, as that isn't
supported by NVIDIA. If you want to change
libraries when the path changes see the
FindCUDA.cmake script for an example of how to clear
these variables. There are also examples of how to
use the CUDA_SDK_ROOT_DIR to locate headers or
libraries, if you so choose (at your own risk).
CUDA_INCLUDE_DIRS -- Include directory for cuda headers. Added automatically
for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
CUDA_LIBRARIES -- Cuda RT library.
CUDA_CUFFT_LIBRARIES -- Device or emulation library for the Cuda FFT
implementation (alternative to:
CUDA_ADD_CUFFT_TO_TARGET macro)
CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
implementation (alternative to:
CUDA_ADD_CUBLAS_TO_TARGET macro).
CUDA_cudart_static_LIBRARY -- Statically linkable cuda runtime library.
Only available for CUDA version 5.5+
CUDA_cudadevrt_LIBRARY -- Device runtime library.
Required for separable compilation.
CUDA_cupti_LIBRARY -- CUDA Profiling Tools Interface library.
Only available for CUDA version 4.0+.
CUDA_curand_LIBRARY -- CUDA Random Number Generation library.
Only available for CUDA version 3.2+.
CUDA_cusolver_LIBRARY -- CUDA Direct Solver library.
Only available for CUDA version 7.0+.
CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
Only available for CUDA version 3.2+.
CUDA_npp_LIBRARY -- NVIDIA Performance Primitives lib.
Only available for CUDA version 4.0+.
CUDA_nppc_LIBRARY -- NVIDIA Performance Primitives lib (core).
Only available for CUDA version 5.5+.
CUDA_nppi_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 5.5 - 8.0.
CUDA_nppial_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppicc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppicom_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0 - 10.2.
Replaced by nvjpeg.
CUDA_nppidei_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppif_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppig_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppim_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppist_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppisu_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_nppitc_LIBRARY -- NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
CUDA_npps_LIBRARY -- NVIDIA Performance Primitives lib (signal processing).
Only available for CUDA version 5.5+.
CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
Only available for CUDA version 3.2+.
Windows only.
CUDA_nvcuvid_LIBRARY -- CUDA Video Decoder library.
Only available for CUDA version 3.2+.
Windows only.
CUDA_nvToolsExt_LIBRARY
-- NVIDA CUDA Tools Extension library.
Available for CUDA version 5+.
CUDA_OpenCL_LIBRARY -- NVIDA CUDA OpenCL library.
Available for CUDA version 5+.
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
cuda_compute_separable_compilation_object_file_name(<output_file_var>
<cuda_target>
<object_files>)
Compute the name of the intermediate link file used for separable
compilation. This file name is typically passed into
``CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS``. output_file_var is produced
based on cuda_target the list of objects files that need separable
compilation as specified by ``<object_files>``. If the ``<object_files>`` list is
empty, then ``<output_file_var>`` will be empty. This function is called
automatically for ``cuda_add_library()`` and ``cuda_add_executable()``. Note that
this is a function and not a macro.
.. code-block:: cmake
cuda_include_directories(path0 path1 ...)
Sets the directories that should be passed to nvcc
(e.g. ``nvcc -Ipath0 -Ipath1 ...``). These paths usually contain other ``.cu``
files.
.. code-block:: cmake
cuda_link_separable_compilation_objects(<output_file_var> <cuda_target>
<nvcc_flags> <object_files>)
Generates the link object required by separable compilation from the given
object files. This is called automatically for ``cuda_add_executable()`` and
``cuda_add_library()``, but can be called manually when using ``cuda_wrap_srcs()``
directly. When called from ``cuda_add_library()`` or ``cuda_add_executable()`` the
``<nvcc_flags>`` passed in are the same as the flags passed in via the ``OPTIONS``
argument. The only nvcc flag added automatically is the bitness flag as
specified by ``CUDA_64_BIT_DEVICE_CODE``. Note that this is a function
instead of a macro.
.. code-block:: cmake
cuda_select_nvcc_arch_flags(<out_variable> [<target_CUDA_architecture> ...])
Selects GPU arch flags for nvcc based on ``target_CUDA_architecture``.
Values for ``target_CUDA_architecture``:
* ``Auto``: detects local machine GPU compute arch at runtime.
* ``Common`` and ``All``: cover common and entire subsets of architectures.
* ``<name>``: one of ``Fermi``, ``Kepler``, ``Maxwell``, ``Kepler+Tegra``, ``Kepler+Tesla``, ``Maxwell+Tegra``, ``Pascal``.
* ``<ver>``, ``<ver>(<ver>)``, ``<ver>+PTX``, where ``<ver>`` is one of
``2.0``, ``2.1``, ``3.0``, ``3.2``, ``3.5``, ``3.7``, ``5.0``, ``5.2``, ``5.3``, ``6.0``, ``6.2``.
Returns list of flags to be added to ``CUDA_NVCC_FLAGS`` in ``<out_variable>``.
Additionally, sets ``<out_variable>_readable`` to the resulting numeric list.
Example::
cuda_select_nvcc_arch_flags(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
list(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA.
Note that this is a function instead of a macro.
.. code-block:: cmake
cuda_wrap_srcs(<cuda_target> <format> <generated_files> <file>...
[STATIC | SHARED | MODULE] [OPTIONS ...])
This is where all the magic happens. ``cuda_add_executable()``,
``cuda_add_library()``, ``cuda_compile()``, and ``cuda_compile_ptx()`` all call this
function under the hood.
Given the list of files ``<file>...`` this macro generates
custom commands that generate either PTX or linkable objects (use ``PTX`` or
``OBJ`` for the ``<format>`` argument to switch). Files that don't end with ``.cu``
or have the ``HEADER_FILE_ONLY`` property are ignored.
The arguments passed in after ``OPTIONS`` are extra command line options to
give to nvcc. You can also specify per configuration options by
specifying the name of the configuration followed by the options. General
options must precede configuration specific options. Not all
configurations need to be specified, only the ones provided will be used.
For example:
.. code-block:: cmake
cuda_add_executable(...
OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
DEBUG -g
RELEASE --use_fast_math
RELWITHDEBINFO --use_fast_math;-g
MINSIZEREL --use_fast_math)
For certain configurations (namely VS generating object files with
``CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE`` set to ``ON``), no generated file will
be produced for the given cuda file. This is because when you add the
cuda file to Visual Studio it knows that this file produces an object file
and will link in the resulting object file automatically.
This script will also generate a separate cmake script that is used at
build time to invoke nvcc. This is for several reasons:
* nvcc can return negative numbers as return values which confuses
Visual Studio into thinking that the command succeeded. The script now
checks the error codes and produces errors when there was a problem.
* nvcc has been known to not delete incomplete results when it
encounters problems. This confuses build systems into thinking the
target was generated when in fact an unusable file exists. The script
now deletes the output files if there was an error.
* By putting all the options that affect the build into a file and then
make the build rule dependent on the file, the output files will be
regenerated when the options change.
This script also looks at optional arguments ``STATIC``, ``SHARED``, or ``MODULE`` to
determine when to target the object compilation for a shared library.
:variable:`BUILD_SHARED_LIBS` is ignored in ``cuda_wrap_srcs()``, but it is respected in
``cuda_add_library()``. On some systems special flags are added for building
objects intended for shared libraries. A preprocessor macro,
``<target_name>_EXPORTS`` is defined when a shared library compilation is
detected.
Flags passed into add_definitions with ``-D`` or ``/D`` are passed along to nvcc.
Result Variables
""""""""""""""""
The script defines the following variables:
``CUDA_VERSION_MAJOR``
The major version of cuda as reported by nvcc.
``CUDA_VERSION_MINOR``
The minor version.
``CUDA_VERSION``, ``CUDA_VERSION_STRING``
Full version in the ``X.Y`` format.
``CUDA_HAS_FP16``
.. versionadded:: 3.6
Whether a short float (``float16``, ``fp16``) is supported.
``CUDA_TOOLKIT_ROOT_DIR``
Path to the CUDA Toolkit (defined if not set).
``CUDA_SDK_ROOT_DIR``
Path to the CUDA SDK. Use this to find files in the SDK. This script will
not directly support finding specific libraries or headers, as that isn't
supported by NVIDIA. If you want to change libraries when the path changes
see the ``FindCUDA.cmake`` script for an example of how to clear these
variables. There are also examples of how to use the ``CUDA_SDK_ROOT_DIR``
to locate headers or libraries, if you so choose (at your own risk).
``CUDA_INCLUDE_DIRS``
Include directory for cuda headers. Added automatically
for ``cuda_add_executable()`` and ``cuda_add_library()``.
``CUDA_LIBRARIES``
Cuda RT library.
``CUDA_CUFFT_LIBRARIES``
Device or emulation library for the Cuda FFT implementation (alternative to
``cuda_add_cufft_to_target()`` macro)
``CUDA_CUBLAS_LIBRARIES``
Device or emulation library for the Cuda BLAS implementation (alternative to
``cuda_add_cublas_to_target()`` macro).
``CUDA_cudart_static_LIBRARY``
Statically linkable cuda runtime library.
Only available for CUDA version 5.5+.
``CUDA_cudadevrt_LIBRARY``
.. versionadded:: 3.7
Device runtime library. Required for separable compilation.
``CUDA_cupti_LIBRARY``
CUDA Profiling Tools Interface library.
Only available for CUDA version 4.0+.
``CUDA_curand_LIBRARY``
CUDA Random Number Generation library.
Only available for CUDA version 3.2+.
``CUDA_cusolver_LIBRARY``
.. versionadded:: 3.2
CUDA Direct Solver library.
Only available for CUDA version 7.0+.
``CUDA_cusparse_LIBRARY``
CUDA Sparse Matrix library.
Only available for CUDA version 3.2+.
``CUDA_npp_LIBRARY``
NVIDIA Performance Primitives lib.
Only available for CUDA version 4.0+.
``CUDA_nppc_LIBRARY``
NVIDIA Performance Primitives lib (core).
Only available for CUDA version 5.5+.
``CUDA_nppi_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 5.5 - 8.0.
``CUDA_nppial_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppicc_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppicom_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0 - 10.2.
Replaced by nvjpeg.
``CUDA_nppidei_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppif_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppig_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppim_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppist_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppisu_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_nppitc_LIBRARY``
NVIDIA Performance Primitives lib (image processing).
Only available for CUDA version 9.0.
``CUDA_npps_LIBRARY``
NVIDIA Performance Primitives lib (signal processing).
Only available for CUDA version 5.5+.
``CUDA_nvcuvenc_LIBRARY``
CUDA Video Encoder library.
Only available for CUDA version 3.2+.
Windows only.
``CUDA_nvcuvid_LIBRARY``
CUDA Video Decoder library.
Only available for CUDA version 3.2+.
Windows only.
``CUDA_nvToolsExt_LIBRARY``
.. versionadded:: 3.16
NVIDA CUDA Tools Extension library.
Available for CUDA version 5+.
``CUDA_OpenCL_LIBRARY``
.. versionadded:: 3.16
NVIDA CUDA OpenCL library.
Available for CUDA version 5+.
#]=======================================================================]

5
Modules/FindCUDAToolkit.cmake
View File

@@ -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.

14
Modules/FindCURL.cmake
View File

@@ -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,

2
Modules/FindCups.cmake
View File

@@ -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.

8
Modules/FindCurses.cmake
View File

@@ -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
^^^^^^^^^^^^^^^^^^^^^^

77
Modules/FindDoxygen.cmake
View File

@@ -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.
.. versionadded:: 3.12
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.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``.

2
Modules/FindEXPAT.cmake
View File

@@ -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``

19
Modules/FindFLEX.cmake
View File

@@ -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:
::

4
Modules/FindFLTK.cmake
View File

@@ -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)

7
Modules/FindFreetype.cmake
View File

@@ -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
^^^^^

5
Modules/FindGDAL.cmake
View File

@@ -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
^^^^^^^^^^^^^^^

5
Modules/FindGLEW.cmake
View File

@@ -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)

5
Modules/FindGLUT.cmake
View File

@@ -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)

24
Modules/FindGTK2.cmake
View File

@@ -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
^^^^^^^^^^^^^^^

15
Modules/FindGTest.cmake
View File

@@ -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)

2
Modules/FindGettext.cmake
View File

@@ -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`.
#]=======================================================================]

13
Modules/FindGit.cmake
View File

@@ -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

2
Modules/FindGnuTLS.cmake
View File

@@ -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.

12
Modules/FindHDF5.cmake
View File

@@ -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``.
#]=======================================================================]

3
Modules/FindHg.cmake
View File

@@ -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:
::

3
Modules/FindICU.cmake
View File

@@ -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::

12
Modules/FindIce.cmake
View File

@@ -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

3
Modules/FindImageMagick.cmake
View File

@@ -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

8
Modules/FindIntl.cmake
View File

@@ -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

8
Modules/FindJPEG.cmake
View File

@@ -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
^^^^^^^^^^^^^^^^^^

7
Modules/FindJava.cmake
View File

@@ -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.

21
Modules/FindLAPACK.cmake
View File

@@ -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``

4
Modules/FindLATEX.cmake
View File

@@ -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

4
Modules/FindLibArchive.cmake
View File

@@ -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

2
Modules/FindLibLZMA.cmake
View File

@@ -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.

8
Modules/FindLibXml2.cmake
View File

@@ -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
^^^^^^^^^^^^^^^^

5
Modules/FindLibXslt.cmake
View File

@@ -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``

5
Modules/FindLua.cmake
View File

@@ -5,10 +5,11 @@
FindLua
-------
Locate Lua library.
.. versionadded:: 3.18
Support for Lua 5.4.
This module defines::
::

11
Modules/FindMPI.cmake
View File

@@ -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:
::

38
Modules/FindMatlab.cmake
View File

@@ -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

17
Modules/FindOpenACC.cmake
View File

@@ -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``

5
Modules/FindOpenCL.cmake
View File

@@ -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.

44
Modules/FindOpenGL.cmake
View File

@@ -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*

10
Modules/FindOpenMP.cmake
View File

@@ -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.

17
Modules/FindOpenSSL.cmake
View File

@@ -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)

2
Modules/FindPNG.cmake
View File

@@ -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``

18
Modules/FindPackageHandleStandardArgs.cmake
View File

@@ -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`.

74
Modules/FindPkgConfig.cmake
View File

@@ -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.
.. 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.
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.
.. 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

2
Modules/FindPostgreSQL.cmake
View File

@@ -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.

24
Modules/FindProtobuf.cmake
View File

@@ -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>...])

2
Modules/FindPython.cmake
View File

@@ -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.

2
Modules/FindPython2.cmake
View File

@@ -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.

2
Modules/FindPython3.cmake
View File

@@ -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.

6
Modules/FindQt.cmake
View File

@@ -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

Some files were not shown because too many files have changed in this diff Show More