You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
319 lines
13 KiB
319 lines
13 KiB
CMake 3.16 Release Notes
|
|
************************
|
|
|
|
.. only:: html
|
|
|
|
.. contents::
|
|
|
|
Changes made since CMake 3.15 include the following.
|
|
|
|
New Features
|
|
============
|
|
|
|
Languages
|
|
---------
|
|
|
|
* CMake learned to support the Objective C (``OBJC``) and Objective C++
|
|
(``OBJCXX``) languages. They may be enabled via the :command:`project`
|
|
and :command:`enable_language` commands. When ``OBJC`` or ``OBJCXX``
|
|
is enabled, source files with the ``.m`` or ``.mm``, respectively,
|
|
will be compiled as Objective C or C++. Otherwise they will be treated
|
|
as plain C++ sources as they were before.
|
|
|
|
Compilers
|
|
---------
|
|
|
|
* The ``Clang`` compiler is now supported on ``Solaris``.
|
|
|
|
Platforms
|
|
---------
|
|
|
|
* On AIX, executables using the :prop_tgt:`ENABLE_EXPORTS` target property
|
|
now produce a linker import file with a ``.imp`` extension in addition
|
|
to the executable file. Plugins (created via :command:`add_library` with
|
|
the ``MODULE`` option) that use :command:`target_link_libraries` to link
|
|
to the executable for its symbols are now linked using the import file.
|
|
The :command:`install(TARGETS)` command now installs the import file as
|
|
an ``ARCHIVE`` artifact.
|
|
|
|
* On AIX, runtime linking is no longer enabled by default. CMake provides
|
|
the linker enough information to resolve all symbols up front.
|
|
One may manually enable runtime linking for shared libraries and/or
|
|
loadable modules by adding ``-Wl,-G`` to their link flags
|
|
(e.g. in the :variable:`CMAKE_SHARED_LINKER_FLAGS` or
|
|
:variable:`CMAKE_MODULE_LINKER_FLAGS` variable).
|
|
One may manually enable runtime linking for executables by adding
|
|
``-Wl,-brtl`` to their link flags (e.g. in the
|
|
:variable:`CMAKE_EXE_LINKER_FLAGS` variable).
|
|
|
|
Command-Line
|
|
------------
|
|
|
|
* :manual:`cmake(1)` ``-E`` now supports ``true`` and ``false`` commands,
|
|
which do nothing while returning exit codes of 0 and 1, respectively.
|
|
|
|
* :manual:`cmake(1)` gained a ``--trace-redirect=<file>`` command line
|
|
option that can be used to redirect ``--trace`` output to a file instead
|
|
of ``stderr``.
|
|
|
|
* The :manual:`cmake(1)` ``--loglevel`` command line option has been
|
|
renamed to ``--log-level`` to make it consistent with the naming of other
|
|
command line options. The ``--loglevel`` option is still supported to
|
|
preserve backward compatibility.
|
|
|
|
Commands
|
|
--------
|
|
|
|
* The :command:`add_test` command learned the option ``COMMAND_EXPAND_LISTS``
|
|
which causes lists in the ``COMMAND`` argument to be expanded, including
|
|
lists created by generator expressions.
|
|
|
|
* The :command:`file` command learned a new sub-command,
|
|
``GET_RUNTIME_DEPENDENCIES``, which allows you to recursively get the list of
|
|
libraries linked by an executable or library. This sub-command is intended as
|
|
a replacement for :module:`GetPrerequisites`.
|
|
|
|
* The :command:`find_file`, :command:`find_library`, :command:`find_path`,
|
|
:command:`find_package`, and :command:`find_program` commands have learned to
|
|
check the following variables to control the default behavior for groups of
|
|
search locations:
|
|
|
|
* :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the default
|
|
behavior of searching the :variable:`<PackageName>_ROOT` variables.
|
|
|
|
* :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the default
|
|
behavior of searching the CMake-specific environment variables.
|
|
|
|
* :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the default
|
|
behavior of searching the standard system environment variables.
|
|
|
|
* :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the default behavior of
|
|
searching the CMake-specific cache variables.
|
|
|
|
* :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the default
|
|
behavior of searching the platform-specific CMake variables.
|
|
|
|
* The :command:`find_package` command has learned to check the
|
|
:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default
|
|
behavior of searching the CMake user package registry and to check the
|
|
:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable to control
|
|
the default behavior of searching the CMake system package registry.
|
|
|
|
* The :command:`message` command learned indentation control with the new
|
|
:variable:`CMAKE_MESSAGE_INDENT` variable.
|
|
|
|
* The :command:`target_precompile_headers` command was added to specify
|
|
a list of headers to precompile for faster compilation times.
|
|
|
|
Variables
|
|
---------
|
|
|
|
* The :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` variable has been
|
|
introduced to optionally initialize the
|
|
:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property.
|
|
|
|
* The :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` variable was added to
|
|
specify the resource encoding for the the :generator:`Eclipse CDT4` extra
|
|
generator.
|
|
|
|
* The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the
|
|
:prop_tgt:`UNITY_BUILD` target property to tell generators to batch
|
|
include source files for faster compilation times.
|
|
|
|
Properties
|
|
----------
|
|
|
|
* The :prop_tgt:`BUILD_RPATH` and :prop_tgt:`INSTALL_RPATH` target properties
|
|
now support :manual:`generator expressions <cmake-generator-expressions(7)>`.
|
|
|
|
* The :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` target property was
|
|
added to remove compiler-defined ``RPATH`` entries from a target.
|
|
This property is initialized by the
|
|
:variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` variable.
|
|
|
|
* The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to specify
|
|
a list of headers to precompile for faster compilation times.
|
|
Set it using the :command:`target_precompile_headers` command.
|
|
|
|
* The :prop_tgt:`UNITY_BUILD` target property was added to tell
|
|
generators to batch include source files for faster compilation
|
|
times.
|
|
|
|
* The :prop_tgt:`VS_CONFIGURATION_TYPE` target property now supports
|
|
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
|
|
|
* The :prop_tgt:`VS_DPI_AWARE` target property was added to tell
|
|
:ref:`Visual Studio Generators` to set the ``EnableDpiAwareness``
|
|
property in ``.vcxproj`` files.
|
|
|
|
* The :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` target property was
|
|
added to tell the :generator:`Xcode` generator to set the value of the
|
|
``Allow debugging when using document Versions Browser`` schema option.
|
|
|
|
Modules
|
|
-------
|
|
|
|
* The :module:`FindDoxygen` module :command:`doxygen_add_docs` command
|
|
gained a new ``USE_STAMP_FILE`` option. When this option present,
|
|
the custom target created by the command will only re-run Doxygen if
|
|
any of the source files have changed since the last successful run.
|
|
|
|
* The :module:`FindGnuTLS` module now provides an imported target.
|
|
|
|
* The :module:`FindPackageHandleStandardArgs` module
|
|
:command:`find_package_handle_standard_args` command gained
|
|
a new ``REASON_FAILURE_MESSAGE`` option to specify a message
|
|
giving the reason for the failure.
|
|
|
|
* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro
|
|
now defines a ``<prefix>_MODULE_NAME`` result variable containing the
|
|
first matching module name.
|
|
|
|
* The :module:`FindPython3` and :module:`FindPython` modules gained
|
|
options to control which ``ABIs`` will be searched.
|
|
|
|
* The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython`
|
|
modules now support direct specification of artifacts via cache entries.
|
|
|
|
Autogen
|
|
-------
|
|
|
|
* When using :prop_tgt:`AUTOMOC`, CMake now generates the ``-p`` path prefix
|
|
option for ``moc``. This ensures that ``moc`` output files are identical
|
|
on different build setups (given, that the headers compiled by ``moc`` are
|
|
in an :command:`include directory <target_include_directories>`).
|
|
Also it ensures that ``moc`` output files will compile correctly when the
|
|
source and/or build directory is a symbolic link.
|
|
|
|
The ``moc`` path prefix generation behavior can be configured by setting
|
|
the new :variable:`CMAKE_AUTOMOC_PATH_PREFIX` variable and/or
|
|
:prop_tgt:`AUTOMOC_PATH_PREFIX` target property.
|
|
|
|
CTest
|
|
-----
|
|
|
|
* :manual:`ctest(1)` now has the ability to schedule tests based on resource
|
|
requirements for each test. See :ref:`ctest-resource-allocation` for
|
|
details.
|
|
|
|
* A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added.
|
|
This property is similar to :prop_test:`FAIL_REGULAR_EXPRESSION` and
|
|
:prop_test:`PASS_REGULAR_EXPRESSION`, but with the same meaning as
|
|
:prop_test:`SKIP_RETURN_CODE`. This is useful, for example, in cases where
|
|
the user has no control over the return code of the test. For example, in
|
|
Catch2, the return value is the number of assertion failed, therefore it is
|
|
impossible to use it for :prop_test:`SKIP_RETURN_CODE`.
|
|
|
|
CPack
|
|
-----
|
|
|
|
* :manual:`cpack(1)` learned support for multiple configurations for ``-C``
|
|
option.
|
|
|
|
* The :cpack_gen:`CPack DEB Generator` is now able to format generic text
|
|
(usually used as the description for multiple CPack generators) according
|
|
to the `Debian Policy Manual`_. See the
|
|
:variable:`CPACK_PACKAGE_DESCRIPTION_FILE` and
|
|
:variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables.
|
|
|
|
* The :cpack_gen:`CPack Archive Generator` learned to generate ``.tar.zst``
|
|
packages with Zstandard compression.
|
|
|
|
.. _`Debian Policy Manual`: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description
|
|
|
|
Deprecated and Removed Features
|
|
===============================
|
|
|
|
* An explicit deprecation diagnostic was added for policy ``CMP0067``
|
|
(``CMP0066`` and below were already deprecated).
|
|
The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
|
|
of all policies are deprecated and that projects should port to the
|
|
NEW behaviors.
|
|
|
|
* The :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable has been
|
|
deprecated. Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable
|
|
instead.
|
|
|
|
* The :module:`GetPrerequisites` module has been deprecated, as it has been
|
|
superceded by :command:`file(GET_RUNTIME_DEPENDENCIES)`.
|
|
|
|
* The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the
|
|
new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable.
|
|
|
|
Other Changes
|
|
=============
|
|
|
|
* The :manual:`cmake(1)` ``-C <initial-cache>`` option now evaluates the
|
|
initial cache script with :variable:`CMAKE_SOURCE_DIR` and
|
|
:variable:`CMAKE_BINARY_DIR` set to the top-level source and build trees.
|
|
|
|
* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool,
|
|
when given the path to a symlink to a directory, now removes just
|
|
the symlink. It no longer removes content of the linked directory.
|
|
|
|
* The :manual:`ctest(1)` ``--build-makeprogram`` command-line option now
|
|
specifies the make program used when configuring a project with the
|
|
:generator:`Ninja` generator or the :ref:`Makefile Generators`.
|
|
|
|
* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
|
|
has been updated so that ``GIT_SUBMODULES ""`` initializes no submodules.
|
|
See policy :policy:`CMP0097`.
|
|
|
|
* The :module:`FindGTest` module has been updated to recognize
|
|
MSVC build trees generated by GTest 1.8.1.
|
|
|
|
* The :command:`project` command no longer strips leading zeros in version
|
|
components. See policy :policy:`CMP0096`.
|
|
|
|
* The Qt Compressed Help file is now named ``CMake.qch``, which no longer
|
|
contains the release version in the file name. When CMake is upgraded
|
|
in-place, the name and location of this file will remain constant.
|
|
Tools such as IDEs, help viewers, etc. should now be able to refer to this
|
|
file at a fixed location that remains valid across CMake upgrades.
|
|
|
|
* ``RPATH`` entries are properly escaped in the generated CMake scripts
|
|
used for installation. See policy :policy:`CMP0095`.
|
|
|
|
* When using :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` on Windows the
|
|
auto-generated exports are now updated only when the object files
|
|
providing the symbols are updated.
|
|
|
|
Updates
|
|
=======
|
|
|
|
Changes made since CMake 3.16.0 include the following.
|
|
|
|
3.16.2
|
|
------
|
|
|
|
* CMake 3.16.0 and 3.16.1 processed ``.hh`` files with :prop_tgt:`AUTOMOC`.
|
|
This was a behavior change from CMake 3.15 and below that can break
|
|
existing projects, so it has been reverted as of 3.16.2.
|
|
|
|
3.16.5
|
|
------
|
|
|
|
* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
|
|
modules no longer create cache entries for ``Python{,2,3}_LIBRARY_RELEASE``
|
|
and ``Python{,2,3}_LIBRARY_DEBUG``. Those values are always computed from
|
|
other results and so should not be cached. The entries were created by
|
|
CMake 3.16.0 through 3.16.4 but were always ``FORCE``-set and could not
|
|
be meaningfully edited by users.
|
|
|
|
Additionally, the modules no longer expose their internal ``_Python*``
|
|
cache entries publicly. CMake 3.16.0 through 3.16.4 accidentally
|
|
made them visible as advanced cache entries.
|
|
|
|
3.16.7
|
|
------
|
|
|
|
* Selection of the Objective C or C++ compiler now considers the
|
|
:envvar:`CC` or :envvar:`CXX` environment variable if the
|
|
:envvar:`OBJC` or :envvar:`OBJCXX` environment variable is not set.
|
|
|
|
* The :module:`FindPkgConfig` module now extracts include directories
|
|
prefixed with ``-isystem`` into the ``*_INCLUDE_DIRS`` variables and
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target properties.
|
|
Previously they would be places in ``*_CFLAGS_OTHER`` variables and
|
|
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
|