# CMake 3.19 Release Notes

Contents

- CMake 3.19 Release Notes

  - New Features

    - Presets

    - Generators

    - Languages

    - File-Based API

    - Command-Line

    - GUI

    - Commands

    - Variables

    - Properties

    - Modules

    - CTest

    - CPack

    - Other

  - Deprecated and Removed Features

  - Documentation

  - Other Changes

Changes made since CMake 3.18 include the following.

## New Features

### Presets

- `cmake(1)` and `cmake-gui(1)` now recognize `CMakePresets.json` and `CMakeUserPresets.json` files.

### Generators

- The `Xcode` generator now uses the Xcode “new build system” when generating for Xcode 12.0 or higher. See the `CMAKE_XCODE_BUILD_SYSTEM` variable. One may use `-T buildsystem=1` to switch to the legacy build system.

- The `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 `XCODE_LINK_BUILD_PHASE_MODE` target property, which is initialized by a new `CMAKE_XCODE_LINK_BUILD_PHASE_MODE` variable.

- The Visual Studio Generators for VS 2015 and above gained support for the Visual Studio Tools for Android. One may now set `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 `project()` and `enable_language()` commands. `ISPC` is currently supported by the Makefile Generators and the `Ninja` generator on Linux, macOS, and Windows using the Intel ISPC compiler.

- `CUDA` language support for Clang now includes:

  - separable compilation (`CUDA_SEPARABLE_COMPILATION`), and

  - finding scattered toolkit installations when cross-compiling.

### File-Based API

- The `cmake-file-api(7)` “codemodel” version 2 `version` field has been updated to 2.2.

- The `cmake-file-api(7)` “codemodel” version 2 “target” object gained a new `languageStandard` field in the `compileGroups` objects.

### Command-Line

- The `cmake(1)` command-line tool’s `--install` mode gained a `--default-directory-permissions` option.

- `cmake(1)` gained a `-E create_hardlink` command-line tool that can be used to create hardlinks between files.

### GUI

- The `CMake GUI` now has an environment variable editor.

### Commands

- The `add_test()` command now (officially) supports whitespace and other special characters in the name for the test it creates. See policy `CMP0110`.

- The `cmake_language()` command gained a `DEFER` mode to schedule command calls to occur at the end of processing a directory.

- The `cmake_path()` command was added for operations on filesystem paths.

- The `configure_file()` command gained a `NO_SOURCE_PERMISSIONS` option to suppress copying the input file’s permissions to the output file.

- The `execute_process()` command gained a `COMMAND_ERROR_IS_FATAL` option to specify a fatal error.

- The `file(ARCHIVE_CREATE)` command gained a `COMPRESSION_LEVEL` option to specify the compression level.

- The `file(CHMOD)` and `file(CHMOD_RECURSE)` subcommands were added to set permissions of files and directories.

- The `file(DOWNLOAD)` command `<file>` argument is now optional. If it is not specified, the file is not saved.

- The `file(GENERATE)` command gained a new `TARGET` keyword to support resolving target-dependent generator expressions.

- The `file()` gained sub-command REAL_PATH to compute a path with symlinks resolved.

- The `find_package()` command learned to handle a version range.

- The `separate_arguments()` command gained new `PROGRAM` option to search program.

- The `set_property()`, `get_property()`, and `get_directory_property()` commands’ `DIRECTORY` options now accept references to binary directory paths, such as the value of `CMAKE_CURRENT_BINARY_DIR`.

- The `string()` command gained set of new `JSON` sub commands to provide JSON parsing capabilities.

### Variables

- The `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 `CMAKE_MFC_FLAG` variable now supports generator expressions.

- The `CMAKE_OPTIMIZE_DEPENDENCIES` variable was added to initialize the new `OPTIMIZE_DEPENDENCIES` target property and avoid unnecessarily building dependencies for a static library.

- The `CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable was added to tell the Visual Studio Generators what maximum version of the Windows SDK to choose.

### Properties

- The `EXCLUDE_FROM_ALL` target property now supports `generator expressions`.

- The `OPTIMIZE_DEPENDENCIES` target property was added to avoid unnecessarily building dependencies for a static library.

- The `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 `WIN32_EXECUTABLE` target property now supports `generator expressions`.

### Modules

- The `CheckCompilerFlag` module has been added to generalize `CheckCCompilerFlag` and `CheckCXXCompilerFlag` to more languages. It also supports the `CUDA` and `ISPC` languages.

- The `CheckLinkerFlag` module now supports the `CUDA` language.

- The `CheckSourceCompiles` module has been added to generalize `CheckCSourceCompiles` and `CheckCXXSourceCompiles` to more languages. It also supports the `CUDA` and `ISPC` languages.

- The `CheckSourceRuns` module has been added to generalize `CheckCSourceRuns` and `CheckCXXSourceRuns` to more languages. It also supports the `CUDA` language.

- `CMakePackageConfigHelpers` module learned to manage version range.

- The `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 `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 `find_package()` command.

- The `FindPython3`, `FindPython2` and `FindPython` modules gained the capability to manage a version range.

- The `FindPython3`, `FindPython2` and `FindPython` modules provide, respectively, the variable `Python3_LINK_OPTIONS`, `Python2_LINK_OPTIONS` and `Python_LINK_OPTIONS` for link options.

- The `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`.

- `FindSWIG` module gains the capability to manage a version range.

- The `FindTIFF` module gained a `CXX` component to find the `tiffxx` library containing C++ bindings.

- The `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.

- `UseSWIG` module gains new source file properties `OUTPUT_DIR` and `OUTFILE_DIR` to manage output directories on per source basis.

### CTest

- `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 `CPACK_PRE_BUILD_SCRIPTS`, `CPACK_POST_BUILD_SCRIPTS`, and `CPACK_PACKAGE_FILES` variables.

- The `CPack External Generator` gained the `CPACK_EXTERNAL_BUILT_PACKAGES` variable.

- The `CPack WIX Generator` gained a `CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces.

### Other

- Interface Libraries may now have source files added via `add_library()` or `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 `cmake_minimum_required()` or `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 `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.

- `cmake-gui(1)` now requires Qt5. Support for compiling with Qt4 has been removed.

- The `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:

- `IDE Integration 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 `CMAKE_OSX_SYSROOT`. The deployment target or system macOS version will not affect the choice of SDK.

- The `CMAKE_<LANG>_COMPILER` variable may now be used to store “mandatory” compiler flags like the `CC` and other environment variables.

- The `CMAKE_<LANG>_FLAGS_INIT` variable will now be considered during the compiler identification check if other sources like `CMAKE_<LANG>_FLAGS` or `CFLAGS` are not set.

- The `find_program()` command now requires permission to execute but not to read the file found. See policy `CMP0109`.

- An imported target with a missing location now fails during generation if the location is used. See 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 `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`

- Makefile Generators no longer repeat custom commands from target dependencies. See policy `CMP0113`.

- The `ExternalProject` module handling of step target dependencies has been revised. See policy `CMP0114`.

- The `OSX_ARCHITECTURES` target property is now respected for the `ASM` language.

- If `CUDA` compiler detection fails with user-specified `CMAKE_CUDA_ARCHITECTURES` or `CMAKE_CUDA_HOST_COMPILER`, an error is raised.