Compare commits
No commits in common. '057d50741e9ae7944aef3397371702ccb0fbf5ad' and '167f7148a5d87908344d2b3a28a5c91b0f6d199b' have entirely different histories.
057d50741e
...
167f7148a5
@ -1,263 +0,0 @@
|
||||
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.
|
||||
@ -1,46 +0,0 @@
|
||||
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,111 +1,43 @@
|
||||
CMake Testing Guide
|
||||
*******************
|
||||
CMake Testing Process
|
||||
*********************
|
||||
|
||||
The following is a guide to the CMake test suite for developers.
|
||||
The following documents the process for running integration testing builds.
|
||||
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 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.
|
||||
|
||||
``-R <regex>``
|
||||
Select tests for which the regular expression matches a substring
|
||||
of their name.
|
||||
CMake Dashboard Scripts
|
||||
=======================
|
||||
|
||||
Cleaning Test Build Trees
|
||||
-------------------------
|
||||
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.
|
||||
|
||||
Many CMake tests create their own test project build trees underneath
|
||||
the ``Tests/`` directory at the top of the CMake build tree. These
|
||||
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:
|
||||
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
|
||||
|
||||
$ cmake -B build-ninja -G Ninja -DCMAKE_BUILD_TYPE=Debug
|
||||
$ cmake --build build-ninja
|
||||
$ mkdir -p ~/Dashboards
|
||||
$ cd ~/Dashboards
|
||||
$ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
|
||||
$ cd CMakeScripts
|
||||
|
||||
one may configure a second build tree to drive tests with the
|
||||
``Ninja Multi-Config`` generator:
|
||||
|
||||
.. code-block:: console
|
||||
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 -B build-nmc-tests -G "Ninja Multi-Config" \
|
||||
-DCMake_TEST_EXTERNAL_CMAKE="$PWD/build-ninja/bin"
|
||||
$ cmake --build build-nmc-tests --config Release
|
||||
|
||||
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
|
||||
.. _`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
|
||||
|
||||
$ cd build-nmc-tests
|
||||
$ ctest -C Release
|
||||
Nightly Start Time
|
||||
------------------
|
||||
|
||||
Note that the configuration with which one drives tests in the second
|
||||
build tree is independent of the configuration with which CMake was
|
||||
built in the first.
|
||||
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.
|
||||
|
||||
@ -0,0 +1,6 @@
|
||||
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.
|
||||
@ -1,18 +0,0 @@
|
||||
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``
|
||||
@ -1,17 +0,0 @@
|
||||
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.
|
||||
@ -1,11 +0,0 @@
|
||||
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,9 +1,57 @@
|
||||
Visual Studio 12 2013
|
||||
---------------------
|
||||
|
||||
Removed. This once generated Visual Studio 12 2013 project files, but
|
||||
the generator has been removed since CMake 3.31. It is still possible
|
||||
to build with the VS 12 2013 toolset by also installing VS 2015 (or above)
|
||||
and 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.
|
||||
Deprecated. Generates Visual Studio 12 (VS 2013) project files.
|
||||
|
||||
.. note::
|
||||
This generator is deprecated and will be removed in a future version
|
||||
of CMake. It will still be possible to build with VS 12 2013 tools
|
||||
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
@ -1,5 +0,0 @@
|
||||
``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).
|
||||
@ -1,26 +0,0 @@
|
||||
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
|
||||
@ -1,39 +0,0 @@
|
||||
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
|
||||
@ -1,22 +0,0 @@
|
||||
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
|
||||
@ -1,37 +0,0 @@
|
||||
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
|
||||
@ -1,40 +0,0 @@
|
||||
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``, or
|
||||
``JOB_SERVER_AWARE`` 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
|
||||
@ -1,27 +0,0 @@
|
||||
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
|
||||
@ -1,38 +0,0 @@
|
||||
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
|
||||
@ -1,37 +0,0 @@
|
||||
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
|
||||
@ -1,28 +0,0 @@
|
||||
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
|
||||
@ -1,36 +0,0 @@
|
||||
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
|
||||
@ -1,20 +0,0 @@
|
||||
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`.
|
||||
@ -1,15 +0,0 @@
|
||||
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.
|
||||
@ -1,87 +0,0 @@
|
||||
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``.
|
||||
@ -1,12 +0,0 @@
|
||||
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
|
||||
@ -1,271 +0,0 @@
|
||||
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`.
|
||||
|
||||
Updates
|
||||
=======
|
||||
|
||||
Changes made since CMake 3.31.0 include the following.
|
||||
|
||||
3.31.1
|
||||
------
|
||||
|
||||
* This version made no changes to documented features or interfaces.
|
||||
Some implementation updates were made to support ecosystem changes
|
||||
and/or fix regressions.
|
||||
@ -1,10 +0,0 @@
|
||||
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,86 +0,0 @@
|
||||
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.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue