CMake 3.16 Release Notes ************************ .. only:: html .. contents:: Changes made since CMake 3.15 include the following. * The :command:`find_package` command has learned to check the following variables to control searching * :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` - Controls the searching the cmake user registry. * The :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` has been deprecated. Instead use :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` * A new target property, :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH`, was added which removes compiler-defined rpaths from a target. This property is initialized by :variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH`. * 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`. * The command :command:`add_test` learned the option ``COMMAND_EXPAND_LISTS`` which causes lists in the ``COMMAND`` argument to be expanded, including lists created by generator expressions. * 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). * 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 `). 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. * :prop_tgt:`BUILD_RPATH` and :prop_tgt:`INSTALL_RPATH` now support :manual:`generator expressions `. * :manual:`cmake(1)` ``-E`` now supports ``true`` and ``false`` commands, which do nothing while returning exit codes of 0 and 1, respectively. * The :manual:`cmake(1)` ``-C `` 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 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 intermediary CMake install script. See policy :policy:`CMP0095`. * CPack learned :variable:`CPACK_INSTALL_CMAKE_CONFIGURATIONS` to control what configurations going to be packaged for multi-configuration generators. * The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable. * The :cpack_gen:`CPack Archive Generator` learned to generate `.tar.zst` packages with Zstandard compression. * :manual:`ctest(1)` ``--build-makeprogram`` now specifies the make program used when configuring a project with the Ninja and Makefiles generators in addition to building it. * :manual:`ctest(1)` now has the ability to serialize tests based on hardware requirements for each test. See :ref:`ctest-hardware-allocation` for details. * Variable :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` has been introduced to optionally initialize the :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property. * 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 :command:`doxygen_add_docs` command from the :module:`FindDoxygen` module 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 :generator:`Eclipse CDT4` extra generator gained a new :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` option to specify the resource encoding. * The :module:`ExternalProject` module's ``ExternalProject_Add`` command has been updated so that ``GIT_SUBMODULES ""`` initializes no submodules. See policy :policy:`CMP0097`. * The :module:`FindGnuTLS` module now provides an imported target. * The :module:`FindPkgConfig` module :command:`pkg_search_module` macro now defines a ``_MODULE_NAME`` result variable containing the first matching module name. * Modules :module:`FindPython3` and :module:`FindPython` gain the capability to control which ``ABIs`` will be searched. * Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` gain the capability to specify directly artifacts. * Modules :module:`FindPackageHandleStandardArgs` gains the capability to specify a message giving the reason for the failure. * 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 :module:`GetPrerequisites` module has been deprecated, as it has been superceded by :command:`file(GET_RUNTIME_DEPENDENCIES)`. * 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 searching * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the searching the cmake-specific environment variables. * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the searching the cmake-specific cache variables. * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the searching cmake platform specific variables. * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the searching of :variable:`_ROOT` variables. * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the searching the standard system environment variables. * The :module:`FindGTest` module has been updated to recognize MSVC build trees generated by GTest 1.8.1. * The :command:`message` command learned indentation control with the new :variable:`CMAKE_MESSAGE_INDENT` variable. * 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. * New variables :variable:`CMAKE__LINK_LIBRARY_FLAG`, :variable:`CMAKE__LINK_LIBRARY_FILE_FLAG`, and :variable:`CMAKE__LINK_LIBRARY_SUFFIX` allow control of the flag used to specify linking to a library on a per-language basis. This is useful for mixed-language projects where the different drivers may use different flags. * The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to tell generators to use a list of precompile headers for faster compilation times. * The :command:`project` no longer strips leading zeros in version components. See policy :policy:`CMP0096`. * 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 ``Clang`` compiler is now supported on ``Solaris``. * :manual:`cmake(1)` gained a ``--trace-redirect=`` command line option that can be used to redirect ``--trace`` output to a file instead of ``stderr``. * The :prop_tgt:`UNITY_BUILD` target property was added to tell generators to batch include source files for faster compilation times. * :prop_tgt:`VS_CONFIGURATION_TYPE` now supports :manual:`generator expressions `. * The :prop_tgt:`VS_DPI_AWARE` target property was added to tell :ref:`Visual Studio Generators` to set the ``EnableDpiAwareness`` property in ``.vcxproj`` files. * On Windows, existing auto generated exports are now only updated if the modified time stamp of the exports is not newer than any modified time stamp of the input files. * The Xcode generator learnt to set the value of the ``Allow debugging when using document Versions Browser`` schema option with the :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` target property.