CMake/Help/release/3.20.rst

CMake 3.20 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.19 include the following.

New Features
============

Presets
-------

* :manual:`cmake-presets(7)` gained support for build and test presets.

Generators
----------

* :ref:`Makefile Generators`, for some toolchains, now use the compiler
  to extract implicit dependencies while compiling source files.

Languages
---------

* C++23 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`,
  :prop_tgt:`CUDA_STANDARD`, or :prop_tgt:`OBJCXX_STANDARD` target properties,
  or via the :manual:`Compile Features <cmake-compile-features(7)>`
  functionality's ``cxx_std_23`` meta-feature.

* ``CUDA`` language support now works when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :envvar:`CUDAARCHS` environment variable was added for initializing
  :variable:`CMAKE_CUDA_ARCHITECTURES`. Useful in cases where the compiler
  default is unsuitable for the machine's GPU.

Compilers
---------

* The NVIDIA HPC SDK compilers are now supported with compiler id ``NVHPC``.

* The Intel oneAPI NextGen LLVM compilers are now supported with
  compiler id ``IntelLLVM``:

  * The ``icx``/``icpx`` C/C++ compilers on Linux, and the ``icx``
    C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.

  * The ``ifx`` Fortran compiler on Linux is partially supported.
    As of oneAPI 2021.1, ``ifx`` does not define several identification
    macros, so CMake identifies it as the classic ``Intel`` compiler.
    This works in many cases because ``ifx`` accepts the same command line
    parameters as ``ifort``.  A future version of oneAPI may fix this.

  * The ``ifx`` Fortran compiler on Windows is not yet supported.

  The Intel oneAPI Classic compilers (``icc``, ``icpc``, and ``ifort``)
  continue to be supported with compiler id ``Intel``.

* Support was added for the IAR STM8 compiler.

Platforms
---------

* CMake's support for :ref:`Cross Compiling for Android`
  is now merged with the Android NDK's toolchain file.
  They now have similar behavior, though some variable names differ.
  User-facing changes include:

  - ``find_*`` functions will search NDK ABI / API specific paths by default.

  - The default :variable:`CMAKE_BUILD_TYPE` for Android is
    now ``RelWithDebInfo``.

  - The :variable:`CMAKE_ANDROID_NDK_VERSION` variable was added to
    report the version of the NDK.

File-Based API
--------------

* The :manual:`cmake-file-api(7)` gained a new "toolchains" object
  kind that describes the compiler used for each enabled language.

Commands
--------

* :command:`add_custom_command` and :command:`add_custom_target` now
  support :manual:`generator expressions <cmake-generator-expressions(7)>`
  in their ``OUTPUT`` and ``BYPRODUCTS`` options.

  Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained
  support for new generator expressions ``$<COMMAND_CONFIG:...>`` and
  ``$<OUTPUT_CONFIG:...>`` that control cross-config handling when using
  the :generator:`Ninja Multi-Config` generator.

* The :command:`add_custom_command` command gained ``DEPFILE`` support on
  :ref:`Makefile Generators`.

* The :command:`add_library` command previously prohibited imported object
  libraries when using potentially multi-architecture configurations.
  This mostly affected the :generator:`Xcode` generator, e.g. when targeting
  iOS or one of the other device platforms.  This restriction has now been
  removed.

* The :command:`cmake_path` command was added for operations on
  filesystem paths.

* The :command:`configure_file` command gained ``USE_SOURCE_PERMISSIONS``
  and ``FILE_PERMISSIONS`` options to support copying of permissions of the
  source file and using specified permissions respectively.

* The :command:`file(GENERATE)` command gained a ``NEWLINE_STYLE`` option to
  specify how newlines are handled for the generated file.

* The :command:`file(GENERATE)` command gained ``NO_SOURCE_PERMISSIONS``,
  ``USE_SOURCE_PERMISSIONS``, and ``FILE_PERMISSIONS`` options for controlling
  the permissions of the generated file.

* The :command:`install(FILES)` command ``RENAME`` option learned to
  support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :command:`target_include_directories` command gained a new option
  ``AFTER``.

* The :command:`target_sources` command now supports targets created
  by the :command:`add_custom_target` command.

* The :command:`try_run` command gained a ``WORKING_DIRECTORY`` option to
  set the working directory in which to run the compiled check executable.

Variables
---------

* The :variable:`CMAKE_<LANG>_BYTE_ORDER` variable was added to provide the
  target architecture byte order detected from the toolchain.

* The :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY`,
  :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY`, and
  :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` variables now support
  target-dependent generator expressions.

Properties
----------

* The :prop_tgt:`<LANG>_CLANG_TIDY` target property and the associated
  :variable:`CMAKE_<LANG>_CLANG_TIDY` variable learned to support
  the ``OBJC`` and ``OBJCXX`` languages.

* The :prop_tgt:`EXPORT_COMPILE_COMMANDS` target property was added
  for the associated :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable
  to allow for configuration of exporting compile commands per target.

* The :prop_sf:`GENERATED` source-file property is now visible
  from any directory scope, regardless of the scope in which it is set.
  See policy :policy:`CMP0118`.

* The :prop_tgt:`UNITY_BUILD_UNIQUE_ID` target property
  was added to support generation of an identifier that is
  unique per source file in unity builds.  It can help to
  resolve duplicate symbol problems with anonymous namespaces.

* The :prop_tgt:`WIN32_EXECUTABLE` target property now works with Clang
  on Windows.

* The :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator to embed frameworks.
  Aspects of the embedding can be customized with the
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_PATH <XCODE_EMBED_<type>>`,
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`, and
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` target properties.

Modules
-------

* The :module:`ExternalData` module :command:`ExternalData_Add_Target`
  function gained a ``SHOW_PROGRESS <bool>`` option for controlling whether
  or not to show progress output during the build.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` function
  gained a ``CONFIGURE_HANDLED_BY_BUILD`` option.  This can be used to make
  subsequent runs of the configure step be triggered by the build step when
  an external project dependency rebuilds instead of always re-running the
  configure step in such cases.

* The :module:`FindBoost` module gained a ``Boost_NO_WARN_NEW_VERSIONS``
  option to silence the warning about unknown dependencies for new
  Boost versions.

* The :module:`FindCUDAToolkit` module gained support for finding CUDA
  toolkits when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :module:`FindGDAL` module has been improved to document and mark as
  advanced its cache variables. There is a new ``FindGDAL_SKIP_GDAL_CONFIG``
  variable which may be used to skip over the ``gdal-config``-based search.
  Users may also set ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` to add additional
  versions to the library name search strategy.

* The :module:`FindIntl` module now provides an imported target.

* The :module:`FindOpenSSL` module learned to support a version range.

* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules gained options controlling how unversioned interpreter names are
  searched.

* The :module:`UseJava` module ``add_jar()`` command's
  ``GENERATE_NATIVE_HEADERS`` feature gained options to export the
  generated target.

* The :module:`UseSWIG` module gained the capability, for
  :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>`
  generators, to use the ``swig`` tool to generate implicit dependencies.

Autogen
-------

* The :ref:`Qt AUTOMOC` feature now works with per-config sources.

CTest
-----

* :manual:`ctest(1)` gained a ``--test-dir`` option to specify the directory
  in which to look for tests.

CPack
-----

* :module:`CPack` gained the :variable:`CPACK_THREADS` variable to
  control the number of threads used for parallelized operations,
  such as compressing the installer package.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS`
  variable to specify additional search directories for
  resolving private library dependencies when using
  ``dpkg-shlibdeps``.

* The :cpack_gen:`CPack IFW Generator` gained a new
  :variable:`CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST` variable to
  control visibility of the widget listing installer pages on the left side
  of the wizard. This feature available only since QtIFW 4.0.

* The :cpack_gen:`CPack NSIS Generator` gained new
  :variable:`CPACK_NSIS_BRANDING_TEXT` and
  :variable:`CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION` variables to change
  the text at the bottom of the install window and change its trim position

* The :cpack_gen:`CPack NSIS Generator` now correctly handles Unicode
  characters.  If you want to have a :variable:`CPACK_RESOURCE_FILE_LICENSE`
  with UTF-8 characters, it needs to be encoded in UTF-8 BOM.

* The :cpack_gen:`CPack NuGet Generator` gained options:

  - :variable:`CPACK_NUGET_PACKAGE_ICON` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICON`
    allow package icons to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION` add
    support for specifying licenses recognized by the
    `Software Package Data Exchange`_ (SPDX).
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME` allow
    licenses to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LANGUAGE` allow the locale
    for a package to be specified, for example ``en_CA``.

.. _Software Package Data Exchange: https://spdx.org/

Deprecated and Removed Features
===============================

* The :manual:`cmake-server(7)` mode has been removed.
  Clients should use the :manual:`cmake-file-api(7)` instead.

* The :module:`WriteCompilerDetectionHeader` module has been deprecated
  via policy :policy:`CMP0120`.  Projects should be ported away from it.

* The :module:`TestBigEndian` module has been deprecated in favor
  of the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.

* The :module:`AddFileDependencies` module is deprecated.
  Port projects to use :command:`set_property` directly.

* The :cpack_gen:`CPack NuGet Generator` deprecated some variables to reflect
  changes in the NuGet specification:

  - :variable:`CPACK_NUGET_PACKAGE_ICONURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICONURL` have been deprecated;
    replace with a reference to a local icon file.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSEURL` have been deprecated;
    replace with a reference to the project's license file or SPDX
    license expression.

Other Changes
=============

* Source file extensions must now be explicit.
  See policy :policy:`CMP0115` for details.

* The :prop_sf:`LANGUAGE` source file property now forces compilation
  as the specified language.  See policy :policy:`CMP0119`.

* On AIX, installation of XCOFF executables and shared libraries
  no longer requires relinking to change the runtime search path
  from the build-tree RPATH to the install-tree RPATH.  CMake now
  edits the XCOFF binaries directly during installation, as has
  long been done on ELF platforms.

* With MSVC-like compilers the value of
  :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` no longer contains
  the ``/GR`` flag for runtime type information by default.
  See policy :policy:`CMP0117`.

* Ninja generators now transform the ``DEPFILE`` generated by an
  :command:`add_custom_command`. See policy :policy:`CMP0116` for details.

* The precompiled Linux binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-linux-$arch``, where ``$arch`` is either ``x86_64`` or
  ``aarch64``.

* The precompiled Windows binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-windows-$arch``, where ``$arch`` is either ``x86_64`` or
  ``i386``.

Updates
=======

Changes made since CMake 3.20.0 include the following.

3.20.1
------

* The :module:`FindIntl` module in CMake 3.20.0 added checks
  ``Intl_HAVE_GETTEXT_BUILTIN``, ``Intl_HAVE_DCGETTEXT_BUILTIN``,
  and ``Intl_IS_BUILTIN``, but they were not implemented correctly.
  These have been removed and replaced with a single ``Intl_IS_BUILT_IN``
  check, whose name is consistent with the :module:`FindIconv` module.