Help/release/3.16.rst

   1 CMake 3.16 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.15 include the following.
   9
  10 New Features
  11 ============
  12
  13 Languages
  14 ---------
  15
  16 * CMake learned to support the Objective C (``OBJC``) and Objective C++
  17   (``OBJCXX``) languages.  They may be enabled via the :command:`project`
  18   and :command:`enable_language` commands.  When ``OBJC`` or ``OBJCXX``
  19   is enabled, source files with the ``.m`` or ``.mm``, respectively,
  20   will be compiled as Objective C or C++.  Otherwise they will be treated
  21   as plain C++ sources as they were before.
  22
  23 Compilers
  24 ---------
  25
  26 * The ``Clang`` compiler is now supported on ``Solaris``.
  27
  28 Platforms
  29 ---------
  30
  31 * On AIX, executables using the :prop_tgt:`ENABLE_EXPORTS` target property
  32   now produce a linker import file with a ``.imp`` extension in addition
  33   to the executable file.  Plugins (created via :command:`add_library` with
  34   the ``MODULE`` option) that use :command:`target_link_libraries` to link
  35   to the executable for its symbols are now linked using the import file.
  36   The :command:`install(TARGETS)` command now installs the import file as
  37   an ``ARCHIVE`` artifact.
  38
  39 * On AIX, runtime linking is no longer enabled by default.  CMake provides
  40   the linker enough information to resolve all symbols up front.
  41   One may manually enable runtime linking for shared libraries and/or
  42   loadable modules by adding ``-Wl,-G`` to their link flags
  43   (e.g. in the :variable:`CMAKE_SHARED_LINKER_FLAGS` or
  44   :variable:`CMAKE_MODULE_LINKER_FLAGS` variable).
  45   One may manually enable runtime linking for executables by adding
  46   ``-Wl,-brtl`` to their link flags (e.g. in the
  47   :variable:`CMAKE_EXE_LINKER_FLAGS` variable).
  48
  49 Command-Line
  50 ------------
  51
  52 * :manual:`cmake(1)` ``-E`` now supports ``true`` and ``false`` commands,
  53   which do nothing while returning exit codes of 0 and 1, respectively.
  54
  55 * :manual:`cmake(1)` gained a ``--trace-redirect=<file>`` command line
  56   option that can be used to redirect ``--trace`` output to a file instead
  57   of ``stderr``.
  58
  59 * The :manual:`cmake(1)` ``--loglevel`` command line option has been
  60   renamed to ``--log-level`` to make it consistent with the naming of other
  61   command line options.  The ``--loglevel`` option is still supported to
  62   preserve backward compatibility.
  63
  64 Commands
  65 --------
  66
  67 * The :command:`add_test` command learned the option ``COMMAND_EXPAND_LISTS``
  68   which causes lists in the ``COMMAND`` argument to be expanded, including
  69   lists created by generator expressions.
  70
  71 * The :command:`file` command learned a new sub-command,
  72   ``GET_RUNTIME_DEPENDENCIES``, which allows you to recursively get the list of
  73   libraries linked by an executable or library. This sub-command is intended as
  74   a replacement for :module:`GetPrerequisites`.
  75
  76 * The :command:`find_file`, :command:`find_library`, :command:`find_path`,
  77   :command:`find_package`, and :command:`find_program` commands have learned to
  78   check the following variables to control the default behavior for groups of
  79   search locations:
  80
  81   * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the default
  82     behavior of searching the :variable:`<PackageName>_ROOT` variables.
  83
  84   * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the default
  85     behavior of searching the CMake-specific environment variables.
  86
  87   * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the default
  88     behavior of searching the standard system environment variables.
  89
  90   * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the default behavior of
  91     searching the CMake-specific cache variables.
  92
  93   * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the default
  94     behavior of searching the platform-specific CMake variables.
  95
  96 * The :command:`find_package` command has learned to check the
  97   :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default
  98   behavior of searching the CMake user package registry and to check the
  99   :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable to control
 100   the default behavior of searching the CMake system package registry.
 101
 102 * The :command:`message` command learned indentation control with the new
 103   :variable:`CMAKE_MESSAGE_INDENT` variable.
 104
 105 * The :command:`target_precompile_headers` command was added to specify
 106   a list of headers to precompile for faster compilation times.
 107
 108 Variables
 109 ---------
 110
 111 * The :variable:`CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS` variable has been
 112   introduced to optionally initialize the
 113   :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property.
 114
 115 * The :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` variable was added to
 116   specify the resource encoding for the the :generator:`Eclipse CDT4` extra
 117   generator.
 118
 119 * The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the
 120   :prop_tgt:`UNITY_BUILD` target property to tell generators to batch
 121   include source files for faster compilation times.
 122
 123 Properties
 124 ----------
 125
 126 * The :prop_tgt:`BUILD_RPATH` and :prop_tgt:`INSTALL_RPATH` target properties
 127   now support :manual:`generator expressions <cmake-generator-expressions(7)>`.
 128
 129 * The :prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` target property was
 130   added to remove compiler-defined ``RPATH`` entries from a target.
 131   This property is initialized by the
 132   :variable:`CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH` variable.
 133
 134 * The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to specify
 135   a list of headers to precompile for faster compilation times.
 136   Set it using the :command:`target_precompile_headers` command.
 137
 138 * The :prop_tgt:`UNITY_BUILD` target property was added to tell
 139   generators to batch include source files for faster compilation
 140   times.
 141
 142 * The :prop_tgt:`VS_CONFIGURATION_TYPE` target property now supports
 143   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 144
 145 * The :prop_tgt:`VS_DPI_AWARE` target property was added to tell
 146   :ref:`Visual Studio Generators` to set the ``EnableDpiAwareness``
 147   property in ``.vcxproj`` files.
 148
 149 * The :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` target property was
 150   added to tell the :generator:`Xcode` generator to set the value of the
 151   ``Allow debugging when using document Versions Browser`` schema option.
 152
 153 Modules
 154 -------
 155
 156 * The :module:`FindDoxygen` module :command:`doxygen_add_docs` command
 157   gained a new ``USE_STAMP_FILE`` option.  When this option present,
 158   the custom target created by the command will only re-run Doxygen if
 159   any of the source files have changed since the last successful run.
 160
 161 * The :module:`FindGnuTLS` module now provides an imported target.
 162
 163 * The :module:`FindPackageHandleStandardArgs` module
 164   :command:`find_package_handle_standard_args` command gained
 165   a new ``REASON_FAILURE_MESSAGE`` option to specify a message
 166   giving the reason for the failure.
 167
 168 * The :module:`FindPkgConfig` module :command:`pkg_search_module` macro
 169   now defines a ``<prefix>_MODULE_NAME`` result variable containing the
 170   first matching module name.
 171
 172 * The :module:`FindPython3` and :module:`FindPython` modules gained
 173   options to control which ``ABIs`` will be searched.
 174
 175 * The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython`
 176   modules now support direct specification of artifacts via cache entries.
 177
 178 Autogen
 179 -------
 180
 181 * When using :prop_tgt:`AUTOMOC`, the new :variable:`CMAKE_AUTOMOC_PATH_PREFIX`
 182   variable or :prop_tgt:`AUTOMOC_PATH_PREFIX` target property may be enabled
 183   to generate the ``-p`` path prefix
 184   option for ``moc``.  This ensures that ``moc`` output files are identical
 185   on different build setups (given, that the headers compiled by ``moc`` are
 186   in an :command:`include directory <target_include_directories>`).
 187   Also it ensures that ``moc`` output files will compile correctly when the
 188   source and/or build directory is a symbolic link.
 189
 190 CTest
 191 -----
 192
 193 * :manual:`ctest(1)` now has the ability to schedule tests based on resource
 194   requirements for each test. See :ref:`ctest-resource-allocation` for
 195   details.
 196
 197 * A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added.
 198   This property is similar to :prop_test:`FAIL_REGULAR_EXPRESSION` and
 199   :prop_test:`PASS_REGULAR_EXPRESSION`, but with the same meaning as
 200   :prop_test:`SKIP_RETURN_CODE`. This is useful, for example, in cases where
 201   the user has no control over the return code of the test. For example, in
 202   Catch2, the return value is the number of assertion failed, therefore it is
 203   impossible to use it for :prop_test:`SKIP_RETURN_CODE`.
 204
 205 CPack
 206 -----
 207
 208 * :manual:`cpack(1)` learned support for multiple configurations for ``-C``
 209   option.
 210
 211 * The :cpack_gen:`CPack DEB Generator` is now able to format generic text
 212   (usually used as the description for multiple CPack generators) according
 213   to the `Debian Policy Manual`_.  See the
 214   :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` and
 215   :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables.
 216
 217 * The :cpack_gen:`CPack Archive Generator` learned to generate ``.tar.zst``
 218   packages with Zstandard compression.
 219
 220 .. _`Debian Policy Manual`: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description
 221
 222 Deprecated and Removed Features
 223 ===============================
 224
 225 * An explicit deprecation diagnostic was added for policy ``CMP0067``
 226   (``CMP0066`` and below were already deprecated).
 227   The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
 228   of all policies are deprecated and that projects should port to the
 229   NEW behaviors.
 230
 231 * The :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable has been
 232   deprecated.  Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable
 233   instead.
 234
 235 * The :module:`GetPrerequisites` module has been deprecated, as it has been
 236   superceded by :command:`file(GET_RUNTIME_DEPENDENCIES)`.
 237
 238 * The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the
 239   new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable.
 240
 241 Other Changes
 242 =============
 243
 244 * The :manual:`cmake(1)` ``-C <initial-cache>`` option now evaluates the
 245   initial cache script with :variable:`CMAKE_SOURCE_DIR` and
 246   :variable:`CMAKE_BINARY_DIR` set to the top-level source and build trees.
 247
 248 * The :manual:`cmake(1)` ``-E remove_directory`` command-line tool,
 249   when given the path to a symlink to a directory, now removes just
 250   the symlink.  It no longer removes content of the linked directory.
 251
 252 * The :manual:`ctest(1)`  ``--build-makeprogram`` command-line option now
 253   specifies the make program used when configuring a project with the
 254   :generator:`Ninja` generator or the :ref:`Makefile Generators`.
 255
 256 * The :module:`ExternalProject` module :command:`ExternalProject_Add` command
 257   has been updated so that ``GIT_SUBMODULES ""`` initializes no submodules.
 258   See policy :policy:`CMP0097`.
 259
 260 * The :module:`FindGTest` module has been updated to recognize
 261   MSVC build trees generated by GTest 1.8.1.
 262
 263 * The :command:`project` command no longer strips leading zeros in version
 264   components.  See policy :policy:`CMP0096`.
 265
 266 * The Qt Compressed Help file is now named ``CMake.qch``, which no longer
 267   contains the release version in the file name.  When CMake is upgraded
 268   in-place, the name and location of this file will remain constant.
 269   Tools such as IDEs, help viewers, etc. should now be able to refer to this
 270   file at a fixed location that remains valid across CMake upgrades.
 271
 272 * ``RPATH`` entries are properly escaped in the generated CMake scripts
 273   used for installation.  See policy :policy:`CMP0095`.
 274
 275 * When using :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` on Windows the
 276   auto-generated exports are now updated only when the object files
 277   providing the symbols are updated.
 278
 279 Updates
 280 =======
 281
 282 Changes made since CMake 3.16.0 include the following.
 283
 284 3.16.2
 285 ------
 286
 287 * CMake 3.16.0 and 3.16.1 processed ``.hh`` files with :prop_tgt:`AUTOMOC`.
 288   This was a behavior change from CMake 3.15 and below that can break
 289   existing projects, so it has been reverted as of 3.16.2.
 290
 291 3.16.5
 292 ------
 293
 294 * The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
 295   modules no longer create cache entries for ``Python{,2,3}_LIBRARY_RELEASE``
 296   and ``Python{,2,3}_LIBRARY_DEBUG``.  Those values are always computed from
 297   other results and so should not be cached.  The entries were created by
 298   CMake 3.16.0 through 3.16.4 but were always ``FORCE``-set and could not
 299   be meaningfully edited by users.
 300
 301   Additionally, the modules no longer expose their internal ``_Python*``
 302   cache entries publicly.  CMake 3.16.0 through 3.16.4 accidentally
 303   made them visible as advanced cache entries.
 304
 305 3.16.7
 306 ------
 307
 308 * Selection of the Objective C or C++ compiler now considers the
 309   :envvar:`CC` or :envvar:`CXX` environment variable if the
 310   :envvar:`OBJC` or :envvar:`OBJCXX` environment variable is not set.
 311
 312 * The :module:`FindPkgConfig` module now extracts include directories
 313   prefixed with ``-isystem`` into the ``*_INCLUDE_DIRS`` variables and
 314   :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target properties.
 315   Previously they would be places in ``*_CFLAGS_OTHER`` variables and
 316   :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
 317
 318 3.16.9
 319 ------
 320
 321 * The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to
 322   ``OFF`` because this feature can break existing projects that have
 323   identically named header files in different include directories.
 324   This restores compatibility with behavior of CMake 3.15 and below.