Help/release/3.18.rst

   1 CMake 3.18 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.17 include the following.
   9
  10 New Features
  11 ============
  12
  13 Languages
  14 ---------
  15
  16 * The ``CUDA`` language can now be compiled using Clang on non-Windows
  17   platforms. Separable compilation is not yet supported on any platform.
  18
  19 Command-Line
  20 ------------
  21
  22 * :manual:`cmake(1)` gained support for profiling of CMake scripts through
  23   the parameters ``--profiling-output`` and ``--profiling-format``.
  24
  25 * :manual:`cmake(1)` gained a ``cat`` command line
  26   option that can be used to concatenate files and print them
  27   on standard output.
  28
  29 Commands
  30 --------
  31
  32 * The :command:`add_library` and :command:`add_executable` commands
  33   learned to create :ref:`Alias Targets` referencing non-``GLOBAL``
  34   :ref:`Imported Targets`.
  35
  36 * The :command:`cmake_language()` command was added for meta-operations on
  37   scripted or built-in commands, starting with a mode to ``CALL`` other
  38   commands, and ``EVAL CODE`` to inplace evaluate a CMake script.
  39
  40 * The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
  41   and ``ECHO_ERROR_VARIABLE`` options.
  42
  43 * The :command:`export` command now raise an error if used multiple times with
  44   same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.
  45
  46 * The :command:`file` command gained the ``ARCHIVE_CREATE`` and
  47   ``ARCHIVE_EXTRACT`` subcommands to expose the :manual:`cmake(1)` ``-E tar``
  48   functionality to CMake scripting code.
  49
  50 * The :command:`file(CONFIGURE)` subcommand was created in order to replicate
  51   the :command:`configure_file` functionality without resorting to a
  52   pre-existing file on disk as input. The content is instead passed as a
  53   string.
  54
  55 * The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO``
  56   options to control server certificate verification.
  57
  58 * The :command:`find_program`, :command:`find_library`, :command:`find_path`
  59   and :command:`find_file` commands gained a new ``REQUIRED`` option that will
  60   stop processing with an error message if nothing is found.
  61
  62 * The :command:`get_property` command with ``SOURCE`` scope gained the
  63   ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to get a property
  64   from the provided directory scope.
  65
  66 * The :command:`get_source_file_property` command gained the ``DIRECTORY``
  67   and ``TARGET_DIRECTORY`` options to get a property from the
  68   provided directory scope.
  69
  70 * The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort
  71   option to sort using natural order (see ``strverscmp(3)`` manual).
  72
  73 * The :command:`set_property` command with the ``SOURCE`` scope gained the
  74   ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to set properties
  75   in the provided directory scopes.
  76
  77 * The :command:`set_source_files_properties` command gained the ``DIRECTORY``
  78   and ``TARGET_DIRECTORY`` options to set properties in the provided
  79   directory scopes.
  80
  81 * The :command:`string` command learned a new ``HEX`` sub-command, which
  82   converts strings into their hexadecimal representation.
  83
  84 Variables
  85 ---------
  86
  87 * A :variable:`CMAKE_CUDA_ARCHITECTURES` variable was added to specify
  88   CUDA output architectures.  Users are encouraged to use this instead of
  89   specifying options manually, as this approach is compiler-agnostic.
  90   The variable is initialized automatically when
  91   :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
  92   The variable is used to initialize the new :prop_tgt:`CUDA_ARCHITECTURES`
  93   target property.  See policy :policy:`CMP0104`.
  94
  95 * The :variable:`CMAKE_PCH_WARN_INVALID` variable was added to initialize the
  96   :prop_tgt:`PCH_WARN_INVALID` target property to allow the removal of the
  97   precompiled header invalid warning.
  98
  99 Properties
 100 ----------
 101
 102 * The :prop_tgt:`CUDA_ARCHITECTURES` target property was added to specify
 103   CUDA output architectures. Users are encouraged to use this instead of
 104   specifying options manually, as this approach is compiler-agnostic.
 105   The property is initialized by the new :variable:`CMAKE_CUDA_ARCHITECTURES`
 106   variable.  See policy :policy:`CMP0104`.
 107
 108 * The :prop_tgt:`Fortran_PREPROCESS` target property and
 109   :prop_sf:`Fortran_PREPROCESS` source-file property were added to
 110   control preprocessing of Fortran source files.
 111
 112 * The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property
 113   and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
 114   variable were created to allow adding a postfix to the name of a
 115   framework file name when using a multi-config generator.
 116
 117 * The :prop_sf:`OBJECT_OUTPUTS` source file property now supports
 118   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 119
 120 * The :prop_tgt:`PCH_WARN_INVALID` target property was added to allow the
 121   removal of the precompiled header invalid warning.
 122
 123 * The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell
 124   generators which algorithm to use for grouping included source
 125   files.
 126
 127 * The :prop_tgt:`VS_SOURCE_SETTINGS_<tool>` target property was added
 128   to tell :ref:`Visual Studio Generators` for VS 2010 and above to add
 129   metadata to non-built source files using ``<tool>``.
 130
 131 * The :prop_sf:`VS_SETTINGS` source file property was added to tell
 132   :ref:`Visual Studio Generators` for VS 2010 and above to add
 133   metadata to a non-built source file.
 134
 135 * The :prop_tgt:`VS_PLATFORM_TOOLSET` target property was added to tell
 136   :ref:`Visual Studio Generators` for VS 2010 and above to override
 137   the platform toolset.
 138
 139 * The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell
 140   :ref:`Visual Studio Generators` for VS 2010 and above to mark a
 141   target for deployment even when not building for Windows Phone/Store/CE.
 142
 143 Modules
 144 -------
 145
 146 * The :module:`CheckLinkerFlag` module has been added to provide a
 147   facility to check validity of link flags.
 148
 149 * The :module:`ExternalProject` module :command:`ExternalProject_Add` command
 150   gained a new ``GIT_REMOTE_UPDATE_STRATEGY`` keyword.  This can be used to
 151   specify how failed rebase operations during a git update should be handled.
 152   The ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` variable was also added as a
 153   global default and is honored by both the :module:`ExternalProject` and
 154   :module:`FetchContent` modules.
 155
 156 * The :module:`FetchContent` module :command:`FetchContent_Declare` command
 157   now supports a ``SOURCE_SUBDIR`` option.  It can be used to direct
 158   :command:`FetchContent_MakeAvailable` to look in a different location
 159   for the ``CMakeLists.txt`` file.
 160
 161 * The :module:`FindBLAS` module now provides an imported target.
 162
 163 * The :module:`FindCUDAToolkit` module:
 164
 165   * gained the variable
 166     ``CUDAToolkit_LIBRARY_ROOT``, which is the directory containing the
 167     ``nvvm`` directory and ``version.txt``.
 168
 169   * uses toolkit and library root found during ``CUDA`` compiler detection.
 170
 171 * The :module:`FindLAPACK` module now provides an imported target.
 172
 173 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
 174   modules:
 175
 176   * gained the possibility to create per-artifact cache variables for
 177     interactive editing in :manual:`cmake-gui(1)` and :manual:`ccmake(1)`.
 178
 179   * gained sub-components ``Development.Module`` and
 180     ``Development.Embed`` under the ``Development`` component.
 181
 182   * gained the capability to specify which Python implementations to find,
 183     including ``IronPython`` and ``PyPy``.
 184
 185 * The :module:`FindRuby` module input and output variables were all renamed
 186   from ``RUBY_`` to ``Ruby_`` for consistency with other find modules.
 187   Input variables of the old case will be honored if provided, and output
 188   variables of the old case are always provided.
 189
 190 * The :module:`FindSWIG` module now accepts target languages as  ``COMPONENTS``
 191   and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``.
 192
 193 * The :module:`GoogleTest` module :command:`gtest_discover_tests` command:
 194
 195   * gained a new ``DISCOVERY_MODE`` option to control when the test
 196     discovery step is run.  It offers a new ``PRE_TEST`` setting to
 197     run the discovery at test time instead of build time.  A new
 198     ``CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE`` variable can be used
 199     to change the default globally.
 200
 201   * gained a new optional parameter ``XML_OUTPUT_DIR``. When set the
 202     JUnit XML test results are stored in that directory.
 203
 204 * The :module:`FindLibXslt` module now provides imported targets.
 205
 206 * The :module:`UseSWIG` module now supports Fortran as a target language if
 207   the ``SWIG_EXECUTABLE`` is SWIG-Fortran_.
 208
 209 .. _`SWIG-Fortran`: https://github.com/swig-fortran/swig
 210
 211 Generator Expressions
 212 ---------------------
 213
 214 * The ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>``
 215   :manual:`generator expressions <cmake-generator-expressions(7)>` were added
 216   to manage device and host link steps.
 217
 218 * The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>``
 219   :manual:`generator expressions <cmake-generator-expressions(7)>` were added.
 220
 221 CTest
 222 -----
 223
 224 * :manual:`ctest(1)` gained a new :variable:`CTEST_RESOURCE_SPEC_FILE`
 225   variable, which can be used to specify a
 226   :ref:`resource specification file <ctest-resource-specification-file>`.
 227
 228 * :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
 229   which can be used to stop running the tests once one has failed.
 230
 231 * The :command:`ctest_test` command gained a ``STOP_ON_FAILURE`` option
 232   which can be used to stop running the tests once one has failed.
 233
 234 * The :module:`CTestCoverageCollectGCOV` module
 235   :command:`ctest_coverage_collect_gcov` command gained a
 236   ``TARBALL_COMPRESSION`` option to control compression of the
 237   tarball of collected results.
 238
 239 CPack
 240 -----
 241
 242 * The :cpack_gen:`CPack Archive Generator`'s ``TXZ`` format learned the
 243   :variable:`CPACK_ARCHIVE_THREADS` variable to enable parallel compression.
 244   Requires support in the ``liblzma`` used by CMake.
 245
 246 * The :cpack_gen:`CPack NSIS Generator` gained a new variable
 247   :variable:`CPACK_NSIS_MANIFEST_DPI_AWARE` to declare that the
 248   installer is DPI-aware.
 249
 250 * The :cpack_gen:`CPack RPM Generator` gained
 251   :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE` and
 252   :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE`
 253   variables to specify pre- and post-transaction scripts.
 254
 255 Other
 256 -----
 257
 258 * :manual:`cmake-gui(1)` now populates its generator selection
 259   widget default value from the :envvar:`CMAKE_GENERATOR` environment
 260   variable.  Additionally, environment variables
 261   :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET`
 262   are used to populate their respective widget defaults.
 263
 264 * :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
 265   environment variable to customize colors.
 266
 267 * The :manual:`Compile Features <cmake-compile-features(7)>` functionality
 268   is now aware of the availability of C11 features in MSVC 19.27 and above,
 269   including support for the ``c_restrict`` feature and the ``-std:c11`` flag.
 270
 271 Deprecated and Removed Features
 272 ===============================
 273
 274 * The :module:`Documentation` module has been deprecated via
 275   :policy:`CMP0106`. This module was essentially VTK code that CMake should
 276   not be shipping anymore.
 277
 278 * An explicit deprecation diagnostic was added for policy ``CMP0070``
 279   and policy ``CMP0071`` (``CMP0069`` and below were already deprecated).
 280   The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
 281   of all policies are deprecated and that projects should port to the
 282   NEW behaviors.
 283
 284 Other Changes
 285 =============
 286
 287 * On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config`
 288   generators, when a compiler is not explicitly specified, now select
 289   the first compiler (of any name) found in directories listed by the
 290   ``PATH`` environment variable.
 291
 292 * The :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
 293   properties are now used for the device link step.
 294   See policy :policy:`CMP0105`.
 295
 296 * Creation of an ``ALIAS`` target overwriting an existing target now raises an
 297   error. See policy :policy:`CMP0107`.
 298
 299 * Linking a target to itself through an alias now raises an error.
 300   See policy :policy:`CMP0108`.
 301
 302 * The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
 303   is now optional if ``HANDLE_COMPONENTS`` is specified.
 304
 305 * The :command:`source_group` command now also recognizes forward slashes
 306   as subgroup delimiters, not just backslashes.
 307
 308 * :manual:`ctest(1)` now logs environment variables that it sets for each test,
 309   either due to the :prop_test:`ENVIRONMENT` property or the
 310   :ref:`resource allocation <ctest-resource-allocation>` feature, and submits
 311   this log to CDash. It does not log environment variables that were set
 312   outside of CTest.
 313
 314 * When building CMake itself from source and not using a system-provided
 315   libcurl, HTTP/2 support is now enabled for commands supporting
 316   network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`,
 317   :command:`file(UPLOAD)`, and :command:`ctest_submit`.
 318   The precompiled binaries provided on ``cmake.org`` now support HTTP/2.
 319
 320 * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
 321   been updated to 2.1.
 322
 323 * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
 324   a new ``precompileHeaders`` field in the ``compileGroups`` objects.
 325
 326 Updates
 327 =======
 328
 329 Changes made since CMake 3.18.0 include the following.
 330
 331 3.18.1
 332 ------
 333
 334 * The :generator:`Xcode` generator, when :variable:`CMAKE_OSX_ARCHITECTURES`
 335   is not defined, now selects ``$(NATIVE_ARCH_ACTUAL)`` as the default
 336   architecture (the Xcode ``ARCHS`` setting).  This is needed for Xcode 12
 337   to select the host's architecture, which older versions of Xcode did
 338   by default.
 339
 340 * In CMake 3.18.0 the :command:`add_test` command learned to support
 341   special characters in test names.  This was accidentally left out of
 342   its release notes.  Unfortunately the fix breaks existing projects
 343   that were using manual quoting or escaping to work around the prior
 344   limitation.  This fix has been reverted in 3.18.1, but may be
 345   re-introduced in future versions of CMake with a policy for compatibility.
 346
 347 3.18.2
 348 ------
 349
 350 * The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to
 351   ``OFF`` because this feature can break existing projects that have
 352   identically named header files in different include directories.
 353   This restores compatibility with behavior of CMake 3.15 and below.
 354
 355 * The :manual:`Compile Features <cmake-compile-features(7)>` functionality
 356   was updated for MSVC 19.27 as mentioned above.