Timo Röhling
1 month ago
parent
167f7148a5
commit
f5761cd947
@ -0,0 +1,263 @@
|
|||||||
|
cmake_pkg_config
|
||||||
|
----------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
.. only:: html
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Process pkg-config format package files.
|
||||||
|
|
||||||
|
Synopsis
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
|
.. parsed-literal::
|
||||||
|
|
||||||
|
cmake_pkg_config(EXTRACT <package> [<version>] [...])
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This command generates CMake variables and targets from pkg-config format
|
||||||
|
package files natively, without needing to invoke or even require the presence
|
||||||
|
of a pkg-config implementation. A ``<package>`` is either an absolute path to a
|
||||||
|
package file, or a package name to be searched for using the typical pkg-config
|
||||||
|
search patterns. The optional ``<version>`` string has the same format and
|
||||||
|
semantics as a pkg-config style version specifier, with the exception that if
|
||||||
|
no comparison operator is specified ``=`` is assumed.
|
||||||
|
|
||||||
|
.. _`common options`:
|
||||||
|
|
||||||
|
There are multiple signatures for this command, and some of the options are
|
||||||
|
common between them. They are:
|
||||||
|
|
||||||
|
``EXACT`` / ``QUIET`` / ``REQUIRED``
|
||||||
|
The ``EXACT`` option requests that the version string be matched exactly
|
||||||
|
(including empty string, if no version is provided), overriding the typical
|
||||||
|
pkg-config version comparison algorithm. This will ignore any comparison
|
||||||
|
operator attached to the version string.
|
||||||
|
|
||||||
|
The ``QUIET`` option disables informational messages, including those
|
||||||
|
indicating that the package cannot be found if it is not ``REQUIRED``. The
|
||||||
|
``REQUIRED`` option stops processing with an error message if the package
|
||||||
|
cannot be found.
|
||||||
|
|
||||||
|
``STRICTNESS <mode>``
|
||||||
|
Specify how strictly the contents of the package files will be verified during
|
||||||
|
parsing and resolution. An invalid file, under the provided strictness mode,
|
||||||
|
will cause the command to fail. Possible modes are:
|
||||||
|
|
||||||
|
* ``STRICT``: Closely mirrors the behavior of the original FDO pkg-config.
|
||||||
|
Variables and keywords must be unique. Variables must be defined before
|
||||||
|
they are used. The Name, Description, and Version keywords must be present.
|
||||||
|
The overall structure of the file must be valid and parsable.
|
||||||
|
|
||||||
|
* ``PERMISSIVE``: Closely mirrors the behavior of the pkgconf implementation.
|
||||||
|
Duplicate variables are overridden. Duplicate keywords are appended.
|
||||||
|
Undefined variables resolve to empty strings. The Name, Description, and
|
||||||
|
Version keywords must be present. The overall structure of the file must be
|
||||||
|
valid and parsable.
|
||||||
|
|
||||||
|
* ``BEST_EFFORT``: Same behavior as ``PERMISSIVE`` with regards to duplicate
|
||||||
|
or uninitialized variables and keywords, but will not fail under any
|
||||||
|
conditions. Package files which require BEST_EFFORT will fail validation
|
||||||
|
under all other major implementations and should be fixed.
|
||||||
|
|
||||||
|
The default strictness is ``PERMISSIVE``.
|
||||||
|
|
||||||
|
``ENV_MODE``
|
||||||
|
Specifies which environment variables will be queried when running a given
|
||||||
|
command. Possible modes are:
|
||||||
|
|
||||||
|
* ``FDO``: Queries only the original set of ``PKG_CONFIG_*`` environment
|
||||||
|
variables used by the freedesktop.org ``pkg-config`` implementation.
|
||||||
|
|
||||||
|
* ``PKGCONF``: Queries the more extensive set of environment variables used
|
||||||
|
by the ``pkgconf`` implementation.
|
||||||
|
|
||||||
|
* ``IGNORE``: Ignores the presence, absence, and value of environment
|
||||||
|
variables entirely. In all cases an environment variable would be queried
|
||||||
|
its treated as defined, but with a value of empty string for the purpose
|
||||||
|
of the operation. This does not modify the current environment. For boolean
|
||||||
|
environment variables, such as ``PKG_CONFIG_ALLOW_*``, this means they are
|
||||||
|
evaluated as truthy.
|
||||||
|
|
||||||
|
``PKG_CONFIG_SYSROOT_PATH`` is a minor exception. When ``ENV_MODE IGNORE``
|
||||||
|
is used, no root path prepending will occur by default and ``pc_sysrootdir``
|
||||||
|
remains defaulted to ``/``.
|
||||||
|
|
||||||
|
Target-generating subcommands always ignore flag-filtering environment
|
||||||
|
variables. The default environment mode is ``PKGCONF``.
|
||||||
|
|
||||||
|
``PC_LIBDIR <path>...``
|
||||||
|
Overrides the default search location for package files; also used to derive
|
||||||
|
the ``pc_path`` package variable.
|
||||||
|
|
||||||
|
When this option is not provided, the default library directory is the first
|
||||||
|
available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_PC_LIB_DIRS``
|
||||||
|
#. The ``PKG_CONFIG_LIBDIR`` environment variable
|
||||||
|
#. The output of ``pkg-config --variable pc_path pkg-config``
|
||||||
|
#. A platform-dependent default value
|
||||||
|
|
||||||
|
``PC_PATH <path>...``
|
||||||
|
Overrides the supplemental package file directories which will be prepended
|
||||||
|
to the search path; also used to derive the ``pc_path`` package variable.
|
||||||
|
|
||||||
|
When this option is not provided, the default paths are the first available of
|
||||||
|
the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_PC_PATH``
|
||||||
|
#. The ``PKG_CONFIG_PATH`` environment variable
|
||||||
|
#. Empty list
|
||||||
|
|
||||||
|
``DISABLE_UNINSTALLED <bool>``
|
||||||
|
Overrides the search behavior for "uninstalled" package files. These are
|
||||||
|
package files with an "-uninstalled" suffix which describe packages integrated
|
||||||
|
directly from a build tree.
|
||||||
|
|
||||||
|
Normally such package files have higher priority than "installed" packages.
|
||||||
|
When ``DISABLE_UNINSTALLED`` is true, searching for "uninstalled" packages
|
||||||
|
is disabled.
|
||||||
|
|
||||||
|
When this option is not provided, the default search behavior is determined
|
||||||
|
by the first available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED``
|
||||||
|
#. If the ``PKG_CONFIG_DISABLE_UNINSTALLED`` environment variable is defined
|
||||||
|
the search is disabled, otherwise it is enabled.
|
||||||
|
|
||||||
|
``PC_SYSROOT_DIR <path>``
|
||||||
|
Overrides the root path which will be prepended to paths specified by ``-I``
|
||||||
|
compile flags and ``-L`` library search locations; also used to derive the
|
||||||
|
``pc_sysrootdir`` package variable.
|
||||||
|
|
||||||
|
When this option is not provided, the default root path is provided by the
|
||||||
|
first available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_SYSROOT_DIR``
|
||||||
|
#. The ``PKG_CONFIG_SYSROOT_DIR`` environment variable
|
||||||
|
#. If no root path is available, nothing will be prepended to include or
|
||||||
|
library directory paths and ``pc_sysrootdir`` will be set to ``/``
|
||||||
|
|
||||||
|
``TOP_BUILD_DIR <path>``
|
||||||
|
Overrides the top build directory path used to derived the ``pc_top_builddir``
|
||||||
|
package variable.
|
||||||
|
|
||||||
|
When this option is not provided, the default top build directory path is
|
||||||
|
the first available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_TOP_BUILD_DIR``
|
||||||
|
#. The ``PKG_CONFIG_TOP_BUILD_DIR`` environment variable
|
||||||
|
#. If no top build directory path is available, the ``pc_top_builddir``
|
||||||
|
package variable is not set
|
||||||
|
|
||||||
|
Signatures
|
||||||
|
^^^^^^^^^^
|
||||||
|
|
||||||
|
.. signature::
|
||||||
|
cmake_pkg_config(EXTRACT <package> [<version>] [...])
|
||||||
|
|
||||||
|
Extract the contents of the package into variables.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
cmake_pkg_config(EXTRACT <package> [<version>]
|
||||||
|
[REQUIRED] [EXACT] [QUIET]
|
||||||
|
[STRICTNESS <mode>]
|
||||||
|
[ENV_MODE <mode>]
|
||||||
|
[PC_LIBDIR <path>...]
|
||||||
|
[PC_PATH <path>...]
|
||||||
|
[DISABLE_UNINSTALLED <bool>]
|
||||||
|
[PC_SYSROOT_DIR <path>]
|
||||||
|
[TOP_BUILD_DIR <path>]
|
||||||
|
[SYSTEM_INCLUDE_DIRS <path>...]
|
||||||
|
[SYSTEM_LIBRARY_DIRS <path>...]
|
||||||
|
[ALLOW_SYSTEM_INCLUDES <bool>]
|
||||||
|
[ALLOW_SYSTEM_LIBS <bool>])
|
||||||
|
|
||||||
|
The following variables will be populated from the contents of package file:
|
||||||
|
|
||||||
|
==================================== ====== ========================================================================================
|
||||||
|
Variable Type Definition
|
||||||
|
==================================== ====== ========================================================================================
|
||||||
|
``CMAKE_PKG_CONFIG_NAME`` String Value of the ``Name`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_DESCRIPTION`` String Value of the ``Description`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_VERSION`` String Value of the ``Version`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_PROVIDES`` List Value of the ``Provides`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_REQUIRES`` List Value of the ``Requires`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_CONFLICTS`` List Value of the ``Conflicts`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_CFLAGS`` String Value of the ``CFlags`` / ``Cflags`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_INCLUDES`` List All ``-I`` prefixed flags from ``CMAKE_PKG_CONFIG_CFLAGS``
|
||||||
|
``CMAKE_PKG_CONFIG_COMPILE_OPTIONS`` List All flags not prefixed with ``-I`` from ``CMAKE_PKG_CONFIG_CFLAGS``
|
||||||
|
``CMAKE_PKG_CONFIG_LIBS`` String Value of the ``Libs`` keyword
|
||||||
|
``CMAKE_PKG_CONFIG_LIBDIRS`` List All ``-L`` prefixed flags from ``CMAKE_PKG_CONFIG_LIBS``
|
||||||
|
``CMAKE_PKG_CONFIG_LIBNAMES`` List All ``-l`` prefixed flags from ``CMAKE_PKG_CONFIG_LIBS``
|
||||||
|
``CMAKE_PKG_CONFIG_LINK_OPTIONS`` List All flags not prefixed with ``-L`` or ``-l`` from ``CMAKE_PKG_CONFIG_LIBS``
|
||||||
|
``CMAKE_PKG_CONFIG_*_PRIVATE`` \* ``CFLAGS`` / ``LIBS`` / ``REQUIRES`` and derived, but in their ``.private`` suffix forms
|
||||||
|
==================================== ====== ========================================================================================
|
||||||
|
|
||||||
|
``SYSTEM_INCLUDE_DIRS``
|
||||||
|
Overrides the "system" directories for the purpose of flag mangling include
|
||||||
|
directories in ``CMAKE_PKG_CONFIG_CFLAGS`` and derived variables.
|
||||||
|
|
||||||
|
When this option is not provided, the default directories are provided by the
|
||||||
|
first available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS``
|
||||||
|
#. The ``PKG_CONFIG_SYSTEM_INCLUDE_PATH`` environment variable
|
||||||
|
#. The output of ``pkgconf --variable pc_system_includedirs pkg-config``
|
||||||
|
#. A platform-dependent default value
|
||||||
|
|
||||||
|
Additionally, when the ``ENV_MODE`` is ``PKGCONF`` the
|
||||||
|
``CMAKE_PKG_CONFIG_PKGCONF_INCLUDES`` variable will be concatenated to the
|
||||||
|
list if available. If it is not available, the following environment variables
|
||||||
|
will be queried and concatenated:
|
||||||
|
|
||||||
|
* ``CPATH``
|
||||||
|
* ``C_INCLUDE_PATH``
|
||||||
|
* ``CPLUS_INCLUDE_PATH``
|
||||||
|
* ``OBJC_INCLUDE_PATH``
|
||||||
|
* ``INCLUDE`` (Windows Only)
|
||||||
|
|
||||||
|
``SYSTEM_LIBRARY_DIRS``
|
||||||
|
Overrides the "system" directories for the purpose of flag mangling library
|
||||||
|
directories in ``CMAKE_PKG_CONFIG_LIBS`` and derived variables.
|
||||||
|
|
||||||
|
When this option is not provided, the default directories are provided by the
|
||||||
|
first available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_SYS_LIB_DIRS``
|
||||||
|
#. The ``PKG_CONFIG_SYSTEM_LIBRARY_PATH`` environment variable
|
||||||
|
#. The output of ``pkgconf --variable pc_system_libdirs pkg-config``
|
||||||
|
#. A platform-dependent default value
|
||||||
|
|
||||||
|
Additionally, when the ``ENV_MODE`` is ``PKGCONF`` the
|
||||||
|
``CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS`` variable will be concatenated to the
|
||||||
|
list if available. If it is not available, the ``LIBRARY_PATH`` environment
|
||||||
|
variable will be queried and concatenated.
|
||||||
|
|
||||||
|
``ALLOW_SYSTEM_INCLUDES``
|
||||||
|
Preserves "system" directories during flag mangling of include directories
|
||||||
|
in ``CMAKE_PKG_CONFIG_CFLAGS`` and derived variables.
|
||||||
|
|
||||||
|
When this option is not provided, the default value is determined by the first
|
||||||
|
available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES``
|
||||||
|
#. If the ``PKG_CONFIG_ALLOW_SYSTEM_CFLAGS`` environment variable is defined
|
||||||
|
the flags are preserved, otherwise they are filtered during flag mangling.
|
||||||
|
|
||||||
|
|
||||||
|
``ALLOW_SYSTEM_LIBS``
|
||||||
|
Preserves "system" directories during flag mangling of library directories
|
||||||
|
in ``CMAKE_PKG_CONFIG_LIBS`` and derived variables.
|
||||||
|
|
||||||
|
When this option is not provided, the default value is determined by the first
|
||||||
|
available of the following values:
|
||||||
|
|
||||||
|
#. ``CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS``
|
||||||
|
#. If the ``PKG_CONFIG_ALLOW_SYSTEM_LIBS`` environment variable is defined
|
||||||
|
the flags are preserved, otherwise they are filtered during flag mangling.
|
||||||
@ -0,0 +1,46 @@
|
|||||||
|
CMake Integration Testing
|
||||||
|
*************************
|
||||||
|
|
||||||
|
The following documents how to run integration testing builds.
|
||||||
|
See documentation on `CMake Development`_ for more information.
|
||||||
|
|
||||||
|
See the `CMake Testing Guide`_ for running the test suite locally.
|
||||||
|
|
||||||
|
.. _`CMake Development`: README.rst
|
||||||
|
.. _`CMake Testing Guide`: testing.rst
|
||||||
|
|
||||||
|
CMake Dashboard Scripts
|
||||||
|
=======================
|
||||||
|
|
||||||
|
The *integration testing* step of the `CMake Review Process`_ uses a set of
|
||||||
|
testing machines that follow an integration branch on their own schedule to
|
||||||
|
drive testing and submit results to the `CMake CDash Page`_. Anyone is
|
||||||
|
welcome to provide testing machines in order to help keep support for their
|
||||||
|
platforms working.
|
||||||
|
|
||||||
|
The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
|
||||||
|
nightly, continuous, and experimental testing of CMake. Use the following
|
||||||
|
commands to set up a new integration testing client:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ mkdir -p ~/Dashboards
|
||||||
|
$ cd ~/Dashboards
|
||||||
|
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
|
||||||
|
$ cd CMakeScripts
|
||||||
|
|
||||||
|
The `cmake_common.cmake`_ script contains comments at the top with
|
||||||
|
instructions to set up a testing client. As it instructs, create a
|
||||||
|
CTest script with local settings and include ``cmake_common.cmake``.
|
||||||
|
|
||||||
|
.. _`CMake Review Process`: review.rst
|
||||||
|
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
|
||||||
|
.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
|
||||||
|
.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake
|
||||||
|
|
||||||
|
Nightly Start Time
|
||||||
|
------------------
|
||||||
|
|
||||||
|
The ``cmake_common.cmake`` script expects its includer to be run from a
|
||||||
|
nightly scheduled task (cron job). Schedule such tasks for sometime after
|
||||||
|
``1:00am UTC``, the time at which our nightly testing branches fast-forward.
|
||||||
@ -1,43 +1,111 @@
|
|||||||
CMake Testing Process
|
CMake Testing Guide
|
||||||
*********************
|
*******************
|
||||||
|
|
||||||
The following documents the process for running integration testing builds.
|
The following is a guide to the CMake test suite for developers.
|
||||||
See documentation on `CMake Development`_ for more information.
|
See documentation on `CMake Development`_ for more information.
|
||||||
|
|
||||||
|
See `CMake Integration Testing`_ for running integration testing builds.
|
||||||
|
|
||||||
|
See `Tests/README.rst`_ for the test suite layout in the source tree.
|
||||||
|
|
||||||
.. _`CMake Development`: README.rst
|
.. _`CMake Development`: README.rst
|
||||||
|
.. _`CMake Integration Testing`: integration-testing.rst
|
||||||
|
.. _`Tests/README.rst`: ../../Tests/README.rst
|
||||||
|
|
||||||
|
Running Tests in the Build Tree
|
||||||
|
===============================
|
||||||
|
|
||||||
|
After `Building CMake`_, one may run the test suite in the build tree
|
||||||
|
using `ctest(1)`_:
|
||||||
|
|
||||||
|
* With a single-configuration CMake generator, such as ``Ninja``
|
||||||
|
or ``Unix Makefiles``, one may simply run ``ctest``:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ ctest
|
||||||
|
|
||||||
|
* With a multi-configuration CMake generator, such as
|
||||||
|
``Ninja Multi-Config``, ``Visual Studio``, or ``Xcode``,
|
||||||
|
one must tell ``ctest`` which configuration to test
|
||||||
|
by passing the ``-C <config>`` option:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ ctest -C Debug
|
||||||
|
|
||||||
|
Some useful `ctest(1)`_ options include:
|
||||||
|
|
||||||
|
``-N``
|
||||||
|
List test names without running them.
|
||||||
|
|
||||||
|
``-V``
|
||||||
|
Show verbose output from each test.
|
||||||
|
|
||||||
|
``-j <N>``
|
||||||
|
Run to run up to ``N`` tests concurrently.
|
||||||
|
|
||||||
CMake Dashboard Scripts
|
``-R <regex>``
|
||||||
=======================
|
Select tests for which the regular expression matches a substring
|
||||||
|
of their name.
|
||||||
|
|
||||||
The *integration testing* step of the `CMake Review Process`_ uses a set of
|
Cleaning Test Build Trees
|
||||||
testing machines that follow an integration branch on their own schedule to
|
-------------------------
|
||||||
drive testing and submit results to the `CMake CDash Page`_. Anyone is
|
|
||||||
welcome to provide testing machines in order to help keep support for their
|
|
||||||
platforms working.
|
|
||||||
|
|
||||||
The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
|
Many CMake tests create their own test project build trees underneath
|
||||||
nightly, continuous, and experimental testing of CMake. Use the following
|
the ``Tests/`` directory at the top of the CMake build tree. These
|
||||||
commands to set up a new integration testing client:
|
build trees are left behind after testing completes in order to
|
||||||
|
facilitate manual investigation of results. Many of the tests do *not*
|
||||||
|
clean their build trees if they are run again, with the exception of
|
||||||
|
tests using the `RunCMake`_ infrastructure.
|
||||||
|
|
||||||
|
In order to clear test build trees, drive the ``test_clean`` custom target
|
||||||
|
in the CMake build tree:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ cmake --build . --target test_clean
|
||||||
|
|
||||||
|
This removes the ``Tests/`` subdirectories created by individual tests
|
||||||
|
so they will use a fresh directory next time they run.
|
||||||
|
|
||||||
|
.. _`Building CMake`: ../../README.rst#building-cmake
|
||||||
|
.. _`ctest(1)`: https://cmake.org/cmake/help/latest/manual/ctest.1.html
|
||||||
|
.. _`RunCMake`: ../../Tests/RunCMake/README.rst
|
||||||
|
|
||||||
|
Running Tests with a Different Generator
|
||||||
|
========================================
|
||||||
|
|
||||||
|
After `Building CMake`_ with one CMake generator, one may configure the
|
||||||
|
test suite using a different generator in a separate build tree, without
|
||||||
|
building CMake itself again, by defining ``CMake_TEST_EXTERNAL_CMAKE``
|
||||||
|
to be the absolute path to the ``bin`` directory containing the ``cmake``,
|
||||||
|
``ctest``, and ``cpack`` executables.
|
||||||
|
|
||||||
|
For example, after building CMake with the ``Ninja`` generator:
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
$ mkdir -p ~/Dashboards
|
$ cmake -B build-ninja -G Ninja -DCMAKE_BUILD_TYPE=Debug
|
||||||
$ cd ~/Dashboards
|
$ cmake --build build-ninja
|
||||||
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
|
|
||||||
$ cd CMakeScripts
|
|
||||||
|
|
||||||
The `cmake_common.cmake`_ script contains comments at the top with
|
one may configure a second build tree to drive tests with the
|
||||||
instructions to set up a testing client. As it instructs, create a
|
``Ninja Multi-Config`` generator:
|
||||||
CTest script with local settings and include ``cmake_common.cmake``.
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
.. _`CMake Review Process`: review.rst
|
$ cmake -B build-nmc-tests -G "Ninja Multi-Config" \
|
||||||
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
|
-DCMake_TEST_EXTERNAL_CMAKE="$PWD/build-ninja/bin"
|
||||||
.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
|
$ cmake --build build-nmc-tests --config Release
|
||||||
.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake
|
|
||||||
|
The second build tree does not build CMake itself, but does configure
|
||||||
|
the test suite and build test binaries. One may then run tests normally:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
Nightly Start Time
|
$ cd build-nmc-tests
|
||||||
------------------
|
$ ctest -C Release
|
||||||
|
|
||||||
The ``cmake_common.cmake`` script expects its includer to be run from a
|
Note that the configuration with which one drives tests in the second
|
||||||
nightly scheduled task (cron job). Schedule such tasks for sometime after
|
build tree is independent of the configuration with which CMake was
|
||||||
``1:00am UTC``, the time at which our nightly testing branches fast-forward.
|
built in the first.
|
||||||
|
|||||||
@ -1,6 +0,0 @@
|
|||||||
try_compile-linker-language
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
* The :command:`try_compile` and :command:`try_run` commands gained a
|
|
||||||
``LINKER_LANGUAGE`` option to specify the :prop_tgt:`LINKER_LANGUAGE`
|
|
||||||
target property in the generated test project.
|
|
||||||
@ -0,0 +1,18 @@
|
|||||||
|
CMAKE_CONFIG_DIR
|
||||||
|
----------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
.. include:: ENV_VAR.txt
|
||||||
|
|
||||||
|
Specify a CMake user-wide configuration directory for
|
||||||
|
:manual:`cmake-file-api(7)` queries.
|
||||||
|
|
||||||
|
If this environment variable is not set, the default user-wide
|
||||||
|
configuration directory is platform-specific:
|
||||||
|
|
||||||
|
- Windows: ``%LOCALAPPDATA%\CMake``
|
||||||
|
- macOS: ``$XDG_CONFIG_HOME/CMake`` if set, otherwise
|
||||||
|
``$HOME/Library/Application Support/CMake``
|
||||||
|
- Linux/Other: ``$XDG_CONFIG_HOME/cmake`` if set, otherwise
|
||||||
|
``$HOME/.config/cmake``
|
||||||
@ -0,0 +1,17 @@
|
|||||||
|
CMAKE_EXPORT_BUILD_DATABASE
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
.. include:: ENV_VAR.txt
|
||||||
|
|
||||||
|
The default value for :variable:`CMAKE_EXPORT_BUILD_DATABASE` when there is no
|
||||||
|
explicit configuration given on the first run while creating a new build tree.
|
||||||
|
On later runs in an existing build tree the value persists in the cache as
|
||||||
|
:variable:`CMAKE_EXPORT_BUILD_DATABASE`.
|
||||||
|
|
||||||
|
.. note ::
|
||||||
|
|
||||||
|
This variable is meaningful only when experimental support for build
|
||||||
|
databases has been enabled by the
|
||||||
|
``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.
|
||||||
@ -0,0 +1,11 @@
|
|||||||
|
CMAKE_INSTALL_PARALLEL_LEVEL
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
.. include:: ENV_VAR.txt
|
||||||
|
|
||||||
|
Specifies the default maximum number of concurrent processes to use when
|
||||||
|
installing using ``cmake --install``.
|
||||||
|
|
||||||
|
This has no impact unless :prop_gbl:`INSTALL_PARALLEL` is enabled.
|
||||||
@ -1,57 +1,8 @@
|
|||||||
Visual Studio 12 2013
|
Visual Studio 12 2013
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
Deprecated. Generates Visual Studio 12 (VS 2013) project files.
|
Removed. This once generated Visual Studio 12 2013 project files, but
|
||||||
|
the generator has been removed since CMake 3.31. It is still possible
|
||||||
.. note::
|
to build with VS 12 2013 tools using the :generator:`Visual Studio 14 2015`
|
||||||
This generator is deprecated and will be removed in a future version
|
(or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``,
|
||||||
of CMake. It will still be possible to build with VS 12 2013 tools
|
or by using the :generator:`NMake Makefiles` generator.
|
||||||
using the :generator:`Visual Studio 14 2015` (or above) generator
|
|
||||||
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``, or by
|
|
||||||
using the :generator:`NMake Makefiles` generator.
|
|
||||||
|
|
||||||
For compatibility with CMake versions prior to 3.0, one may specify this
|
|
||||||
generator using the name "Visual Studio 12" without the year component.
|
|
||||||
|
|
||||||
Project Types
|
|
||||||
^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Only Visual C++ and C# projects may be generated (and Fortran with
|
|
||||||
Intel compiler integration). Other types of projects (JavaScript,
|
|
||||||
Powershell, Python, etc.) are not supported.
|
|
||||||
|
|
||||||
Platform Selection
|
|
||||||
^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The default target platform name (architecture) is ``Win32``.
|
|
||||||
|
|
||||||
.. versionadded:: 3.1
|
|
||||||
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
|
|
||||||
via the :option:`cmake -A` option, to specify a target platform
|
|
||||||
name (architecture). For example:
|
|
||||||
|
|
||||||
* ``cmake -G "Visual Studio 12 2013" -A Win32``
|
|
||||||
* ``cmake -G "Visual Studio 12 2013" -A x64``
|
|
||||||
* ``cmake -G "Visual Studio 12 2013" -A ARM``
|
|
||||||
|
|
||||||
For compatibility with CMake versions prior to 3.1, one may specify
|
|
||||||
a target platform name optionally at the end of the generator name.
|
|
||||||
This is supported only for:
|
|
||||||
|
|
||||||
``Visual Studio 12 2013 Win64``
|
|
||||||
Specify target platform ``x64``.
|
|
||||||
|
|
||||||
``Visual Studio 12 2013 ARM``
|
|
||||||
Specify target platform ``ARM``.
|
|
||||||
|
|
||||||
Toolset Selection
|
|
||||||
^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by
|
|
||||||
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
|
|
||||||
via the :option:`cmake -T` option, to specify another toolset.
|
|
||||||
|
|
||||||
.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
|
|
||||||
By default this generator uses the 32-bit variant even on a 64-bit host.
|
|
||||||
|
|
||||||
.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt
|
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,5 @@
|
|||||||
|
``CMAKE_REQUIRED_LINK_DIRECTORIES``
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
A :ref:`;-list <CMake Language Lists>` of libraries search paths to pass to
|
||||||
|
the linker (see :command:`try_compile` for further details).
|
||||||
@ -0,0 +1,26 @@
|
|||||||
|
CMP0171
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
``codegen`` is a reserved target name.
|
||||||
|
|
||||||
|
CMake 3.30 and earlier did not reserve ``codegen`` as a builtin target name,
|
||||||
|
leaving projects free to create their own target with that name.
|
||||||
|
CMake 3.31 and later prefer to reserve ``codegen`` as a builtin target name
|
||||||
|
to drive custom commands created with the ``CODEGEN`` option to
|
||||||
|
:command:`add_custom_command`. In order to support building the ``codegen``
|
||||||
|
target in scripted environments, e.g., ``cmake --build . --target codegen``,
|
||||||
|
the ``codegen`` target needs to be generated even if no custom commands
|
||||||
|
use the ``CODEGEN`` option. This policy provides compatibility for projects
|
||||||
|
that have not been updated to avoid creating a target named ``codegen``.
|
||||||
|
|
||||||
|
The ``OLD`` behavior of this policy allows projects to create a target
|
||||||
|
with the name ``codegen``. The ``NEW`` behavior halts with a fatal error
|
||||||
|
if a target with the name ``codegen`` is created.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,39 @@
|
|||||||
|
CMP0172
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
The :module:`CPack` module enables per-machine installation by default
|
||||||
|
in the :cpack_gen:`CPack WIX Generator`.
|
||||||
|
|
||||||
|
The :cpack_gen:`CPack WIX Generator`'s :variable:`CPACK_WIX_INSTALL_SCOPE`
|
||||||
|
option controls the scope of the generated Windows Installer package.
|
||||||
|
When :variable:`CPACK_WIX_VERSION` is set to 4 or higher, the default scope
|
||||||
|
is ``perMachine``. However, when using WIX 3 the default scope is ``NONE``,
|
||||||
|
and CPack does not set any ``InstallScope`` in the package specification.
|
||||||
|
The resulting installer requires administrative privileges and installs
|
||||||
|
into the system-wide ``ProgramFiles`` directory, but the start menu entry
|
||||||
|
and uninstaller registration are created only for the current user.
|
||||||
|
|
||||||
|
The :module:`CPack` module in CMake 3.30 and older does not specify any
|
||||||
|
:variable:`CPACK_WIX_INSTALL_SCOPE` value by default, so CPack uses no
|
||||||
|
installation scope by default with WIX 3. CMake 3.31 and newer instead
|
||||||
|
prefer to set :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perMachine`` by
|
||||||
|
default to make the behavior consistent across all WIX versions. This
|
||||||
|
policy provides compatibility for projects that have not been updated
|
||||||
|
to expect ``perMachine`` behavior.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to not set
|
||||||
|
:variable:`CPACK_WIX_INSTALL_SCOPE` by default. The ``NEW`` behavior for
|
||||||
|
this policy is to set :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perMachine``
|
||||||
|
by default.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
See documentation of the
|
||||||
|
:variable:`CMAKE_POLICY_WARNING_CMP0172 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
|
||||||
|
variable to control the warning.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,22 @@
|
|||||||
|
CMP0173
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
The :module:`CMakeFindFrameworks` module is removed.
|
||||||
|
|
||||||
|
CMake's framework handling has evolved well beyond what the
|
||||||
|
``CMakeFindFrameworks`` module supports. The module lacks any handling of
|
||||||
|
XCFrameworks, it never documented the one command it provides, and
|
||||||
|
:command:`find_library` provides superior capabilities in all respects.
|
||||||
|
|
||||||
|
The ``OLD`` behavior of this policy is for :module:`CMakeFindFrameworks` to
|
||||||
|
continue to provide the undocumented ``cmake_find_frameworks()`` command.
|
||||||
|
The ``NEW`` behavior halts with a fatal error if anything tries to include
|
||||||
|
the module.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,37 @@
|
|||||||
|
CMP0174
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
:command:`cmake_parse_arguments(PARSE_ARGV)` defines a variable for an empty
|
||||||
|
string after a single-value keyword.
|
||||||
|
|
||||||
|
One of the main reasons for using the ``PARSE_ARGV`` form of the
|
||||||
|
:command:`cmake_parse_arguments` command is to more robustly handle corner
|
||||||
|
cases related to empty values. The non-``PARSE_ARGV`` form doesn't preserve
|
||||||
|
empty arguments, but the ``PARSE_ARGV`` form does. For each single-value
|
||||||
|
keyword given, a variable should be defined if the keyword is present, even
|
||||||
|
if it is followed by an empty string.
|
||||||
|
|
||||||
|
Prior to CMake 3.31, no variable would be defined if the value given after a
|
||||||
|
single-value keyword was an empty string. This meant the code could not detect
|
||||||
|
the difference between the keyword not being given, and it being given but with
|
||||||
|
an empty value, except by iterating over all the arguments and checking if the
|
||||||
|
keyword is present.
|
||||||
|
|
||||||
|
For the ``OLD`` behavior of this policy,
|
||||||
|
:command:`cmake_parse_arguments(PARSE_ARGV)` does not define a variable for a
|
||||||
|
single-value keyword followed by an empty string, or followed by no value at
|
||||||
|
all.
|
||||||
|
|
||||||
|
For the ``NEW`` behavior, :command:`cmake_parse_arguments(PARSE_ARGV)` always
|
||||||
|
defines a variable for each keyword given in the arguments, even a single-value
|
||||||
|
keyword with an empty string as its value or no value at all. With the
|
||||||
|
``NEW`` behavior, the code can robustly check if a single-value keyword was
|
||||||
|
given using just ``if(DEFINED <prefix>_<keyword>)``.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,40 @@
|
|||||||
|
CMP0175
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
:command:`add_custom_command` rejects invalid arguments.
|
||||||
|
|
||||||
|
CMake 3.30 and earlier silently ignored unsupported keywords and missing or
|
||||||
|
invalid arguments for the different forms of the :command:`add_custom_command`
|
||||||
|
command. CMake 3.31 implements more rigorous argument checking and will flag
|
||||||
|
invalid or missing arguments as errors.
|
||||||
|
|
||||||
|
The ``OLD`` behavior of this policy will accept the same invalid keywords or
|
||||||
|
arguments as CMake 3.30 and earlier. The ``NEW`` behavior will flag the
|
||||||
|
following as errors that previously went unreported:
|
||||||
|
|
||||||
|
* The ``OUTPUT`` form does not accept ``PRE_BUILD``, ``PRE_LINK``, or
|
||||||
|
``POST_BUILD`` keywords.
|
||||||
|
* When the ``APPEND`` keyword is given, the ``OUTPUT`` form also does not
|
||||||
|
accept ``BYPRODUCTS``, ``COMMAND_EXPAND_LISTS``, ``DEPENDS_EXPLICIT_ONLY``,
|
||||||
|
``DEPFILE``, ``JOB_POOL``, ``JOB_SERVER_AWARE``, ``USES_TERMINAL``, or
|
||||||
|
``VERBATIM`` keywords.
|
||||||
|
* The ``TARGET`` form requires exactly one of ``PRE_BUILD``, ``PRE_LINK``, or
|
||||||
|
``POST_BUILD`` to be given. Previously, if none were given, ``POST_BUILD``
|
||||||
|
was assumed, or if multiple keywords were given, the last one was used.
|
||||||
|
* The ``TARGET`` form does not accept ``DEPENDS``, ``DEPENDS_EXPLICIT_ONLY``,
|
||||||
|
``DEPFILE``, ``IMPLICIT_DEPENDS``, ``MAIN_DEPENDENCY``, ``JOB_POOL``,
|
||||||
|
``JOB_SERVER_AWARE``, or ``USES_TERMINAL`` keywords.
|
||||||
|
* The ``TARGET`` form now requires at least one ``COMMAND`` to be given.
|
||||||
|
* If a keyword expects a value to be given after it, but no value is provided,
|
||||||
|
that was previously treated as though the keyword was not given at all.
|
||||||
|
* The ``COMMENT`` keyword expects exactly one value after it. If multiple
|
||||||
|
values are given, or if the ``COMMENT`` keyword is given more than once,
|
||||||
|
this is an error.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,27 @@
|
|||||||
|
CMP0176
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
:command:`execute_process` ``ENCODING`` is ``UTF-8`` by default.
|
||||||
|
|
||||||
|
The ``ENCODING`` option is meaningful only on Windows. It specifies the
|
||||||
|
character encoding expected in the process's output on stdout and stderr.
|
||||||
|
In CMake 3.14 and below the default encoding was ``NONE``, which corresponds
|
||||||
|
to CMake's internal UTF-8 encoding. In CMake 3.15 through CMake 3.30 the
|
||||||
|
default encoding was accidentally changed to ``AUTO``, but the change went
|
||||||
|
unnoticed and was not documented.
|
||||||
|
|
||||||
|
CMake 3.31 and above prefer the ``ENCODING`` default to be ``UTF-8``.
|
||||||
|
This policy provides compatibility with projects that may have been
|
||||||
|
relying on the default being ``AUTO``.
|
||||||
|
|
||||||
|
The ``OLD`` behavior of this policy is for :command:`execute_process`
|
||||||
|
to use ``AUTO`` by default if no ``ENCODING`` is specified. The ``NEW``
|
||||||
|
behavior for this policy is to use ``UTF-8`` as the default ``ENCODING``.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,38 @@
|
|||||||
|
CMP0177
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
:command:`install` ``DESTINATION`` paths are normalized.
|
||||||
|
|
||||||
|
The :command:`install` command has a number of different forms, and most of
|
||||||
|
them take a ``DESTINATION`` keyword, some in more than one place.
|
||||||
|
CMake 3.30 and earlier used the value given after the ``DESTINATION`` keyword
|
||||||
|
as provided with no transformations. The :command:`install(EXPORT)` form
|
||||||
|
assumes the path contains no ``..`` or ``.`` path components when computing
|
||||||
|
a path relative to the ``DESTINATION``, and if the project provided a path
|
||||||
|
that violated that assumption, the computed path would be incorrect.
|
||||||
|
|
||||||
|
CMake 3.31 normalizes all ``DESTINATION`` values given in any form of the
|
||||||
|
:command:`install` command, except for the ``INCLUDES DESTINATION`` of the
|
||||||
|
:command:`install(TARGETS)` form. The normalization performed is the same
|
||||||
|
as for the :command:`cmake_path` command (see :ref:`Normalization`).
|
||||||
|
|
||||||
|
The ``OLD`` behavior of this policy performs no translation on the
|
||||||
|
``DESTINATION`` values of any :command:`install` command. They are used
|
||||||
|
exactly as provided. If a destination path contains ``..`` or ``.`` path
|
||||||
|
components, :command:`install(EXPORT)` will use the same wrong paths as
|
||||||
|
CMake 3.30 and earlier.
|
||||||
|
|
||||||
|
The ``NEW`` behavior will normalize all ``DESTINATION`` values except for
|
||||||
|
``INCLUDES DESTINATION``. If a destination path contains a generator
|
||||||
|
expression, it will be wrapped in a ``$<PATH:CMAKE_PATH,NORMALIZE,...>``
|
||||||
|
generator expression.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.31.
|
||||||
|
It may be set by :command:`cmake_policy` or :command:`cmake_minimum_required`.
|
||||||
|
If it is not set, CMake will warn if it detects a path that would be different
|
||||||
|
if normalized, and uses ``OLD`` behavior. If a destination path contains a
|
||||||
|
generator expression, no such warning will be issued regardless of the value.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,37 @@
|
|||||||
|
CMP0178
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
Test command lines preserve empty arguments.
|
||||||
|
|
||||||
|
Empty values in the :prop_tgt:`TEST_LAUNCHER` and
|
||||||
|
:prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved
|
||||||
|
for tests added by the following:
|
||||||
|
|
||||||
|
* The :command:`add_test` command.
|
||||||
|
* The :command:`ExternalData_Add_Test` command from the :module:`ExternalData`
|
||||||
|
module.
|
||||||
|
* The :command:`gtest_add_tests` or :command:`gtest_discover_tests` commands
|
||||||
|
from the :module:`GoogleTest` module.
|
||||||
|
|
||||||
|
For the :command:`gtest_add_tests` and :command:`gtest_discover_tests`
|
||||||
|
commands, empty elements in the values passed after the ``EXTRA_ARGS``
|
||||||
|
keyword are also now preserved.
|
||||||
|
|
||||||
|
The ``OLD`` behavior of this policy silently discards empty list items
|
||||||
|
from the :prop_tgt:`TEST_LAUNCHER` and :prop_tgt:`CROSSCOMPILING_EMULATOR`
|
||||||
|
target properties in the above-mentioned cases. It also silently discards
|
||||||
|
empty items from the values given after ``EXTRA_ARGS`` for the
|
||||||
|
:command:`gtest_add_tests` and :command:`gtest_discover_tests` commands.
|
||||||
|
|
||||||
|
The ``NEW`` behavior of this policy preserves empty list items in the
|
||||||
|
:prop_tgt:`TEST_LAUNCHER` and :prop_tgt:`CROSSCOMPILING_EMULATOR` target
|
||||||
|
properties, and in values given after ``EXTRA_ARGS`` for
|
||||||
|
:command:`gtest_add_tests` and :command:`gtest_discover_tests`.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,28 @@
|
|||||||
|
CMP0179
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
De-duplication of static libraries on link lines keeps first occurrence.
|
||||||
|
This policy is only relevant when policy :policy:`CMP0156` is set to ``NEW``.
|
||||||
|
|
||||||
|
Based on the linker capabilities, the static libraries can
|
||||||
|
be de-duplicated. See policy :policy:`CMP0156` for more information.
|
||||||
|
|
||||||
|
CMake 3.30 and below may choose to keep, on some platforms, the last occurrence
|
||||||
|
of the static libraries rather than the fist occurrence when they are
|
||||||
|
de-duplicated.
|
||||||
|
|
||||||
|
CMake 3.31 and above prefer to keep, on all platforms, the first occurrence of
|
||||||
|
the static libraries when they are de-duplicated.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to keep, on some platforms, the last
|
||||||
|
occurrence of the static libraries when they are de-duplicated. The ``NEW``
|
||||||
|
behavior for this policy is to keep the first occurrence of the static
|
||||||
|
libraries when they are de-duplicated, regardless of the platform.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,36 @@
|
|||||||
|
CMP0180
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
:command:`project` always sets ``<PROJECT-NAME>_*`` as normal variables.
|
||||||
|
|
||||||
|
In CMake 3.29 and below, the :command:`project` command set
|
||||||
|
:variable:`<PROJECT-NAME>_SOURCE_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`,
|
||||||
|
and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` as cache entries, but not as
|
||||||
|
normal variables. CMake 3.30 started setting them as normal variables,
|
||||||
|
but only if they are already set as normal variables. This was needed to
|
||||||
|
preserve support for some :module:`FetchContent` use cases under policy
|
||||||
|
:policy:`CMP0169`'s NEW behavior, while also preserving behavior of nested
|
||||||
|
directories that call :command:`project` with the same project name.
|
||||||
|
See release notes for 3.30.3, 3.30.4, and 3.30.5 for details.
|
||||||
|
|
||||||
|
CMake 3.31 and later prefer to always set ``<PROJECT-NAME>_SOURCE_DIR``,
|
||||||
|
``<PROJECT-NAME>_BINARY_DIR``, and ``<PROJECT-NAME>_IS_TOP_LEVEL``, as both
|
||||||
|
cache entries and normal variables, regardless of what cache or normal
|
||||||
|
variables already exist. This policy provides compatibility for projects
|
||||||
|
that have not been updated to expect this behavior.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy will only set normal variables for
|
||||||
|
``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
|
||||||
|
``<PROJECT-NAME>_IS_TOP_LEVEL`` if there is already a normal variable by that
|
||||||
|
name when :command:`project` is called.
|
||||||
|
The ``NEW`` behavior for this policy will always set normal variables for
|
||||||
|
``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
|
||||||
|
``<PROJECT-NAME>_IS_TOP_LEVEL`` when :command:`project` is called.
|
||||||
|
|
||||||
|
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
|
||||||
|
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
|
||||||
|
.. include:: STANDARD_ADVICE.txt
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,20 @@
|
|||||||
|
AIX_SHARED_LIBRARY_ARCHIVE
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
On AIX, enable creation of a shared library archive. This places
|
||||||
|
the shared object ``.so`` file inside an archive ``.a`` file.
|
||||||
|
|
||||||
|
By default, CMake creates shared libraries on AIX as plain
|
||||||
|
shared object ``.so`` files for consistency with other UNIX platforms.
|
||||||
|
Alternatively, set this property to a true value to create a shared
|
||||||
|
library archive instead, as is AIX convention.
|
||||||
|
|
||||||
|
The shared object name in the archive encodes version information from
|
||||||
|
the :prop_tgt:`SOVERSION` target property, if set, and otherwise from
|
||||||
|
the :prop_tgt:`VERSION` target property, if set.
|
||||||
|
|
||||||
|
This property defaults to :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE`
|
||||||
|
if that variable is set when a ``SHARED`` library target is created
|
||||||
|
by :command:`add_library`.
|
||||||
@ -0,0 +1,15 @@
|
|||||||
|
EXPORT_BUILD_DATABASE
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
Enable/Disable output of a build database for a target.
|
||||||
|
|
||||||
|
This property is initialized by the value of the variable
|
||||||
|
:variable:`CMAKE_EXPORT_BUILD_DATABASE` if it is set when a target is created.
|
||||||
|
|
||||||
|
.. note ::
|
||||||
|
|
||||||
|
This property is meaningful only when experimental support for build
|
||||||
|
databases has been enabled by the
|
||||||
|
``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.
|
||||||
@ -0,0 +1,87 @@
|
|||||||
|
LINK_LIBRARIES_STRATEGY
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
Specify a strategy for ordering a target's direct link dependencies
|
||||||
|
on linker command lines. This property is initialized by the value of the
|
||||||
|
:variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable if it is set when a
|
||||||
|
target is created.
|
||||||
|
|
||||||
|
CMake generates a target's link line using its :ref:`Target Link Properties`.
|
||||||
|
In particular, the :prop_tgt:`LINK_LIBRARIES` target property records the
|
||||||
|
target's direct link dependencies, typically populated by calls to
|
||||||
|
:command:`target_link_libraries`. Indirect link dependencies are
|
||||||
|
propagated from those entries of :prop_tgt:`LINK_LIBRARIES` that name
|
||||||
|
library targets by following the transitive closure of their
|
||||||
|
:prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. CMake supports multiple
|
||||||
|
strategies for nominally ordering direct and indirect link dependencies,
|
||||||
|
which are then filtered for `Toolchain-Specific Behavior`_.
|
||||||
|
|
||||||
|
Consider this example for the strategies below:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_library(A STATIC ...)
|
||||||
|
add_library(B STATIC ...)
|
||||||
|
add_library(C STATIC ...)
|
||||||
|
add_executable(main ...)
|
||||||
|
target_link_libraries(B PRIVATE A)
|
||||||
|
target_link_libraries(C PRIVATE A)
|
||||||
|
target_link_libraries(main PRIVATE A B C)
|
||||||
|
|
||||||
|
The supported strategies are:
|
||||||
|
|
||||||
|
``REORDER_MINIMALLY``
|
||||||
|
Entries of :prop_tgt:`LINK_LIBRARIES` always appear first and in their
|
||||||
|
original order. Indirect link dependencies not satisfied by the
|
||||||
|
original entries may be reordered and de-duplicated with respect to
|
||||||
|
one another, but are always appended after the original entries.
|
||||||
|
This may result in less efficient link lines, but gives projects
|
||||||
|
control of ordering among independent entries. Such control may be
|
||||||
|
important when intermixing link flags with libraries, or when multiple
|
||||||
|
libraries provide a given symbol.
|
||||||
|
|
||||||
|
This is the default.
|
||||||
|
|
||||||
|
In the above example, this strategy computes a link line for ``main``
|
||||||
|
by starting with its original entries ``A B C``, and then appends
|
||||||
|
another ``A`` to satisfy the dependencies of ``B`` and ``C`` on ``A``.
|
||||||
|
The nominal order produced by this strategy is ``A B C A``.
|
||||||
|
|
||||||
|
Note that additional filtering for `Toolchain-Specific Behavior`_
|
||||||
|
may de-duplicate ``A`` on the actual linker invocation in the
|
||||||
|
generated build system, resulting in either ``A B C`` or ``B C A``.
|
||||||
|
|
||||||
|
``REORDER_FREELY``
|
||||||
|
Entries of :prop_tgt:`LINK_LIBRARIES` may be reordered, de-duplicated,
|
||||||
|
and intermixed with indirect link dependencies. This may result in
|
||||||
|
more efficient link lines, but does not give projects any control of
|
||||||
|
ordering among independent entries.
|
||||||
|
|
||||||
|
In the above example, this strategy computes a link line for ``main``
|
||||||
|
by re-ordering its original entries ``A B C`` to satisfy the
|
||||||
|
dependencies of ``B`` and ``C`` on ``A``.
|
||||||
|
The nominal order produced by this strategy is ``B C A``.
|
||||||
|
|
||||||
|
Toolchain-Specific Behavior
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
After one of the above strategies produces a nominal order among
|
||||||
|
direct and indirect link dependencies, the actual linker invocation
|
||||||
|
in the generated build system may de-duplicate entries based on
|
||||||
|
platform-specific requirements and linker capabilities.
|
||||||
|
See policy :policy:`CMP0156`.
|
||||||
|
|
||||||
|
For example, if the ``REORDER_MINIMALLY`` strategy produces ``A B C A``,
|
||||||
|
the actual link line may de-duplicate ``A`` as follows:
|
||||||
|
|
||||||
|
* If ``A`` is a static library and the linker re-scans automatically,
|
||||||
|
the first occurrence is kept, resulting in ``A B C``.
|
||||||
|
See policy :policy:`CMP0179`
|
||||||
|
|
||||||
|
* If ``A`` is a shared library on Windows, the first
|
||||||
|
occurrence is kept, resulting in ``A B C``.
|
||||||
|
|
||||||
|
* If ``A`` is a shared library on macOS or UNIX platforms, the last
|
||||||
|
occurrence is kept, resulting in ``B C A``.
|
||||||
@ -0,0 +1,12 @@
|
|||||||
|
VS_FRAMEWORK_REFERENCES
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
Visual Studio framework references.
|
||||||
|
Specify a :ref:`semicolon-separated list <CMake Language Lists>` of framework references
|
||||||
|
to be added to a generated Visual Studio project. For example:
|
||||||
|
|
||||||
|
* "Microsoft.WindowsDesktop.App.WPF" for WPF applications
|
||||||
|
* "Microsoft.WindowsDesktop.App.WindowsForms" for WinForms applications
|
||||||
|
* "Microsoft.WindowsDesktop.App" for applications using both frameworks
|
||||||
@ -0,0 +1,259 @@
|
|||||||
|
CMake 3.31 Release Notes
|
||||||
|
************************
|
||||||
|
|
||||||
|
.. only:: html
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Changes made since CMake 3.30 include the following.
|
||||||
|
|
||||||
|
New Features
|
||||||
|
============
|
||||||
|
|
||||||
|
Presets
|
||||||
|
-------
|
||||||
|
|
||||||
|
* :manual:`cmake-presets(7)` files may now include comments using the key
|
||||||
|
``$comment`` at any level within the JSON object to provide documentation.
|
||||||
|
|
||||||
|
* :manual:`cmake-presets(7)` files may now request graphviz output using
|
||||||
|
the ``graphviz`` key in a configure preset.
|
||||||
|
|
||||||
|
Generators
|
||||||
|
----------
|
||||||
|
|
||||||
|
* The :ref:`Ninja Generators` and :ref:`Makefile Generators` now produce
|
||||||
|
a ``codegen`` build target. See policy :policy:`CMP0171`. It drives a
|
||||||
|
subset of the build graph sufficient to run custom commands created with
|
||||||
|
:command:`add_custom_command`'s new ``CODEGEN`` option.
|
||||||
|
|
||||||
|
Command-Line
|
||||||
|
------------
|
||||||
|
|
||||||
|
* The :option:`cmake --workflow` mode now accepts a preset name as the first
|
||||||
|
argument, allowing the simpler command line
|
||||||
|
:option:`cmake --workflow \<preset\> <cmake--workflow --preset>`.
|
||||||
|
|
||||||
|
* The :option:`cmake -LR[A][H]` option was added to list cache entries
|
||||||
|
whose names match a regular expression.
|
||||||
|
|
||||||
|
Compilers
|
||||||
|
---------
|
||||||
|
|
||||||
|
* The LFortran compiler is now supported with
|
||||||
|
:variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``LFortran``.
|
||||||
|
|
||||||
|
Commands
|
||||||
|
--------
|
||||||
|
|
||||||
|
* The :command:`add_custom_command` command gained a ``CODEGEN`` option
|
||||||
|
to mark a custom command's outputs as dependencies of a ``codegen`` target.
|
||||||
|
See policy :policy:`CMP0171`.
|
||||||
|
|
||||||
|
* The :command:`cmake_pkg_config` command was added as an endpoint for using
|
||||||
|
CMake's native pkg-config format parser. The only supported option in this
|
||||||
|
release is ``EXTRACT``, which provides low-level access to the values
|
||||||
|
produced by parsing a pkg-config file. For most users, this is not yet a
|
||||||
|
suitable replacement for the :module:`FindPkgConfig` module.
|
||||||
|
|
||||||
|
* The :command:`file(ARCHIVE_CREATE)` command gained a ``WORKING_DIRECTORY``
|
||||||
|
option to specify a working directory for the archiving process.
|
||||||
|
|
||||||
|
* The :command:`file(MAKE_DIRECTORY)` command gained a ``RESULT`` option
|
||||||
|
to capture failure in a result variable.
|
||||||
|
|
||||||
|
* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands'
|
||||||
|
``TYPE`` argument gained support for a ``LIBEXEC`` type.
|
||||||
|
|
||||||
|
Variables
|
||||||
|
---------
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE` variable and corresponding
|
||||||
|
:prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE` target property were added to
|
||||||
|
create shared libraries on AIX as shared library archives.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_EXPORT_BUILD_DATABASE` variable, a corresponding
|
||||||
|
:envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment variable, and an
|
||||||
|
:prop_tgt:`EXPORT_BUILD_DATABASE` target property, were added to
|
||||||
|
enable exporting C++ module compile commands.
|
||||||
|
This is only supported with :ref:`Ninja Generators`.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable was added to
|
||||||
|
provide the suffix for executable names on the host platform.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_<LANG>_HOST_COMPILER_ID` and
|
||||||
|
:variable:`CMAKE_<LANG>_HOST_COMPILER_VERSION` variables were added,
|
||||||
|
where ``<LANG>`` is either ``CUDA`` or ``HIP``. They are populated
|
||||||
|
when :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA`` to identify
|
||||||
|
NVCC's host compiler.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_<LANG>_STANDARD_LINK_DIRECTORIES` variable was added.
|
||||||
|
Toolchain files can set this variable to control which link library directory
|
||||||
|
paths are always passed to the compiler for the specified language.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
|
||||||
|
corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target
|
||||||
|
property were added to optionally specify the strategy
|
||||||
|
CMake uses to generate link lines.
|
||||||
|
|
||||||
|
Properties
|
||||||
|
----------
|
||||||
|
|
||||||
|
* The :prop_tgt:`MACOSX_FRAMEWORK_BUNDLE_NAME <MACOSX_FRAMEWORK_INFO_PLIST>`
|
||||||
|
target property was added to set the ``CFBundleName`` key in an Apple
|
||||||
|
:prop_tgt:`FRAMEWORK`'s ``Info.plist`` file.
|
||||||
|
|
||||||
|
* The :prop_tgt:`UNITY_BUILD` target property now supports the
|
||||||
|
``CUDA`` language.
|
||||||
|
|
||||||
|
* The :prop_tgt:`VS_FRAMEWORK_REFERENCES` target property was added
|
||||||
|
to tell :ref:`Visual Studio Generators` to add framework references.
|
||||||
|
|
||||||
|
Modules
|
||||||
|
-------
|
||||||
|
|
||||||
|
* Check modules now support a ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
|
||||||
|
The following modules gained this support:
|
||||||
|
|
||||||
|
* :module:`CMakePushCheckState`
|
||||||
|
* :module:`CheckCCompilerFlag`
|
||||||
|
* :module:`CheckCSourceCompiles`
|
||||||
|
* :module:`CheckCSourceRuns`
|
||||||
|
* :module:`CheckCXXCompilerFlag`
|
||||||
|
* :module:`CheckCXXSourceCompiles`
|
||||||
|
* :module:`CheckCXXSourceRuns`
|
||||||
|
* :module:`CheckCXXSymbolExists`
|
||||||
|
* :module:`CheckCompilerFlag`
|
||||||
|
* :module:`CheckFortranCompilerFlag`
|
||||||
|
* :module:`CheckFortranFunctionExists`
|
||||||
|
* :module:`CheckFortranSourceCompiles`
|
||||||
|
* :module:`CheckFortranSourceRuns`
|
||||||
|
* :module:`CheckFunctionExists`
|
||||||
|
* :module:`CheckIncludeFile`
|
||||||
|
* :module:`CheckIncludeFileCXX`
|
||||||
|
* :module:`CheckIncludeFiles`
|
||||||
|
* :module:`CheckOBJCCompilerFlag`
|
||||||
|
* :module:`CheckLibraryExists`
|
||||||
|
* :module:`CheckOBJCCompilerFlag`
|
||||||
|
* :module:`CheckOBJCSourceCompiles`
|
||||||
|
* :module:`CheckOBJCSourceRuns`
|
||||||
|
* :module:`CheckOBJCXXCompilerFlag`
|
||||||
|
* :module:`CheckOBJCXXSourceCompiles`
|
||||||
|
* :module:`CheckOBJCXXSourceRuns`
|
||||||
|
* :module:`CheckPrototypeDefinition`
|
||||||
|
* :module:`CheckSourceCompiles`
|
||||||
|
* :module:`CheckSourceRuns`
|
||||||
|
* :module:`CheckStructHasMember`
|
||||||
|
* :module:`CheckSymbolExists`
|
||||||
|
* :module:`CheckTypeSize`
|
||||||
|
* :module:`CheckVariableExists`
|
||||||
|
|
||||||
|
* The :module:`CMakePackageConfigHelpers` module's
|
||||||
|
:command:`generate_apple_platform_selection_file` function
|
||||||
|
gained support for iOS Mac Catalyst.
|
||||||
|
|
||||||
|
* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
|
||||||
|
gained a new ``DISCOVERY_EXTRA_ARGS`` keyword. It allows extra arguments
|
||||||
|
to be appended to the command line when querying for the list of tests.
|
||||||
|
|
||||||
|
* The :module:`FindCUDAToolkit` module now provides a ``CUDA::nvml_static``
|
||||||
|
target.
|
||||||
|
|
||||||
|
* The :module:`FindOpenMP` module gained support for the ``CUDA`` language.
|
||||||
|
|
||||||
|
CTest
|
||||||
|
-----
|
||||||
|
|
||||||
|
* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
|
||||||
|
step now verify TLS server certificates for connections to ``https://`` URLs
|
||||||
|
by default. See the :variable:`CTEST_TLS_VERIFY` variable for details.
|
||||||
|
|
||||||
|
* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
|
||||||
|
step now require TLS 1.2 or higher for connections to ``https://`` URLs by
|
||||||
|
default. See the :variable:`CTEST_TLS_VERSION` variable for details.
|
||||||
|
|
||||||
|
CPack
|
||||||
|
-----
|
||||||
|
|
||||||
|
* The :cpack_gen:`CPack DEB Generator` gained a
|
||||||
|
:variable:`CPACK_DEBIAN_PACKAGE_MULTIARCH` option
|
||||||
|
to support multi-arch packages.
|
||||||
|
|
||||||
|
* The :cpack_gen:`CPack IFW Generator` gained the new
|
||||||
|
:variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGE_URLS` variable to
|
||||||
|
specify images associated with entries of
|
||||||
|
:variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES`.
|
||||||
|
This feature is available for QtIFW 4.0 and newer.
|
||||||
|
|
||||||
|
* The :cpack_gen:`CPack RPM Generator` gained support for ``zstd`` as a
|
||||||
|
:variable:`CPACK_RPM_COMPRESSION_TYPE` value.
|
||||||
|
|
||||||
|
* The :module:`CPack` module enables per-machine installation by default
|
||||||
|
in the :cpack_gen:`CPack WIX Generator`. See policy :policy:`CMP0172`
|
||||||
|
and the :variable:`CPACK_WIX_INSTALL_SCOPE` variable.
|
||||||
|
|
||||||
|
Deprecated and Removed Features
|
||||||
|
===============================
|
||||||
|
|
||||||
|
* Compatibility with versions of CMake older than 3.10 is now deprecated
|
||||||
|
and will be removed from a future version. Calls to
|
||||||
|
:command:`cmake_minimum_required` or :command:`cmake_policy` that set
|
||||||
|
the policy version to an older value now issue a deprecation diagnostic.
|
||||||
|
|
||||||
|
* The :module:`CMakeFindFrameworks` module has been deprecated via
|
||||||
|
:policy:`CMP0173`. Projects should use :command:`find_library` instead.
|
||||||
|
|
||||||
|
* The :generator:`Visual Studio 12 2013` generator has been removed.
|
||||||
|
|
||||||
|
Other Changes
|
||||||
|
=============
|
||||||
|
|
||||||
|
* When static libraries on link lines are de-duplicated (by policy
|
||||||
|
:policy:`CMP0156`), the first occurrence is now kept on all platforms.
|
||||||
|
See policy :policy:`CMP0179`.
|
||||||
|
|
||||||
|
* Empty list elements in the :prop_tgt:`TEST_LAUNCHER` and
|
||||||
|
:prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved by:
|
||||||
|
|
||||||
|
* The :command:`add_test` command.
|
||||||
|
* The :command:`ExternalData_Add_Test` command from the
|
||||||
|
:module:`ExternalData` module.
|
||||||
|
* The :command:`gtest_add_tests` and :command:`gtest_discover_tests`
|
||||||
|
commands from the :module:`GoogleTest` module.
|
||||||
|
Empty list elements after the ``EXTRA_ARGS`` keyword of these
|
||||||
|
two commands are also now preserved.
|
||||||
|
|
||||||
|
See policy :policy:`CMP0178`.
|
||||||
|
|
||||||
|
* The :command:`execute_process` command's ``ENCODING`` option,
|
||||||
|
meaningful on Windows, now defaults to ``UTF-8``.
|
||||||
|
See policy :policy:`CMP0176`.
|
||||||
|
|
||||||
|
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
|
||||||
|
verify TLS server certificates for connections to ``https://`` URLs by
|
||||||
|
default. See the :variable:`CMAKE_TLS_VERIFY` variable for details.
|
||||||
|
This change was made without a policy so that users are protected
|
||||||
|
even when building projects that have not been updated.
|
||||||
|
Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
|
||||||
|
variable to ``0`` to restore the old default.
|
||||||
|
|
||||||
|
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
|
||||||
|
require TLS 1.2 or higher for connections to ``https://`` URLs by default.
|
||||||
|
See the :variable:`CMAKE_TLS_VERSION` variable for details.
|
||||||
|
|
||||||
|
* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command was updated
|
||||||
|
to more closely match the dynamic loader's behavior on Linux.
|
||||||
|
|
||||||
|
* The :command:`install` command's ``DESTINATION`` arguments are
|
||||||
|
now :ref:`normalized <Normalization>`, with the exception
|
||||||
|
of ``INCLUDES DESTINATION`` arguments in :command:`install(TARGETS)`.
|
||||||
|
See policy :policy:`CMP0177`.
|
||||||
|
|
||||||
|
* The :command:`project` command now always sets
|
||||||
|
:variable:`<PROJECT-NAME>_SOURCE_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`,
|
||||||
|
and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` as both normal variables and
|
||||||
|
cache entries. See policy :policy:`CMP0180`.
|
||||||
|
|
||||||
|
* The :command:`cmake_parse_arguments(PARSE_ARGV)` command now defines a
|
||||||
|
variable for an empty string after a single-value keyword. See policy
|
||||||
|
:policy:`CMP0174`.
|
||||||
@ -0,0 +1,10 @@
|
|||||||
|
CMAKE_AIX_SHARED_LIBRARY_ARCHIVE
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
On AIX, enable creation of shared library archives.
|
||||||
|
|
||||||
|
This variable initializes the :prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE`
|
||||||
|
target property on ``SHARED`` library targets as they are created
|
||||||
|
by :command:`add_library`. See that target property for details.
|
||||||
@ -1,10 +1,14 @@
|
|||||||
CMAKE_EXECUTABLE_SUFFIX
|
CMAKE_EXECUTABLE_SUFFIX
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
The suffix for executables on this platform.
|
The suffix for executables on the target platform.
|
||||||
|
|
||||||
The suffix to use for the end of an executable filename if any, ``.exe``
|
The suffix to use for the end of an executable filename if any, ``.exe``
|
||||||
on Windows.
|
on Windows.
|
||||||
|
|
||||||
:variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for
|
:variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for
|
||||||
language ``<LANG>``.
|
language ``<LANG>``.
|
||||||
|
|
||||||
|
|
||||||
|
See the :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable for the
|
||||||
|
executable suffix on the host platform.
|
||||||
|
|||||||
@ -0,0 +1,86 @@
|
|||||||
|
CMAKE_EXPORT_BUILD_DATABASE
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
.. note ::
|
||||||
|
|
||||||
|
This variable is meaningful only when experimental support for build
|
||||||
|
databases has been enabled by the
|
||||||
|
``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.
|
||||||
|
|
||||||
|
Enable/Disable output of module compile commands during the build.
|
||||||
|
|
||||||
|
If enabled, generates a ``build_database.json`` file containing the
|
||||||
|
information necessary to compile a target's C++ module sources with any
|
||||||
|
tooling. The format of the JSON file looks like:
|
||||||
|
|
||||||
|
.. code-block:: javascript
|
||||||
|
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"revision": 0,
|
||||||
|
"sets": [
|
||||||
|
{
|
||||||
|
"family-name" : "export_build_database",
|
||||||
|
"name" : "export_build_database@Debug",
|
||||||
|
"translation-units" : [
|
||||||
|
{
|
||||||
|
"arguments": [
|
||||||
|
"/path/to/compiler",
|
||||||
|
"...",
|
||||||
|
],
|
||||||
|
"baseline-arguments" :
|
||||||
|
[
|
||||||
|
"...",
|
||||||
|
],
|
||||||
|
"local-arguments" :
|
||||||
|
[
|
||||||
|
"...",
|
||||||
|
],
|
||||||
|
"object": "CMakeFiles/target.dir/source.cxx.o",
|
||||||
|
"private": true,
|
||||||
|
"provides": {
|
||||||
|
"importable": "path/to/bmi"
|
||||||
|
},
|
||||||
|
"requires" : [],
|
||||||
|
"source": "path/to/source.cxx",
|
||||||
|
"work-directory": "/path/to/working/directory"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"visible-sets" : []
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
This is initialized by the :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment
|
||||||
|
variable, and initializes the :prop_tgt:`EXPORT_BUILD_DATABASE` target
|
||||||
|
property for all targets.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
This option is implemented only by the :ref:`Ninja Generators`. It is
|
||||||
|
ignored on other generators.
|
||||||
|
|
||||||
|
When supported and enabled, numerous targets are created in order to make it
|
||||||
|
possible to build a file containing just the commands that are needed for the
|
||||||
|
tool in question.
|
||||||
|
|
||||||
|
``cmake_build_database-<CONFIG>``
|
||||||
|
Writes ``build_database_<CONFIG>.json``. Writes a build database for the
|
||||||
|
entire build for the given configuration and all languages. Not available if
|
||||||
|
the configuration name is the empty string.
|
||||||
|
|
||||||
|
``cmake_build_database-<LANG>-<CONFIG>``
|
||||||
|
Writes ``build_database_<LANG>_<CONFIG>.json``. Writes build database for
|
||||||
|
the entire build for the given configuration and language. Not available if
|
||||||
|
the configuration name is the empty string.
|
||||||
|
|
||||||
|
``cmake_build_database-<LANG>``
|
||||||
|
Writes ``build_database_<LANG>.json``. Writes build database for the entire
|
||||||
|
build for the given language and all configurations. In a multi-config
|
||||||
|
generator, other build configuration database may be assumed to exist.
|
||||||
|
|
||||||
|
``cmake_build_database``
|
||||||
|
Writes to ``build_database.json``. Writes build database for all languages
|
||||||
|
and configurations. In a multi-config generator, other build configuration
|
||||||
|
database may be assumed to exist.
|
||||||
@ -0,0 +1,12 @@
|
|||||||
|
CMAKE_HOST_EXECUTABLE_SUFFIX
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
The suffix for executables on the host platform. This may differ from
|
||||||
|
the suffix for the target platform, :variable:`CMAKE_EXECUTABLE_SUFFIX`.
|
||||||
|
|
||||||
|
The suffix to use for the end of an executable filename if any, ``.exe``
|
||||||
|
on Windows.
|
||||||
|
|
||||||
|
See also :variable:`CMAKE_EXECUTABLE_SUFFIX`.
|
||||||
@ -0,0 +1,10 @@
|
|||||||
|
CMAKE_<LANG>_CREATE_SHARED_LIBRARY_ARCHIVE
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
Rule variable to create a shared library with archive.
|
||||||
|
|
||||||
|
This is a rule variable that tells CMake how to create a shared
|
||||||
|
library with an archive for the language <LANG>. This rule variable
|
||||||
|
is a ; delimited list of commands to run to perform the linking step.
|
||||||
@ -0,0 +1,10 @@
|
|||||||
|
CMAKE_<LANG>_HOST_COMPILER_ID
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
This variable is available when ``<LANG>`` is ``CUDA`` or ``HIP``
|
||||||
|
and :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA``.
|
||||||
|
It contains the identity of the host compiler invoked by ``nvcc``,
|
||||||
|
either by default or as specified by :variable:`CMAKE_<LANG>_HOST_COMPILER`,
|
||||||
|
among possibilities documented by :variable:`CMAKE_<LANG>_COMPILER_ID`.
|
||||||
@ -0,0 +1,10 @@
|
|||||||
|
CMAKE_<LANG>_HOST_COMPILER_VERSION
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.31
|
||||||
|
|
||||||
|
This variable is available when ``<LANG>`` is ``CUDA`` or ``HIP``
|
||||||
|
and :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA``.
|
||||||
|
It contains the version of the host compiler invoked by ``nvcc``,
|
||||||
|
either by default or as specified by :variable:`CMAKE_<LANG>_HOST_COMPILER`,
|
||||||
|
in the same format as :variable:`CMAKE_<LANG>_COMPILER_VERSION`.
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue