CMake 3.19 Release Notes ************************ .. only:: html .. contents:: Changes made since CMake 3.18 include the following. New Features ============ Presets ------- * :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. Generators ---------- * The :generator:`Xcode` generator now uses the Xcode "new build system" when generating for Xcode 12.0 or higher. See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable. One may use ``-T buildsystem=1`` to switch to the legacy build system. * The :generator:`Xcode` generator gained support for linking libraries and frameworks via the *Link Binaries With Libraries* build phase instead of always by embedding linker flags directly. This behavior is controlled by a new :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE` variable. * The :ref:`Visual Studio Generators` for VS 2015 and above gained support for the Visual Studio Tools for Android. One may now set :variable:`CMAKE_SYSTEM_NAME` to ``Android`` to generate ``.vcxproj`` files for the Android tools. Languages --------- * CMake learned to support ``ISPC`` as a first-class language that can be enabled via the :command:`project` and :command:`enable_language` commands. ``ISPC`` is currently supported by the :ref:`Makefile Generators` and the :generator:`Ninja` generator on Linux, macOS, and Windows using the Intel ISPC compiler. * ``CUDA`` language support for Clang now includes: - separable compilation (:prop_tgt:`CUDA_SEPARABLE_COMPILATION`), and - finding scattered toolkit installations when cross-compiling. File-Based API -------------- * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has been updated to 2.2. * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained a new ``languageStandard`` field in the ``compileGroups`` objects. Command-Line ------------ * The :manual:`cmake(1)` command-line tool's ``--install`` mode gained a ``--default-directory-permissions`` option. * :manual:`cmake(1)` gained a ``-E create_hardlink`` command-line tool that can be used to create hardlinks between files. GUI --- * The :manual:`CMake GUI ` now has an environment variable editor. Commands -------- * The :command:`add_test` command now (officially) supports whitespace and other special characters in the name for the test it creates. See policy :policy:`CMP0110`. * The :command:`cmake_language` command gained a ``DEFER`` mode to schedule command calls to occur at the end of processing a directory. * The :command:`cmake_path` command was added for operations on filesystem paths. * The :command:`configure_file` command gained a ``NO_SOURCE_PERMISSIONS`` option to suppress copying the input file's permissions to the output file. * The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL`` option to specify a fatal error. * The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL`` option to specify the compression level. * The :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` subcommands were added to set permissions of files and directories. * The :command:`file(DOWNLOAD)` command ```` argument is now optional. If it is not specified, the file is not saved. * The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to support resolving target-dependent generator expressions. * The :command:`file` gained sub-command `REAL_PATH` to compute a path with symlinks resolved. * The :command:`find_package` command learned to handle a version range. * The :command:`separate_arguments` command gained new ``PROGRAM`` option to search program. * The :command:`set_property`, :command:`get_property`, and :command:`get_directory_property` commands' ``DIRECTORY`` options now accept references to binary directory paths, such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. * The :command:`string` command gained set of new ``JSON`` sub commands to provide JSON parsing capabilities. Variables --------- * The :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell Clang to use a VFS overlay to support the Windows SDK when cross-compiling from hosts with case-sensitive filesystems. * The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions. * The :variable:`CMAKE_OPTIMIZE_DEPENDENCIES` variable was added to initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and avoid unnecessarily building dependencies for a static library. * The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable was added to tell the :ref:`Visual Studio Generators` what maximum version of the Windows SDK to choose. Properties ---------- * The :prop_tgt:`EXCLUDE_FROM_ALL` target property now supports :manual:`generator expressions `. * The :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property was added to avoid unnecessarily building dependencies for a static library. * The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable template instantiation in the precompiled header. This is enabled by default and offers a roughly 20% compile time improvement. Currently only supported by Clang 11. * The :prop_tgt:`WIN32_EXECUTABLE` target property now supports :manual:`generator expressions `. Modules ------- * The :module:`CheckCompilerFlag` module has been added to generalize :module:`CheckCCompilerFlag` and :module:`CheckCXXCompilerFlag` to more languages. It also supports the ``CUDA`` and ``ISPC`` languages. * The :module:`CheckLinkerFlag` module now supports the ``CUDA`` language. * The :module:`CheckSourceCompiles` module has been added to generalize :module:`CheckCSourceCompiles` and :module:`CheckCXXSourceCompiles` to more languages. It also supports the ``CUDA`` and ``ISPC`` languages. * The :module:`CheckSourceRuns` module has been added to generalize :module:`CheckCSourceRuns` and :module:`CheckCXXSourceRuns` to more languages. It also supports the ``CUDA`` language. * :module:`CMakePackageConfigHelpers` module learned to manage version range. * The :module:`FindCUDAToolkit` module gained support for finding CUDA toolkits that do not contain ``nvcc``, as well as for finding scattered toolkit installations when cross-compiling. * The :module:`FindPackageHandleStandardArgs` module learned to handle version range. It also gained the ``find_package_check_version()`` command to check the validity of a version against version-related arguments of :command:`find_package` command. * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` modules gained the capability to manage a version range. * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` modules provide, respectively, the variable ``Python3_LINK_OPTIONS``, ``Python2_LINK_OPTIONS`` and ``Python_LINK_OPTIONS`` for link options. * The :module:`FindSDL` module now provides: * imported target ``SDL::SDL``, * result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``, * version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR`` ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``. * :module:`FindSWIG` module gains the capability to manage a version range. * The :module:`FindTIFF` module gained a ``CXX`` component to find the ``tiffxx`` library containing C++ bindings. * The :module:`FindVulkan` module now provides a ``Vulkan::glslc`` imported target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain the path to the GLSL SPIR-V compiler. * :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on per source basis. CTest ----- * :manual:`ctest(1)` now supports ``compute-sanitizer`` (``cuda-memcheck``) as ``CTEST_MEMORYCHECK_COMMAND``. The different tools (memcheck, racecheck, synccheck, initcheck) supplied by ``compute-sanitizer`` can be selected by adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS`` variable. The default flags are ``--tool memcheck --leak-check full``. CPack ----- * CPack gained the :variable:`CPACK_PRE_BUILD_SCRIPTS`, :variable:`CPACK_POST_BUILD_SCRIPTS`, and :variable:`CPACK_PACKAGE_FILES` variables. * The :cpack_gen:`CPack External Generator` gained the :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable. * The :cpack_gen:`CPack WIX Generator` gained a :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces. Other ----- * :ref:`Interface Libraries` may now have source files added via :command:`add_library` or :command:`target_sources`. Those with sources will be generated as part of the build system. Deprecated and Removed Features =============================== * Compatibility with versions of CMake older than 2.8.12 is now deprecated and will be removed from a future version. Calls to :command:`cmake_minimum_required` or :command:`cmake_policy` that set the policy version to an older value now issue a deprecation diagnostic. * An explicit deprecation diagnostic was added for policy ``CMP0071`` (``CMP0071`` 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. * macOS SDKs older than 10.5 are no longer supported. * :manual:`cmake-gui(1)` now requires Qt5. Support for compiling with Qt4 has been removed. * The :manual:`cmake(1)` command-line option ``--warn-unused-vars`` has been removed and is now silently ignored. The option has not worked correctly since CMake 3.3. Documentation ============= The following guides have been added: * :guide:`IDE Integration Guide` * :guide:`Importing and Exporting Guide` Other Changes ============= * Building for macOS will now use the latest SDK available on the system, unless the user has explicitly chosen a SDK using :variable:`CMAKE_OSX_SYSROOT`. The deployment target or system macOS version will not affect the choice of SDK. * The :variable:`CMAKE__COMPILER` variable may now be used to store "mandatory" compiler flags like the :envvar:`CC` and other environment variables. * The :variable:`CMAKE__FLAGS_INIT` variable will now be considered during the compiler identification check if other sources like :variable:`CMAKE__FLAGS` or :envvar:`CFLAGS` are not set. * The :command:`find_program` command now requires permission to execute but not to read the file found. See policy :policy:`CMP0109`. * An imported target missing its location property fails during generation if the location is used. See policy :policy:`CMP0111`. * The following target-based generator expressions that query for directory or file name components no longer add a dependency on the evaluated target. See policy :policy:`CMP0112`. - ``TARGET_FILE_DIR`` - ``TARGET_LINKER_FILE_BASE_NAME`` - ``TARGET_LINKER_FILE_NAME`` - ``TARGET_LINKER_FILE_DIR`` - ``TARGET_SONAME_FILE_NAME`` - ``TARGET_SONAME_FILE_DIR`` - ``TARGET_PDB_FILE_NAME`` - ``TARGET_PDB_FILE_DIR`` - ``TARGET_BUNDLE_DIR`` - ``TARGET_BUNDLE_CONTENT_DIR`` * :ref:`Makefile Generators` no longer repeat custom commands from target dependencies. See policy :policy:`CMP0113`. * The :module:`ExternalProject` module handling of step target dependencies has been revised. See policy :policy:`CMP0114`. * The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected for the ``ASM`` language. * If ``CUDA`` compiler detection fails with user-specified :variable:`CMAKE_CUDA_ARCHITECTURES` or :variable:`CMAKE_CUDA_HOST_COMPILER`, an error is raised.