Update to upstream version '3.24.0'
with Debian dir 9b1611105a
ci/unstable
Timo Röhling
2 years ago
commit
99c46c07e6
@ -0,0 +1,41 @@
|
|||||||
|
Specify which registry views must be queried. This option is only meaningful
|
||||||
|
on ``Windows`` platform and will be ignored on other ones. When not
|
||||||
|
specified, |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when :policy:`CMP0134`
|
||||||
|
policy is ``NEW``. Refer to :policy:`CMP0134` policy for default view when
|
||||||
|
policy is ``OLD`` or undefined.
|
||||||
|
|
||||||
|
``64``
|
||||||
|
Query the 64bit registry. On ``32bit Windows``, returns always the string
|
||||||
|
``/REGISTRY-NOTFOUND``.
|
||||||
|
|
||||||
|
``32``
|
||||||
|
Query the 32bit registry.
|
||||||
|
|
||||||
|
``64_32``
|
||||||
|
Query both views (``64`` and ``32``) and generate a path for each.
|
||||||
|
|
||||||
|
``32_64``
|
||||||
|
Query both views (``32`` and ``64``) and generate a path for each.
|
||||||
|
|
||||||
|
``HOST``
|
||||||
|
Query the registry matching the architecture of the host: ``64`` on ``64bit
|
||||||
|
Windows`` and ``32`` on ``32bit Windows``.
|
||||||
|
|
||||||
|
``TARGET``
|
||||||
|
Query the registry matching the architecture specified by
|
||||||
|
:variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
|
||||||
|
``HOST`` view.
|
||||||
|
|
||||||
|
``BOTH``
|
||||||
|
Query both views (``32`` and ``64``). The order depends of the following
|
||||||
|
rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
|
||||||
|
following view depending of the content of this variable:
|
||||||
|
|
||||||
|
* ``8``: ``64_32``
|
||||||
|
* ``4``: ``32_64``
|
||||||
|
|
||||||
|
If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
|
||||||
|
architecture of the host:
|
||||||
|
|
||||||
|
* ``64bit``: ``64_32``
|
||||||
|
* ``32bit``: ``32``
|
||||||
@ -1,16 +1,18 @@
|
|||||||
option
|
option
|
||||||
------
|
------
|
||||||
|
|
||||||
Provide an option that the user can optionally select.
|
Provide a boolean option that the user can optionally select.
|
||||||
|
|
||||||
.. code-block:: cmake
|
.. code-block:: cmake
|
||||||
|
|
||||||
option(<variable> "<help_text>" [value])
|
option(<variable> "<help_text>" [value])
|
||||||
|
|
||||||
Provides an option for the user to select as ``ON`` or ``OFF``.
|
If no initial ``<value>`` is provided, boolean ``OFF`` is the default value.
|
||||||
If no initial ``<value>`` is provided, ``OFF`` is used.
|
|
||||||
If ``<variable>`` is already set as a normal or cache variable,
|
If ``<variable>`` is already set as a normal or cache variable,
|
||||||
then the command does nothing (see policy :policy:`CMP0077`).
|
then the command does nothing (see policy :policy:`CMP0077`).
|
||||||
|
|
||||||
If you have options that depend on the values of other options, see
|
For options that depend on the values of other options, see
|
||||||
the module help for :module:`CMakeDependentOption`.
|
the module help for :module:`CMakeDependentOption`.
|
||||||
|
|
||||||
|
In CMake project mode, a boolean cache variable is created with the option
|
||||||
|
value. In CMake script mode, a boolean variable is set with the option value.
|
||||||
|
|||||||
@ -1,87 +1,7 @@
|
|||||||
CPack PackageMaker Generator
|
CPack PackageMaker Generator
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
||||||
PackageMaker CPack generator (macOS).
|
Removed. This once generated PackageMaker installers, but the
|
||||||
|
generator has been removed since CMake 3.24. Xcode no longer distributes
|
||||||
.. deprecated:: 3.17
|
the PackageMaker tools. Use the :cpack_gen:`CPack productbuild Generator`
|
||||||
|
instead.
|
||||||
Xcode no longer distributes the PackageMaker tools.
|
|
||||||
This CPack generator will be removed in a future version of CPack.
|
|
||||||
|
|
||||||
Variables specific to CPack PackageMaker generator
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The following variable is specific to installers built on Mac
|
|
||||||
macOS using PackageMaker:
|
|
||||||
|
|
||||||
.. variable:: CPACK_OSX_PACKAGE_VERSION
|
|
||||||
|
|
||||||
The version of macOS that the resulting PackageMaker archive should be
|
|
||||||
compatible with. Different versions of macOS support different
|
|
||||||
features. For example, CPack can only build component-based installers for
|
|
||||||
macOS 10.4 or newer, and can only build installers that download
|
|
||||||
components on-the-fly for macOS 10.5 or newer. If left blank, this value
|
|
||||||
will be set to the minimum version of macOS that supports the requested
|
|
||||||
features. Set this variable to some value (e.g., 10.4) only if you want to
|
|
||||||
guarantee that your installer will work on that version of macOS, and
|
|
||||||
don't mind missing extra features available in the installer shipping with
|
|
||||||
later versions of macOS.
|
|
||||||
|
|
||||||
Background Image
|
|
||||||
""""""""""""""""
|
|
||||||
|
|
||||||
.. versionadded:: 3.17
|
|
||||||
|
|
||||||
This group of variables controls the background image of the generated
|
|
||||||
installer.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND
|
|
||||||
|
|
||||||
Adds a background to Distribution XML if specified. The value contains the
|
|
||||||
path to image in ``Resources`` directory.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT
|
|
||||||
|
|
||||||
Adds an ``alignment`` attribute to the background in Distribution XML.
|
|
||||||
Refer to Apple documentation for valid values.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING
|
|
||||||
|
|
||||||
Adds a ``scaling`` attribute to the background in Distribution XML.
|
|
||||||
Refer to Apple documentation for valid values.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE
|
|
||||||
|
|
||||||
Adds a ``mime-type`` attribute to the background in Distribution XML.
|
|
||||||
The option contains MIME type of an image.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI
|
|
||||||
|
|
||||||
Adds an ``uti`` attribute to the background in Distribution XML.
|
|
||||||
The option contains UTI type of an image.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA
|
|
||||||
|
|
||||||
Adds a background for the Dark Aqua theme to Distribution XML if
|
|
||||||
specified. The value contains the path to image in ``Resources``
|
|
||||||
directory.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT
|
|
||||||
|
|
||||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option,
|
|
||||||
but for the dark theme.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING
|
|
||||||
|
|
||||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option,
|
|
||||||
but for the dark theme.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE
|
|
||||||
|
|
||||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option,
|
|
||||||
but for the dark theme.
|
|
||||||
|
|
||||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI
|
|
||||||
|
|
||||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option,
|
|
||||||
but for the dark theme.
|
|
||||||
|
|||||||
@ -0,0 +1,10 @@
|
|||||||
|
ADSP_ROOT
|
||||||
|
---------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
.. include:: ENV_VAR.txt
|
||||||
|
|
||||||
|
The ``ADSP_ROOT`` environment variable specifies a default value
|
||||||
|
for the :variable:`CMAKE_ADSP_ROOT` variable when there is no explicit
|
||||||
|
configuration given on the first run while creating a new build tree.
|
||||||
@ -0,0 +1,9 @@
|
|||||||
|
CMAKE_COLOR_DIAGNOSTICS
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
.. include:: ENV_VAR.txt
|
||||||
|
|
||||||
|
Specifies a default value for the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable
|
||||||
|
when there is no explicit value given on the first run.
|
||||||
File diff suppressed because it is too large
Load Diff
@ -1,4 +0,0 @@
|
|||||||
CPackPackageMaker
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
The documentation for the CPack PackageMaker generator has moved here: :cpack_gen:`CPack PackageMaker Generator`
|
|
||||||
@ -0,0 +1,32 @@
|
|||||||
|
CMP0130
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
:command:`while` diagnoses condition evaluation errors.
|
||||||
|
|
||||||
|
CMake 3.23 and below accidentally tolerated errors encountered while
|
||||||
|
evaluating the condition passed to the :command:`while` command
|
||||||
|
(but not the :command:`if` command). For example, the code
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
set(paren "(")
|
||||||
|
while(${paren})
|
||||||
|
endwhile()
|
||||||
|
|
||||||
|
creates an unbalanced parenthesis during condition evaluation.
|
||||||
|
|
||||||
|
CMake 3.24 and above prefer to diagnose such errors. This policy
|
||||||
|
provides compatibility for projects that have not been updated to
|
||||||
|
fix their condition errors.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to ignore errors in
|
||||||
|
:command:`while` conditions. The ``NEW`` behavior for this
|
||||||
|
policy is to diagnose errors in :command:`while` conditions.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. CMake version |release|
|
||||||
|
warns when the policy is not set and uses ``OLD`` behavior. Use the
|
||||||
|
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,31 @@
|
|||||||
|
CMP0131
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
:prop_tgt:`LINK_LIBRARIES` supports the :genex:`$<LINK_ONLY:...>`
|
||||||
|
generator expression.
|
||||||
|
|
||||||
|
CMake 3.23 and below documented the :genex:`$<LINK_ONLY:...>` generator
|
||||||
|
expression only for use in :prop_tgt:`INTERFACE_LINK_LIBRARIES`.
|
||||||
|
When used in :prop_tgt:`LINK_LIBRARIES`, the content guarded inside
|
||||||
|
:genex:`$<LINK_ONLY:...>` was always used, even when collecting non-linking
|
||||||
|
usage requirements such as :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`.
|
||||||
|
|
||||||
|
CMake 3.24 and above prefer to support :genex:`$<LINK_ONLY:...>`, when
|
||||||
|
used in :prop_tgt:`LINK_LIBRARIES`, by using the guarded content only
|
||||||
|
for link dependencies and not other usage requirements. This policy
|
||||||
|
provides compatibility for projects that have not been updated to
|
||||||
|
account for this change.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to use :prop_tgt:`LINK_LIBRARIES`
|
||||||
|
content guarded by :genex:`$<LINK_ONLY:...>` even for non-linking
|
||||||
|
usage requirements. The ``NEW`` behavior for this policy is to use
|
||||||
|
the guarded content only for link dependencies.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. Use the
|
||||||
|
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||||
|
explicitly. Unlike many policies, CMake version |release| does *not*
|
||||||
|
warn when this policy is not set, and simply uses ``OLD`` behavior.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,26 @@
|
|||||||
|
CMP0132
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Apart from when using the Xcode generator and some Visual Studio generators,
|
||||||
|
CMake 3.23 and below will set environment variables like :envvar:`CC`,
|
||||||
|
:envvar:`CXX`, etc. when the corresponding language is enabled.
|
||||||
|
This only occurs on the very first time CMake is run in a build directory,
|
||||||
|
and the environment variables are only defined at configure time, not build
|
||||||
|
time. On subsequent CMake runs, these environment variables are not set,
|
||||||
|
opening up the opportunity for different behavior between the first and
|
||||||
|
subsequent CMake runs. CMake 3.24 and above prefer to not set these
|
||||||
|
environment variables when a language is enabled, even on the first run in
|
||||||
|
a build directory.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy sets the relevant environment variable
|
||||||
|
on the first run when a language is enabled. The ``NEW`` behavior for this
|
||||||
|
policy does not set any such environment variables.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. Use the
|
||||||
|
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||||
|
Unlike many policies, CMake version |release| does *not* warn
|
||||||
|
when this policy is not set and simply uses ``OLD`` behavior.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,32 @@
|
|||||||
|
CMP0133
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
The :module:`CPack` module disables SLA by default in the
|
||||||
|
:cpack_gen:`CPack DragNDrop Generator`.
|
||||||
|
|
||||||
|
The :cpack_gen:`CPack DragNDrop Generator` in CMake 3.22 and below attach a
|
||||||
|
Software License Agreement (SLA) to ``.dmg`` files using the file specified
|
||||||
|
by :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a non-default value.
|
||||||
|
macOS 12.0 deprecated the tools used to do this, so CMake 3.23 added
|
||||||
|
the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option to
|
||||||
|
control the behavior. CMake 3.23 enables that option by default for
|
||||||
|
compatibility with older versions. CMake 3.24 and above prefer to *not*
|
||||||
|
enable the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option by
|
||||||
|
default. This policy provides compatibility with projects that have not
|
||||||
|
been updated to account for the lack of a SLA in their ``.dmg`` packages.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to enable
|
||||||
|
:variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` by default.
|
||||||
|
The ``NEW`` behavior for this policy is to not enable it by default.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. Use the
|
||||||
|
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||||
|
explicitly. Unlike many policies, CMake version |release| does *not* warn
|
||||||
|
by default when this policy is not set and simply uses ``OLD`` behavior.
|
||||||
|
See documentation of the
|
||||||
|
:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
|
||||||
|
variable to control the warning.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,39 @@
|
|||||||
|
CMP0134
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
The default registry view is ``TARGET`` for the :command:`find_file`,
|
||||||
|
:command:`find_path`, :command:`find_library`, and :command:`find_package`
|
||||||
|
commands and ``BOTH`` for the :command:`find_program` command.
|
||||||
|
|
||||||
|
The default registry views in CMake 3.23 and below are selected using the
|
||||||
|
following rules:
|
||||||
|
|
||||||
|
* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``8``:
|
||||||
|
|
||||||
|
* Use view ``64`` for all ``find_*`` commands except :command:`find_program`
|
||||||
|
command.
|
||||||
|
* Use view ``64_32`` for :command:`find_program` command.
|
||||||
|
|
||||||
|
* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``4`` or is undefined:
|
||||||
|
|
||||||
|
* Use view ``32`` for all ``find_*`` commands except :command:`find_program`
|
||||||
|
command.
|
||||||
|
* Use view ``32_64`` for :command:`find_program` command.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to use registry views ``64`` and
|
||||||
|
``64_32`` or ``32_64`` and ``32`` as default, depending of
|
||||||
|
:variable:`CMAKE_SIZEOF_VOID_P` variable value.
|
||||||
|
The ``NEW`` behavior for this policy is to use registry views ``TARGET`` and
|
||||||
|
``BOTH`` as default.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. Use the
|
||||||
|
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||||
|
explicitly. Unlike many policies, CMake version |release| does *not* warn
|
||||||
|
by default when this policy is not set and simply uses ``OLD`` behavior.
|
||||||
|
See documentation of the
|
||||||
|
:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
|
||||||
|
variable to control the warning.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,29 @@
|
|||||||
|
CMP0135
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
When using the ``URL`` download method with the :command:`ExternalProject_Add`
|
||||||
|
command, CMake 3.23 and below sets the timestamps of the extracted contents
|
||||||
|
to the same as the timestamps in the archive. When the ``URL`` changes, the
|
||||||
|
new archive is downloaded and extracted, but the timestamps of the extracted
|
||||||
|
contents might not be newer than the previous contents. Anything that depends
|
||||||
|
on the extracted contents might not be rebuilt, even though the contents may
|
||||||
|
change.
|
||||||
|
|
||||||
|
CMake 3.24 and above prefers to set the timestamps of all extracted contents
|
||||||
|
to the time of the extraction. This ensures that anything that depends on the
|
||||||
|
extracted contents will be rebuilt whenever the ``URL`` changes.
|
||||||
|
|
||||||
|
The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the
|
||||||
|
:command:`ExternalProject_Add` command can be used to explicitly specify how
|
||||||
|
timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not
|
||||||
|
given, this policy controls the default behavior. The ``OLD`` behavior for
|
||||||
|
this policy is to restore the timestamps from the archive. The ``NEW``
|
||||||
|
behavior sets the timestamps of extracted contents to the time of extraction.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. CMake version |release|
|
||||||
|
warns when the policy is not set and uses ``OLD`` behavior. Use the
|
||||||
|
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,50 @@
|
|||||||
|
CMP0136
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Watcom runtime library flags are selected by an abstraction.
|
||||||
|
|
||||||
|
Compilers targeting the Watcom ABI have flags to select the Watcom runtime
|
||||||
|
library.
|
||||||
|
|
||||||
|
In CMake 3.23 and below, Watcom runtime library selection flags are added to
|
||||||
|
the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
|
||||||
|
automatically. This allows users to edit their cache entries to adjust the
|
||||||
|
flags. However, the presence of such default flags is problematic for
|
||||||
|
projects that want to choose a different runtime library programmatically.
|
||||||
|
In particular, it requires string editing of the
|
||||||
|
:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
|
||||||
|
CMake builtin defaults so they can be replaced.
|
||||||
|
|
||||||
|
CMake 3.24 and above prefer to leave the Watcom runtime library selection flags
|
||||||
|
out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
|
||||||
|
offer a first-class abstraction. The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
|
||||||
|
variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property may be set to
|
||||||
|
select the Watcom runtime library. If they are not set then CMake uses the
|
||||||
|
default value ``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other
|
||||||
|
platforms, which is equivalent to the original flags.
|
||||||
|
|
||||||
|
This policy provides compatibility with projects that have not been updated
|
||||||
|
to be aware of the abstraction. The policy setting takes effect as of the
|
||||||
|
first :command:`project` or :command:`enable_language` command that enables
|
||||||
|
a language whose compiler targets the Watcom ABI.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Once the policy has taken effect at the top of a project, that choice
|
||||||
|
must be used throughout the tree. In projects that have nested projects
|
||||||
|
in subdirectories, be sure to convert everything together.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to place Watcom runtime library
|
||||||
|
flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
|
||||||
|
entries and ignore the :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` abstraction.
|
||||||
|
The ``NEW`` behavior for this policy is to *not* place Watcom runtime
|
||||||
|
library flags in the default cache entries and use the abstraction instead.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. Use the
|
||||||
|
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||||
|
Unlike many policies, CMake version |release| does *not* warn
|
||||||
|
when this policy is not set and simply uses ``OLD`` behavior.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,33 @@
|
|||||||
|
CMP0137
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
:command:`try_compile` passes platform variables in project mode.
|
||||||
|
|
||||||
|
The :command:`try_compile` command :ref:`source file <Try Compiling Source
|
||||||
|
Files>` signature propagates CMake variables containing platform settings,
|
||||||
|
and those specified by the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`
|
||||||
|
variable, into the generated test project. This helps the test project drive
|
||||||
|
the toolchain the same way the calling project will. In CMake 3.23 and below,
|
||||||
|
the :ref:`whole-project <Try Compiling Whole Projects>` signature does not
|
||||||
|
propagate platform variables automatically. CMake 3.24 and above prefer to
|
||||||
|
propagate platform variables in the :ref:`whole-project <Try Compiling Whole
|
||||||
|
Projects>` signature. This policy provides compatibility with projects that
|
||||||
|
have not been updated to expect the behavior.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to not pass any additional variables to
|
||||||
|
the :ref:`whole-project <Try Compiling Whole Projects>` signature.
|
||||||
|
The ``NEW`` behavior for this policy is to pass the same variables that the
|
||||||
|
:ref:`source file <Try Compiling Source Files>` signature does.
|
||||||
|
|
||||||
|
Regardless of the policy setting, the
|
||||||
|
:variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be set
|
||||||
|
to suppress passing the platform variables through either signature.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. Use the
|
||||||
|
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||||
|
explicitly. Unlike many policies, CMake version |release| does *not* warn
|
||||||
|
by default when this policy is not set and simply uses ``OLD`` behavior.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,31 @@
|
|||||||
|
CMP0138
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
:module:`CheckIPOSupported` uses flags from calling project.
|
||||||
|
|
||||||
|
The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
|
||||||
|
command compiles a test project to determine whether the toolchain
|
||||||
|
supports :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`. CMake 3.23 and
|
||||||
|
below run the check with the default values of the
|
||||||
|
:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
|
||||||
|
variables for the current environment and toolchain settings.
|
||||||
|
However, some projects may modify these flag variables to add
|
||||||
|
flags that affect availability of the toolchain's IPO features.
|
||||||
|
CMake 3.24 and above prefer to honor the calling project's values
|
||||||
|
for these variables. This policy provides compatibility for projects
|
||||||
|
that have not been updated to expect this behavior.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to ignore the calling
|
||||||
|
project's values of :variable:`CMAKE_<LANG>_FLAGS` and
|
||||||
|
:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`. The ``NEW`` behavior
|
||||||
|
for this policy is to use the values of those variables as
|
||||||
|
compiler flags in the test project.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24. Use the
|
||||||
|
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||||
|
Unlike many policies, CMake version |release| does *not* warn
|
||||||
|
when this policy is not set and simply uses ``OLD`` behavior.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,17 @@
|
|||||||
|
CMP0139
|
||||||
|
-------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
The :command:`if` command supports path comparisons using ``PATH_EQUAL``
|
||||||
|
operator.
|
||||||
|
|
||||||
|
The ``OLD`` behavior for this policy is to ignore the ``PATH_EQUAL`` operator.
|
||||||
|
The ``NEW`` behavior is to interpret the ``PATH_EQUAL`` operator.
|
||||||
|
|
||||||
|
This policy was introduced in CMake version 3.24.
|
||||||
|
CMake version |release| warns when the policy is not set and uses
|
||||||
|
``OLD`` behavior. Use the :command:`cmake_policy` command to set
|
||||||
|
it to ``OLD`` or ``NEW`` explicitly.
|
||||||
|
|
||||||
|
.. include:: DEPRECATED.txt
|
||||||
@ -0,0 +1,10 @@
|
|||||||
|
COMPILE_WARNING_AS_ERROR
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Specify whether to treat warnings on compile as errors.
|
||||||
|
If enabled, adds a flag to treat warnings on compile as errors.
|
||||||
|
|
||||||
|
This property is initialized by the value of the variable
|
||||||
|
:variable:`CMAKE_COMPILE_WARNING_AS_ERROR` if it is set when a target is created.
|
||||||
@ -0,0 +1,13 @@
|
|||||||
|
INTERFACE_HEADER_SETS_TO_VERIFY
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Used to specify which ``PUBLIC`` and ``INTERFACE`` header sets of a target
|
||||||
|
should be verified.
|
||||||
|
|
||||||
|
This property contains a semicolon-separated list of header sets which
|
||||||
|
should be verified if :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to
|
||||||
|
``TRUE``. If the list is empty, all ``PUBLIC`` and ``INTERFACE`` header sets
|
||||||
|
are verified. (If the project does not want to verify any header sets on the
|
||||||
|
target, simply set :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` to ``FALSE``.)
|
||||||
@ -0,0 +1,236 @@
|
|||||||
|
INTERFACE_LINK_LIBRARIES_DIRECT
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
List of libraries that consumers of this library should treat
|
||||||
|
as direct link dependencies.
|
||||||
|
|
||||||
|
This target property may be set to *include* items in a dependent
|
||||||
|
target's final set of direct link dependencies. See the
|
||||||
|
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target property
|
||||||
|
to exclude items.
|
||||||
|
|
||||||
|
The initial set of a dependent target's direct link dependencies is
|
||||||
|
specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect
|
||||||
|
link dependencies are specified by the transitive closure of the direct
|
||||||
|
link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
|
||||||
|
Any link dependency may specify additional direct link dependencies
|
||||||
|
using the ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property.
|
||||||
|
The set of direct link dependencies is then filtered to exclude items named
|
||||||
|
by any dependency's :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
|
||||||
|
target property.
|
||||||
|
|
||||||
|
.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT``
|
||||||
|
.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
|
||||||
|
|
||||||
|
Direct Link Dependencies as Usage Requirements
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The ``INTERFACE_LINK_LIBRARIES_DIRECT`` and
|
||||||
|
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties
|
||||||
|
are :ref:`usage requirements <Target Usage Requirements>`.
|
||||||
|
Their effects propagate to dependent targets transitively, and can
|
||||||
|
therefore affect the direct link dependencies of every target in a
|
||||||
|
chain of dependent libraries. Whenever some library target ``X`` links
|
||||||
|
to another library target ``Y`` whose direct or transitive usage
|
||||||
|
requirements contain ``INTERFACE_LINK_LIBRARIES_DIRECT`` or
|
||||||
|
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, the properties may affect
|
||||||
|
``X``'s list of direct link dependencies:
|
||||||
|
|
||||||
|
* If ``X`` is a shared library or executable, its dependencies are linked.
|
||||||
|
They also affect the usage requirements with which ``X``'s sources are
|
||||||
|
compiled.
|
||||||
|
|
||||||
|
* If ``X`` is a static library or object library, it does not actually
|
||||||
|
link, so its dependencies at most affect the usage requirements with
|
||||||
|
which ``X``'s sources are compiled.
|
||||||
|
|
||||||
|
The properties may also affect the list of direct link dependencies
|
||||||
|
on ``X``'s dependents:
|
||||||
|
|
||||||
|
* If ``X`` links ``Y`` publicly:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
target_link_libraries(X PUBLIC Y)
|
||||||
|
|
||||||
|
then ``Y`` is placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
|
||||||
|
so ``Y``'s usage requirements, including ``INTERFACE_LINK_LIBRARIES_DIRECT``,
|
||||||
|
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the usage requirements
|
||||||
|
declared by the direct link dependencies they add, are propagated to
|
||||||
|
``X``'s dependents.
|
||||||
|
|
||||||
|
* If ``X`` is a static library or object library, and links ``Y`` privately:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
target_link_libraries(X PRIVATE Y)
|
||||||
|
|
||||||
|
then ``$<LINK_ONLY:Y>`` is placed in ``X``'s
|
||||||
|
:prop_tgt:`INTERFACE_LINK_LIBRARIES`. ``Y``'s linking requirements,
|
||||||
|
including ``INTERFACE_LINK_LIBRARIES_DIRECT``,
|
||||||
|
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the transitive link
|
||||||
|
dependencies declared by the direct link dependencies they add, are
|
||||||
|
propagated to ``X``'s dependents. However, ``Y``'s non-linking
|
||||||
|
usage requirements are blocked by the :genex:`LINK_ONLY` generator
|
||||||
|
expression, and are not propagated to ``X``'s dependents.
|
||||||
|
|
||||||
|
* If ``X`` is a shared library or executable, and links ``Y`` privately:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
target_link_libraries(X PRIVATE Y)
|
||||||
|
|
||||||
|
then ``Y`` is not placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
|
||||||
|
so ``Y``'s usage requirements, even ``INTERFACE_LINK_LIBRARIES_DIRECT``
|
||||||
|
and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, are not propagated to
|
||||||
|
``X``'s dependents.
|
||||||
|
|
||||||
|
* In all cases, the content of ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`
|
||||||
|
is not affected by ``Y``'s ``INTERFACE_LINK_LIBRARIES_DIRECT`` or
|
||||||
|
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``.
|
||||||
|
|
||||||
|
One may limit the effects of ``INTERFACE_LINK_LIBRARIES_DIRECT`` and
|
||||||
|
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` to a subset of dependent
|
||||||
|
targets by using the :genex:`TARGET_PROPERTY` generator expression.
|
||||||
|
For example, to limit the effects to executable targets, use an
|
||||||
|
entry of the form::
|
||||||
|
|
||||||
|
"$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"
|
||||||
|
|
||||||
|
Similarly, to limit the effects to specific targets, use an entry
|
||||||
|
of the form::
|
||||||
|
|
||||||
|
"$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"
|
||||||
|
|
||||||
|
This entry will only affect targets that set their ``USE_IT``
|
||||||
|
target property to a true value.
|
||||||
|
|
||||||
|
Direct Link Dependency Ordering
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The list of direct link dependencies for a target is computed from an
|
||||||
|
initial ordered list in its :prop_tgt:`LINK_LIBRARIES` target property.
|
||||||
|
For each item, additional direct link dependencies are discovered from
|
||||||
|
its direct and transitive ``INTERFACE_LINK_LIBRARIES_DIRECT`` usage
|
||||||
|
requirements. Each discovered item is injected before the item that
|
||||||
|
specified it. However, a discovered item is added at most once,
|
||||||
|
and only if it did not appear anywhere in the initial list.
|
||||||
|
This gives :prop_tgt:`LINK_LIBRARIES` control over ordering of
|
||||||
|
those direct link dependencies that it explicitly specifies.
|
||||||
|
|
||||||
|
Once all direct link dependencies have been collected, items named by
|
||||||
|
all of their :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
|
||||||
|
usage requirements are removed from the final list. This does not
|
||||||
|
affect the order of the items that remain.
|
||||||
|
|
||||||
|
Example: Static Plugins
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Consider a static library ``Foo`` that provides a static plugin
|
||||||
|
``FooPlugin`` to consuming application executables, where the
|
||||||
|
implementation of the plugin depends on ``Foo`` and other things.
|
||||||
|
In this case, the application should link to ``FooPlugin`` directly,
|
||||||
|
before ``Foo``. However, the application author only knows about ``Foo``.
|
||||||
|
We can express this as follows:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
# Core library used by other components.
|
||||||
|
add_library(Core STATIC core.cpp)
|
||||||
|
|
||||||
|
# Foo is a static library for use by applications.
|
||||||
|
# Implementation of Foo depends on Core.
|
||||||
|
add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
|
||||||
|
target_link_libraries(Foo PRIVATE Core)
|
||||||
|
|
||||||
|
# Extra parts of Foo for use by its static plugins.
|
||||||
|
# Implementation of Foo's extra parts depends on both Core and Foo.
|
||||||
|
add_library(FooExtras STATIC foo_extras.cpp)
|
||||||
|
target_link_libraries(FooExtras PRIVATE Core Foo)
|
||||||
|
|
||||||
|
# The Foo library has an associated static plugin
|
||||||
|
# that should be linked into the final executable.
|
||||||
|
# Implementation of the plugin depends on Core, Foo, and FooExtras.
|
||||||
|
add_library(FooPlugin STATIC foo_plugin.cpp)
|
||||||
|
target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)
|
||||||
|
|
||||||
|
# An app that links Foo should link Foo's plugin directly.
|
||||||
|
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)
|
||||||
|
|
||||||
|
# An app does not need to link Foo directly because the plugin links it.
|
||||||
|
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)
|
||||||
|
|
||||||
|
An application ``app`` only needs to specify that it links to ``Foo``:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_executable(app main.cpp)
|
||||||
|
target_link_libraries(app PRIVATE Foo)
|
||||||
|
|
||||||
|
The ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property on ``Foo`` tells
|
||||||
|
CMake to pretend that ``app`` also links directly to ``FooPlugin``.
|
||||||
|
The ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target property on ``Foo``
|
||||||
|
tells CMake to pretend that ``app`` did *not* link directly to ``Foo``.
|
||||||
|
Instead, ``Foo`` will be linked as a dependency of ``FooPlugin``. The
|
||||||
|
final link line for ``app`` will link the libraries in the following
|
||||||
|
order:
|
||||||
|
|
||||||
|
* ``FooPlugin`` as a direct link dependency of ``app``
|
||||||
|
(via ``Foo``'s usage requirements).
|
||||||
|
* ``FooExtras`` as a dependency of ``FooPlugin``.
|
||||||
|
* ``Foo`` as a dependency of ``FooPlugin`` and ``FooExtras``.
|
||||||
|
* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.
|
||||||
|
|
||||||
|
Note that without the ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
|
||||||
|
property, ``Foo`` would be linked twice: once as a direct dependency
|
||||||
|
of ``app``, and once as a dependency of ``FooPlugin``.
|
||||||
|
|
||||||
|
Example: Opt-In Static Plugins
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
In the above `Example: Static Plugins`_, the ``app`` executable specifies
|
||||||
|
that it links directly to ``Foo``. In a real application, there might
|
||||||
|
be an intermediate library:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_library(app_impl STATIC app_impl.cpp)
|
||||||
|
target_link_libraries(app_impl PRIVATE Foo)
|
||||||
|
|
||||||
|
add_executable(app main.cpp)
|
||||||
|
target_link_libraries(app PRIVATE app_impl)
|
||||||
|
|
||||||
|
In this case we do not want ``Foo``'s ``INTERFACE_LINK_LIBRARIES_DIRECT``
|
||||||
|
and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties to affect
|
||||||
|
the direct dependencies of ``app_impl``. To avoid this, we can revise
|
||||||
|
the property values to make their effects opt-in:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
# An app that links Foo should link Foo's plugin directly.
|
||||||
|
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
|
||||||
|
"$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
|
||||||
|
)
|
||||||
|
|
||||||
|
# An app does not need to link Foo directly because the plugin links it.
|
||||||
|
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
|
||||||
|
"$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
|
||||||
|
)
|
||||||
|
|
||||||
|
Now, the ``app`` executable can opt-in to get ``Foo``'s plugin(s):
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)
|
||||||
|
|
||||||
|
The final link line for ``app`` will now link the libraries in the following
|
||||||
|
order:
|
||||||
|
|
||||||
|
* ``FooPlugin`` as a direct link dependency of ``app``
|
||||||
|
(via ``Foo``'s usage requirements).
|
||||||
|
* ``app_impl`` as a direct link dependency of ``app``.
|
||||||
|
* ``FooExtras`` as a dependency of ``FooPlugin``.
|
||||||
|
* ``Foo`` as a dependency of ``app_impl``, ``FooPlugin``, and ``FooExtras``.
|
||||||
|
* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.
|
||||||
@ -0,0 +1,9 @@
|
|||||||
|
The value of |INTERFACE_PROPERTY_LINK_DIRECT| may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The |INTERFACE_PROPERTY_LINK_DIRECT| target property is intended for
|
||||||
|
advanced use cases such as injection of static plugins into a consuming
|
||||||
|
executable. It should not be used as a substitute for organizing
|
||||||
|
normal calls to :command:`target_link_libraries`.
|
||||||
@ -0,0 +1,34 @@
|
|||||||
|
INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
|
||||||
|
---------------------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
List of libraries that consumers of this library should *not* treat
|
||||||
|
as direct link dependencies.
|
||||||
|
|
||||||
|
This target property may be set to *exclude* items from a dependent
|
||||||
|
target's final set of direct link dependencies. This property is
|
||||||
|
processed after the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`
|
||||||
|
target property of all other dependencies of the dependent target, so
|
||||||
|
exclusion from direct link dependence takes priority over inclusion.
|
||||||
|
|
||||||
|
The initial set of a dependent target's direct link dependencies is
|
||||||
|
specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect
|
||||||
|
link dependencies are specified by the transitive closure of the direct
|
||||||
|
link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
|
||||||
|
Any link dependency may specify additional direct link dependencies
|
||||||
|
using the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property.
|
||||||
|
The set of direct link dependencies is then filtered to exclude items named
|
||||||
|
by any dependency's ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
|
||||||
|
property.
|
||||||
|
|
||||||
|
Excluding an item from a dependent target's direct link dependencies
|
||||||
|
does not mean the dependent target won't link the item. The item
|
||||||
|
may still be linked as an indirect link dependency via the
|
||||||
|
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property on other dependencies.
|
||||||
|
|
||||||
|
.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``
|
||||||
|
.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
|
||||||
|
|
||||||
|
See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property
|
||||||
|
documentation for more details and examples.
|
||||||
@ -0,0 +1,65 @@
|
|||||||
|
LINK_LIBRARY_OVERRIDE
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Override the library features associated with libraries from
|
||||||
|
:genex:`LINK_LIBRARY` generator expressions. This can be used to resolve
|
||||||
|
incompatible library features that result from specifying different features
|
||||||
|
for the same library in different :genex:`LINK_LIBRARY` generator expressions.
|
||||||
|
|
||||||
|
This property supports overriding multiple libraries and features. It expects
|
||||||
|
a :ref:`semicolon-separated list <CMake Language Lists>`, where each list item
|
||||||
|
has the following form::
|
||||||
|
|
||||||
|
feature[,link-item]*
|
||||||
|
|
||||||
|
For each comma-separated ``link-item``, any existing library feature associated
|
||||||
|
with it will be ignored for the target this property is set on. The item
|
||||||
|
will instead be associated with the specified ``feature``. Each ``link-item``
|
||||||
|
can be anything that would be accepted as part of a ``library-list`` in a
|
||||||
|
:genex:`LINK_LIBRARY` generator expression.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_library(lib1 ...)
|
||||||
|
add_library(lib2 ...)
|
||||||
|
add_library(lib3 ...)
|
||||||
|
|
||||||
|
target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
|
||||||
|
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
|
||||||
|
target_link_libraries(lib3 PRIVATE lib1 lib2)
|
||||||
|
|
||||||
|
# lib1 is associated with both feature2 and no feature. Without any override,
|
||||||
|
# this would result in a fatal error at generation time for lib3.
|
||||||
|
# Define an override to resolve the incompatible feature associations.
|
||||||
|
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")
|
||||||
|
|
||||||
|
# lib1 and external will now be associated with feature2 instead when linking lib3
|
||||||
|
|
||||||
|
It is also possible to override any feature with the pre-defined ``DEFAULT``
|
||||||
|
library feature. This effectively discards any feature for that link item,
|
||||||
|
for that target only (``lib3`` in this example):
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
# When linking lib3, discard any library feature for lib1, and use feature2 for external
|
||||||
|
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE
|
||||||
|
"DEFAULT,lib1"
|
||||||
|
"feature2,external"
|
||||||
|
)
|
||||||
|
|
||||||
|
The above example also demonstrates how to specify different feature overrides
|
||||||
|
for different link items. See the :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>`
|
||||||
|
target property for an alternative way of overriding library features for
|
||||||
|
individual libraries, which may be simpler in some cases. If both properties
|
||||||
|
are defined and specify an override for the same link item,
|
||||||
|
:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` takes precedence over
|
||||||
|
``LINK_LIBRARY_OVERRIDE``.
|
||||||
|
|
||||||
|
Contents of ``LINK_LIBRARY_OVERRIDE`` may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
|
|
||||||
|
For more information about library features, see the
|
||||||
|
:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
|
||||||
|
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
|
||||||
@ -0,0 +1,51 @@
|
|||||||
|
LINK_LIBRARY_OVERRIDE_<LIBRARY>
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Override the library feature associated with ``<LIBRARY>`` from
|
||||||
|
:genex:`LINK_LIBRARY` generator expressions. This can be used to resolve
|
||||||
|
incompatible library features that result from specifying different features
|
||||||
|
for ``<LIBRARY>`` in different :genex:`LINK_LIBRARY` generator expressions.
|
||||||
|
|
||||||
|
When set on a target, this property holds a single library feature name, which
|
||||||
|
will be applied to ``<LIBRARY>`` when linking that target.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_library(lib1 ...)
|
||||||
|
add_library(lib2 ...)
|
||||||
|
add_library(lib3 ...)
|
||||||
|
|
||||||
|
target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
|
||||||
|
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
|
||||||
|
target_link_libraries(lib3 PRIVATE lib1 lib2)
|
||||||
|
|
||||||
|
# lib1 is associated with both feature2 and no feature. Without any override,
|
||||||
|
# this would result in a fatal error at generation time for lib3.
|
||||||
|
# Define an override to resolve the incompatible feature associations.
|
||||||
|
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
|
||||||
|
|
||||||
|
# lib1 will now be associated with feature2 instead when linking lib3
|
||||||
|
|
||||||
|
It is also possible to override any feature with the pre-defined ``DEFAULT``
|
||||||
|
library feature. This effectively discards any feature for that link item,
|
||||||
|
for that target only (``lib3`` in this example):
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
# When linking lib3, discard any library feature for lib1
|
||||||
|
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
|
||||||
|
|
||||||
|
See the :prop_tgt:`LINK_LIBRARY_OVERRIDE` target property for an alternative
|
||||||
|
way of overriding library features for multiple libraries at once. If both
|
||||||
|
properties are defined and specify an override for the same link item,
|
||||||
|
``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` takes precedence over
|
||||||
|
:prop_tgt:`LINK_LIBRARY_OVERRIDE`.
|
||||||
|
|
||||||
|
Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
|
|
||||||
|
For more information about library features, see the
|
||||||
|
:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
|
||||||
|
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
|
||||||
@ -0,0 +1,38 @@
|
|||||||
|
VERIFY_INTERFACE_HEADER_SETS
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Used to verify that all headers in a target's ``PUBLIC`` and ``INTERFACE``
|
||||||
|
header sets can be included on their own.
|
||||||
|
|
||||||
|
When this property is set to true, and the target is an object library, static
|
||||||
|
library, shared library, interface library, or executable with exports enabled,
|
||||||
|
and the target has one or more ``PUBLIC`` or ``INTERFACE`` header sets, an
|
||||||
|
object library target named ``<target_name>_verify_interface_header_sets`` is
|
||||||
|
created. This verification target has one source file per header in the
|
||||||
|
``PUBLIC`` and ``INTERFACE`` header sets. Each source file only includes its
|
||||||
|
associated header file. The verification target links against the original
|
||||||
|
target to get all of its usage requirements. The verification target has its
|
||||||
|
:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`
|
||||||
|
properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`,
|
||||||
|
:prop_tgt:`AUTOUIC`, and :prop_tgt:`UNITY_BUILD` properties set to false.
|
||||||
|
|
||||||
|
If the header's :prop_sf:`LANGUAGE` property is set, the value of that property
|
||||||
|
is used to determine the language with which to compile the header file.
|
||||||
|
Otherwise, if the target has any C++ sources, the header is compiled as C++.
|
||||||
|
Otherwise, if the target has any C sources, the header is compiled as C.
|
||||||
|
Otherwise, if C++ is enabled globally, the header is compiled as C++.
|
||||||
|
Otherwise, if C is enabled globally, the header is compiled as C. Otherwise,
|
||||||
|
the header file is not compiled.
|
||||||
|
|
||||||
|
If any verification targets are created, a top-level target called
|
||||||
|
``all_verify_interface_header_sets`` is created which depends on all
|
||||||
|
verification targets.
|
||||||
|
|
||||||
|
This property is initialized by the value of the
|
||||||
|
:variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable if it is set when
|
||||||
|
a target is created.
|
||||||
|
|
||||||
|
If the project wishes to control which header sets are verified by this
|
||||||
|
property, it can set :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY`.
|
||||||
@ -0,0 +1,21 @@
|
|||||||
|
VS_DOTNET_STARTUP_OBJECT
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Sets the startup object property in Visual Studio .NET targets.
|
||||||
|
The property value defines a full qualified class name (including package
|
||||||
|
name), for example: ``MyCompany.Package.MyStarterClass``.
|
||||||
|
|
||||||
|
If the property is unset, Visual Studio uses the first matching
|
||||||
|
``static void Main(string[])`` function signature by default. When more
|
||||||
|
than one ``Main()`` method is available in the current project, the property
|
||||||
|
becomes mandatory for building the project.
|
||||||
|
|
||||||
|
This property only works for Visual Studio 2010 and above;
|
||||||
|
it is ignored on other generators.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
set_property(TARGET ${TARGET_NAME} PROPERTY
|
||||||
|
VS_DOTNET_STARTUP_OBJECT "MyCompany.Package.MyStarterClass")
|
||||||
@ -0,0 +1,24 @@
|
|||||||
|
VS_NO_COMPILE_BATCHING
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Turn off compile batching for the target. Usually MSBuild calls the compiler
|
||||||
|
with multiple c/cpp files and compiler starts subprocesses for each file to
|
||||||
|
make the build parallel. If you want compiler to be invoked with one file at
|
||||||
|
a time set ``VS_NO_COMPILE_BATCHING`` to ON. If this flag is set MSBuild will
|
||||||
|
call compiler with one c/cpp file at a time. Useful when you want to use tool
|
||||||
|
that replaces the compiler, for example some build caching tool.
|
||||||
|
|
||||||
|
This property is initialized by the :variable:`CMAKE_VS_NO_COMPILE_BATCHING`
|
||||||
|
variable if it is set when a target is created.
|
||||||
|
|
||||||
|
Example
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
This shows setting the property for the target ``foo``.
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_library(foo SHARED foo.cpp)
|
||||||
|
set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON)
|
||||||
@ -0,0 +1,20 @@
|
|||||||
|
``SingleThreaded``
|
||||||
|
Compile without additional flags to use a single-threaded
|
||||||
|
statically-linked runtime library.
|
||||||
|
``SingleThreadedDLL``
|
||||||
|
Compile with ``-br`` or equivalent flag(s) to use a single-threaded
|
||||||
|
dynamically-linked runtime library. This is not available for Linux
|
||||||
|
targets.
|
||||||
|
``MultiThreaded``
|
||||||
|
Compile with ``-bm`` or equivalent flag(s) to use a multi-threaded
|
||||||
|
statically-linked runtime library.
|
||||||
|
``MultiThreadedDLL``
|
||||||
|
Compile with ``-bm -br`` or equivalent flag(s) to use a multi-threaded
|
||||||
|
dynamically-linked runtime library. This is not available for Linux
|
||||||
|
targets.
|
||||||
|
|
||||||
|
The value is ignored on non-Watcom compilers but an unsupported value will
|
||||||
|
be rejected as an error when using a compiler targeting the Watcom ABI.
|
||||||
|
|
||||||
|
The value may also be the empty string (``""``) in which case no runtime
|
||||||
|
library selection flag will be added explicitly by CMake.
|
||||||
@ -0,0 +1,34 @@
|
|||||||
|
WATCOM_RUNTIME_LIBRARY
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
Select the Watcom runtime library for use by compilers targeting the Watcom ABI.
|
||||||
|
|
||||||
|
The allowed values are:
|
||||||
|
|
||||||
|
.. include:: WATCOM_RUNTIME_LIBRARY-VALUES.txt
|
||||||
|
|
||||||
|
Use :manual:`generator expressions <cmake-generator-expressions(7)>` to
|
||||||
|
support per-configuration specification.
|
||||||
|
|
||||||
|
For example, the code:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_executable(foo foo.c)
|
||||||
|
set_property(TARGET foo PROPERTY
|
||||||
|
WATCOM_RUNTIME_LIBRARY "MultiThreaded")
|
||||||
|
|
||||||
|
selects for the target ``foo`` a multi-threaded statically-linked runtime
|
||||||
|
library.
|
||||||
|
|
||||||
|
If this property is not set then CMake uses the default value
|
||||||
|
``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other
|
||||||
|
platforms to select a Watcom runtime library.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
This property has effect only when policy :policy:`CMP0136` is set to ``NEW``
|
||||||
|
prior to the first :command:`project` or :command:`enable_language` command
|
||||||
|
that enables a language using a compiler targeting the Watcom ABI.
|
||||||
@ -0,0 +1,14 @@
|
|||||||
|
XCODE_XCCONFIG
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
If set, the :generator:`Xcode` generator will register the specified
|
||||||
|
file as a target-level XCConfig file. For global XCConfig files see
|
||||||
|
the :variable:`CMAKE_XCODE_XCCONFIG` variable.
|
||||||
|
|
||||||
|
This feature is intended to ease migration from native Xcode projects
|
||||||
|
to CMake projects.
|
||||||
|
|
||||||
|
Contents of ``XCODE_XCCONFIG`` may use
|
||||||
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||||
@ -0,0 +1,350 @@
|
|||||||
|
CMake 3.24 Release Notes
|
||||||
|
************************
|
||||||
|
|
||||||
|
.. only:: html
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Changes made since CMake 3.23 include the following.
|
||||||
|
|
||||||
|
New Features
|
||||||
|
============
|
||||||
|
|
||||||
|
Presets
|
||||||
|
-------
|
||||||
|
|
||||||
|
* :manual:`cmake-presets(7)` files now support schema version ``5``.
|
||||||
|
|
||||||
|
* :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro,
|
||||||
|
which expands to ``:`` or ``;`` based on the platform.
|
||||||
|
|
||||||
|
* :manual:`cmake-presets(7)` files gained support for specifying a
|
||||||
|
``testOutputTruncation`` field in test presets, which specifies the
|
||||||
|
truncation mode once the maximum test output size has been reached.
|
||||||
|
|
||||||
|
Generators
|
||||||
|
----------
|
||||||
|
|
||||||
|
* The :generator:`Green Hills MULTI` generator now generates build
|
||||||
|
rules to re-run CMake if any CMake files are updated.
|
||||||
|
|
||||||
|
* The :ref:`Visual Studio Generators` now support ``SYSTEM`` headers
|
||||||
|
when using VS 2019 Update 11 or later.
|
||||||
|
|
||||||
|
Command-Line
|
||||||
|
------------
|
||||||
|
|
||||||
|
* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove
|
||||||
|
any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/``
|
||||||
|
directory, when configuring a build tree, thus starting a new configuration
|
||||||
|
as if the build tree were freshly created.
|
||||||
|
|
||||||
|
* :manual:`cmake(1)` gained the ``--compile-no-warning-as-error`` command-line
|
||||||
|
option which causes the effects of the :prop_tgt:`COMPILE_WARNING_AS_ERROR`
|
||||||
|
target property and :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable
|
||||||
|
to be ignored.
|
||||||
|
|
||||||
|
* The :manual:`cmake(1)` ``--trace=json-v1`` trace format gained fields
|
||||||
|
``global_frame`` and ``line_end``.
|
||||||
|
|
||||||
|
* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect
|
||||||
|
a double dash (``--``) argument that acts as a delimiter indicating the end of
|
||||||
|
options. Any following arguments are treated as operands/positional arguments,
|
||||||
|
even if they begin with a dash ``-`` character.
|
||||||
|
|
||||||
|
* The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option
|
||||||
|
to keep the current local timestamp instead of extracting file timestamps
|
||||||
|
from the archive.
|
||||||
|
|
||||||
|
Compilers
|
||||||
|
---------
|
||||||
|
|
||||||
|
* LLVM's `flang`_ Fortran compiler is now supported on some platforms,
|
||||||
|
with compiler id ``LLVMFlang``.
|
||||||
|
|
||||||
|
.. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang
|
||||||
|
|
||||||
|
* ADSP compiler support (SHARC and Blackfin) now covers both CCES and
|
||||||
|
VDSP++ installations, with required configuration now done in the
|
||||||
|
compiler module itself rather than the ``Generic-ADSP`` platform module.
|
||||||
|
|
||||||
|
Platforms
|
||||||
|
---------
|
||||||
|
|
||||||
|
* A dedicated ``ADSP`` platform has been added
|
||||||
|
to replace the existing ``Generic-ADSP`` implementation.
|
||||||
|
This features automatic detection of the latest CCES/VDSP++ install
|
||||||
|
and compiler selection (``cc21k`` vs. ``ccblkfn``)
|
||||||
|
based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable.
|
||||||
|
|
||||||
|
Commands
|
||||||
|
--------
|
||||||
|
|
||||||
|
* The :command:`cmake_host_system_information` command, on Windows,
|
||||||
|
gained a ``QUERY WINDOWS_REGISTRY`` mode.
|
||||||
|
See its :ref:`Query Windows registry` section.
|
||||||
|
|
||||||
|
* The :command:`cmake_language` command gained a new
|
||||||
|
``SET_DEPENDENCY_PROVIDER`` sub-command. When a dependency provider is set,
|
||||||
|
calls to :command:`find_package` and :command:`FetchContent_MakeAvailable`
|
||||||
|
can be redirected through a custom command, which can choose to fulfill the
|
||||||
|
request directly, modify how the request is processed, or leave it to be
|
||||||
|
fulfilled by the built-in implementation. See :ref:`dependency_providers`.
|
||||||
|
|
||||||
|
* The :command:`file(DOWNLOAD)` command gained options ``RANGE_START`` and
|
||||||
|
``RANGE_END`` to specify a range of bytes to download. This can be
|
||||||
|
useful for downloading parts of big binary files.
|
||||||
|
|
||||||
|
* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
|
||||||
|
:command:`find_program`, and :command:`find_package` commands gained the
|
||||||
|
``NO_CMAKE_INSTALL_PREFIX`` option to control searching
|
||||||
|
:variable:`CMAKE_INSTALL_PREFIX`.
|
||||||
|
|
||||||
|
* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
|
||||||
|
:command:`find_program`, and :command:`find_package` commands gained the
|
||||||
|
ability to specify which Windows Registry views must be queried.
|
||||||
|
|
||||||
|
* The :command:`find_package` command gained a ``GLOBAL`` option that
|
||||||
|
allows for the promotion of imported targets to global scope for the
|
||||||
|
duration of the :command:`find_package` call.
|
||||||
|
|
||||||
|
* The :command:`if` command gained the capability to compare paths by
|
||||||
|
using the ``PATH_EQUAL`` operator. See policy :policy:`CMP0139`.
|
||||||
|
|
||||||
|
Variables
|
||||||
|
---------
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control
|
||||||
|
color diagnostics generated by compilers. This variable also controls
|
||||||
|
color build system messages with :ref:`Makefile Generators`, replacing
|
||||||
|
:variable:`CMAKE_COLOR_MAKEFILE`.
|
||||||
|
|
||||||
|
The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable was added to set
|
||||||
|
a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding
|
||||||
|
:prop_tgt:`COMPILE_WARNING_AS_ERROR` target property were added to enable
|
||||||
|
compilation with a compiler-specific flag to treat warnings as errors,
|
||||||
|
such as ``-Werror``.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
|
||||||
|
:prop_tgt:`CUDA_ARCHITECTURES` target property now support the
|
||||||
|
special ``native`` value to compile for the architectures(s)
|
||||||
|
of the host's GPU(s).
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to
|
||||||
|
toggle behavior of the :command:`find_package` command's new ``GLOBAL``
|
||||||
|
option.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` variable was added to toggle
|
||||||
|
behavior of the :command:`find_file`, :command:`find_library`,
|
||||||
|
:command:`find_path`, :command:`find_package`, and :command:`find_program`
|
||||||
|
commands' new ``NO_CMAKE_INSTALL_PREFIX`` option.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow
|
||||||
|
injecting custom code at the site of the first :command:`project` call,
|
||||||
|
after the host and target platform details have been determined.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable
|
||||||
|
was added to tell the :command:`try_compile` command not to
|
||||||
|
pass any platform variables to the test project.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable and
|
||||||
|
corresponding :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property
|
||||||
|
were added to enable build rules that verify all headers in header sets
|
||||||
|
can be used on their own.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_VS_NO_COMPILE_BATCHING` variable and corresponding
|
||||||
|
:prop_tgt:`VS_NO_COMPILE_BATCHING` target property were added to
|
||||||
|
tell :ref:`Visual Studio Generators` whether to disable compiler
|
||||||
|
parallelism and call the compiler with one source file at a time.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and
|
||||||
|
:prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to
|
||||||
|
select the runtime library used by compilers targeting the Watcom ABI.
|
||||||
|
See policy :policy:`CMP0136`.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_XCODE_XCCONFIG` variable and corresponding
|
||||||
|
:prop_tgt:`XCODE_XCCONFIG` target property were added to tell
|
||||||
|
the :generator:`Xcode` generator to handle ``xcconfig`` files.
|
||||||
|
|
||||||
|
Properties
|
||||||
|
----------
|
||||||
|
|
||||||
|
* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
|
||||||
|
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties
|
||||||
|
were added to express usage requirements affecting a consumer's
|
||||||
|
direct link dependencies.
|
||||||
|
|
||||||
|
* The :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was
|
||||||
|
added to specify which header sets should be verified by
|
||||||
|
:prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`.
|
||||||
|
|
||||||
|
* The :prop_tgt:`LINK_LIBRARIES` target property now supports
|
||||||
|
the :genex:`$<LINK_ONLY:...>` generator expression.
|
||||||
|
See policy :policy:`CMP0131`.
|
||||||
|
|
||||||
|
* The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to
|
||||||
|
tell :ref:`Visual Studio Generators` which startup class shall be used
|
||||||
|
when the program or project is executed. This is necessary when more
|
||||||
|
than one ``static void Main(string[])`` function signature is available
|
||||||
|
in a managed .NET project.
|
||||||
|
|
||||||
|
Modules
|
||||||
|
-------
|
||||||
|
|
||||||
|
* The :module:`ExternalProject` module :command:`ExternalProject_Add`
|
||||||
|
command gained a new ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for
|
||||||
|
controlling whether the timestamps of extracted contents are set to
|
||||||
|
match those in the archive when the ``URL`` download method is used.
|
||||||
|
Policy :policy:`CMP0135` was added to enable the option by default.
|
||||||
|
|
||||||
|
* The :module:`FetchContent` module and the :command:`find_package` command
|
||||||
|
now support integration capabilities:
|
||||||
|
|
||||||
|
* :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency
|
||||||
|
by calling :command:`find_package` first. A new
|
||||||
|
:variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether
|
||||||
|
this is done by default for all dependencies, is opt-in per dependency,
|
||||||
|
or is disabled entirely.
|
||||||
|
|
||||||
|
* :command:`find_package` can be re-routed to call
|
||||||
|
:command:`FetchContent_MakeAvailable` instead. A new read-only
|
||||||
|
:variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a
|
||||||
|
directory where config package files can be located to facilitate these
|
||||||
|
re-routed calls.
|
||||||
|
|
||||||
|
* The :module:`FindJNI` module now provides imported targets.
|
||||||
|
|
||||||
|
* The :module:`FindMatlab` module :command:`matlab_add_mex` function
|
||||||
|
gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable
|
||||||
|
automatic linking of MATLAB libraries.
|
||||||
|
|
||||||
|
* The :module:`FindVulkan` module now supports components to select which
|
||||||
|
VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers
|
||||||
|
and library.
|
||||||
|
|
||||||
|
* The :module:`FindZLIB` gained a new ``ZLIB_USE_STATIC_LIBS`` variable to
|
||||||
|
search only for static libraries.
|
||||||
|
|
||||||
|
Generator Expressions
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
* The :genex:`LINK_LIBRARY` generator expression was added to manage how
|
||||||
|
libraries are specified during the link step.
|
||||||
|
The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
|
||||||
|
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables are used to define
|
||||||
|
features usable by the :genex:`LINK_LIBRARY` generator expression.
|
||||||
|
Moreover, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
|
||||||
|
:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are
|
||||||
|
available to resolve incompatible features.
|
||||||
|
|
||||||
|
The :genex:`LINK_LIBRARY` generator expression can link frameworks in
|
||||||
|
various ways when targeting ``Apple`` platforms.
|
||||||
|
The following features were added:
|
||||||
|
|
||||||
|
* ``FRAMEWORK``
|
||||||
|
* ``NEEDED_FRAMEWORK``
|
||||||
|
* ``REEXPORT_FRAMEWORK``
|
||||||
|
* ``WEAK_FRAMEWORK``
|
||||||
|
|
||||||
|
The :genex:`LINK_LIBRARY` generator expression can link libraries in
|
||||||
|
various ways when targeting ``Apple`` platforms.
|
||||||
|
The following features were added:
|
||||||
|
|
||||||
|
* ``NEEDED_LIBRARY``
|
||||||
|
* ``REEXPORT_LIBRARY``
|
||||||
|
* ``WEAK_LIBRARY``
|
||||||
|
|
||||||
|
The :genex:`LINK_LIBRARY` generator expression gained the feature
|
||||||
|
``WHOLE_ARCHIVE`` to force load of all members in a static library.
|
||||||
|
This feature is supported on the following target platforms:
|
||||||
|
|
||||||
|
* all ``Apple`` variants
|
||||||
|
* ``Linux``
|
||||||
|
* all ``BSD`` variants
|
||||||
|
* ``SunOS``
|
||||||
|
* ``Windows``
|
||||||
|
* ``CYGWIN``
|
||||||
|
* ``MSYS``
|
||||||
|
|
||||||
|
* The :genex:`LINK_GROUP` generator expression was added to manage the
|
||||||
|
grouping of libraries during the link step. The
|
||||||
|
:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and
|
||||||
|
:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are used to define
|
||||||
|
features usable with the :genex:`LINK_GROUP` generator expression.
|
||||||
|
This release defines the ``RESCAN`` feature, which can be used to handle
|
||||||
|
circular references among static libraries when using toolchains for
|
||||||
|
Linux, BSD, SunOS and GNU toolchains for Windows.
|
||||||
|
|
||||||
|
* The :genex:`PATH` generator expression was added to manage paths.
|
||||||
|
|
||||||
|
* The :genex:`PATH_EQUAL` generator expression was added to manage path
|
||||||
|
comparisons.
|
||||||
|
|
||||||
|
* The :genex:`TARGET_BUNDLE_DIR_NAME` generator expression
|
||||||
|
was added to evaluate to the name of the bundle directory
|
||||||
|
for a given bundle target.
|
||||||
|
|
||||||
|
CTest
|
||||||
|
-----
|
||||||
|
|
||||||
|
* :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and
|
||||||
|
corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to
|
||||||
|
specify the truncation mode once the maximum test output size has been
|
||||||
|
reached. Possible values are ``tail`` (default), ``middle`` or ``head``.
|
||||||
|
|
||||||
|
CPack
|
||||||
|
-----
|
||||||
|
|
||||||
|
* The :cpack_gen:`CPack WIX Generator` gained a new variable,
|
||||||
|
:variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture
|
||||||
|
in order to support computers running Windows for ARM.
|
||||||
|
|
||||||
|
* CPack now supports the :variable:`CPACK_THREADS` option for ``zstd``
|
||||||
|
compression when compiled with libarchive 3.6 or higher. It is
|
||||||
|
supported by official CMake binaries available on `cmake.org`_.
|
||||||
|
|
||||||
|
Deprecated and Removed Features
|
||||||
|
===============================
|
||||||
|
|
||||||
|
* The :module:`CPack` module no longer enables the SLA by default in the
|
||||||
|
:cpack_gen:`CPack DragNDrop Generator`. See policy :policy:`CMP0133`
|
||||||
|
and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable.
|
||||||
|
|
||||||
|
* The deprecated :cpack_gen:`CPack PackageMaker Generator` has been removed.
|
||||||
|
|
||||||
|
* The :module:`FindGLUT` module no longer provides the undocumented
|
||||||
|
``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH`` result variables.
|
||||||
|
|
||||||
|
Other Changes
|
||||||
|
=============
|
||||||
|
|
||||||
|
* CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`,
|
||||||
|
etc. when enabling the corresponding language during the first CMake run in
|
||||||
|
a build directory. See policy :policy:`CMP0132`.
|
||||||
|
|
||||||
|
* The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
|
||||||
|
command now uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
|
||||||
|
and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
|
||||||
|
See policy :policy:`CMP0138`.
|
||||||
|
|
||||||
|
* The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles`
|
||||||
|
generators, when a compiler is not explicitly specified, now select
|
||||||
|
the first compiler (of any name) found in directories listed by the
|
||||||
|
``PATH`` environment variable.
|
||||||
|
|
||||||
|
* The :command:`try_compile` command
|
||||||
|
:ref:`whole-project <Try Compiling Whole Projects>` signature
|
||||||
|
now propagates platform variables. See policy :policy:`CMP0137`.
|
||||||
|
|
||||||
|
* The :command:`while` command now diagnoses errors during condition
|
||||||
|
evaluation. See policy :policy:`CMP0130`.
|
||||||
|
|
||||||
|
* The precompiled macOS binaries provided on `cmake.org`_ no longer attach a
|
||||||
|
SLA to the ``.dmg`` packages. This was removed because macOS 12 deprecated
|
||||||
|
the tools used to attach ``.dmg`` resources.
|
||||||
|
|
||||||
|
* A precompiled Windows ``arm64`` binary is now provided on `cmake.org`_.
|
||||||
|
|
||||||
|
.. _`cmake.org`: https://cmake.org/download/
|
||||||
@ -0,0 +1,11 @@
|
|||||||
|
CMAKE_ADSP_ROOT
|
||||||
|
---------------
|
||||||
|
|
||||||
|
.. versionadded:: 3.24
|
||||||
|
|
||||||
|
When :ref:`Cross Compiling for ADSP SHARC/Blackfin`,
|
||||||
|
this variable holds the absolute path to the latest CCES or VDSP++ install.
|
||||||
|
The directory is expected to contain the ``cc21k.exe`` and ``ccblkfn.exe`` compilers.
|
||||||
|
This will be set automatically if a default install of CCES or VDSP++ can be found.
|
||||||
|
|
||||||
|
See also the :envvar:`ADSP_ROOT` environment variable.
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue