| 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 implementation of the :module:`ExternalProject` module was |
| significantly refactored. The patch step gained support for |
| using the terminal with a new ``USES_TERMINAL_PATCH`` keyword |
| as a by-product of that work. |
| |
| * The :module:`FetchContent` module no longer creates a separate |
| sub-build to implement the content population. It now invokes |
| the step scripts directly from within the main project's |
| configure stage. This significantly speeds up the configure |
| phase when the required content is already populated and |
| up-to-date. |
| |
| * 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``. |
