# CMake 3.15 Release Notes

Contents

- CMake 3.15 Release Notes
  - New Features
    - Generators
    - Languages
    - Compilers
    - Command-Line
    - Commands
    - Variables
    - Properties
    - Modules
    - Generator Expressions
    - CTest
    - CPack
  - Deprecated and Removed Features
  - Other Changes

Changes made since CMake 3.14 include the following.

## New Features

### Generators

- The `Xcode` generator now supports per-target schemes. See the `CMAKE_XCODE_GENERATE_SCHEME` variable and `XCODE_GENERATE_SCHEME` target property.
- The `Green Hills MULTI` generator has been updated:
  - It now supports the `add_custom_command()` and `add_custom_target()` commands.
  - It is now available on Linux.

### Languages

- Preliminary support for the `Swift` language was added to the `Ninja` generator:

  - Use the `SWIFTC` environment variable to specify a compiler.
  - The `Swift_DEPENDENCIES_FILE` target property and `Swift_DEPENDENCIES_FILE` source file property were added to customize dependency files.
  - The `Swift_MODULE_NAME` target property was added to customize the Swift module name.
  - The `Swift_DIAGNOSTICS_FILE` source property was added to indicate where to write the serialised Swift diagnostics.

  The Swift support is experimental, not considered stable, and may change in future releases of CMake.

### Compilers

- The `Clang` compiler variant on Windows that targets the MSVC ABI but has a GNU-like command line is now supported.
- Support for the Clang-based ARM compiler was added with compiler id `ARMClang`.
- Support was added for the IAR compiler architectures Renesas RX, RL78, RH850 and Texas Instruments MSP430.
- Support was added for the IAR compilers built for Linux (IAR BuildLx).

### Command-Line

- The `CMAKE_GENERATOR` environment variable was added to specify a default generator to use when `cmake(1)` is run without a `-G` option. Additionally, environment variables `CMAKE_GENERATOR_PLATFORM`, `CMAKE_GENERATOR_TOOLSET`, and `CMAKE_GENERATOR_INSTANCE` were created to configure the generator.
- The `cmake(1)` `--build` tool `--target` parameter gained support for multiple targets, e.g. `cmake --build . --target Library1 Library2`. It now also has a short form `-t` alias, e.g. `cmake --build . -t Library1 Library2`.
- The `cmake(1)` command gained a new `--install` option. This may be used after building a project to run installation without using the generated build system or the native build tool.
- The `cmake(1)` command learned a new CLI option `--loglevel`.
- The `cmake(1)` `-E remove_directory` command-line tool learned to support removing multiple directories.
- The `cmake(1)` `-E tar` tool has been improved:
  - It now continues adding files to an archive even if some of the files are not readable. This behavior is more consistent with the classic `tar` tool.
  - It now parses all flags, and if an invalid flag was provided, a warning is issued.
  - It now displays an error if no action flag was specified, along with a list of possible actions: `t` (list), `c` (create) or `x` (extract).
  - It now supports extracting (`-x`) or listing (`-t`) only specific files or directories.
  - It now supports Zstandard compression with a `--zstd` option. Zstandard was designed to give a compression ratio comparable to that of the DEFLATE (zip) algorithm, but faster, especially for decompression.

### Commands

- The `add_custom_command()` and `add_custom_target()` commands gained a new `JOB_POOL` option that works with the `Ninja` generator to set the pool variable on the build statement.
- The `add_library()` command `ALIAS` option learned to support import libraries of the `UNKNOWN` type.
- The `cmake_parse_arguments()` command gained an additional `<prefix>_KEYWORDS_MISSING_VALUES` output variable to report keyword arguments that were given by the caller with no values.
- The `execute_process()` command gained a `COMMAND_ECHO` option and supporting `CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable to enable echoing of the command-line string before execution.
- The `file(INSTALL)` command learned a new argument, `FOLLOW_SYMLINK_CHAIN`, which can be used to recursively resolve and install symlinks.
- `list()` learned new sub-commands: `PREPEND`, `POP_FRONT` and `POP_BACK`.
- The `message()` command learned new types: `NOTICE`, `VERBOSE`, `DEBUG` and `TRACE`.
- The `string()` learned a new sub-command `REPEAT`.

### Variables

- The `CMAKE_CROSSCOMPILING_EMULATOR` variable and corresponding `CROSSCOMPILING_EMULATOR` target property learned to support arguments to the emulator.
- The `CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable was added to tell `find_package()` calls to look for a package configuration file first even if a find module is available.
- The `CMAKE_FRAMEWORK` variable was added to initialize the `FRAMEWORK` property on all targets.
- The `CMAKE_VS_JUST_MY_CODE_DEBUGGING` variable and `VS_JUST_MY_CODE_DEBUGGING` target property were added to enable the Just My Code feature of the Visual Studio Debugger when compiling with MSVC cl 19.05 and higher.
- The `CMAKE_MSVC_RUNTIME_LIBRARY` variable and `MSVC_RUNTIME_LIBRARY` target property were introduced to select the runtime library used by compilers targeting the MSVC ABI. See policy `CMP0091`.
- The `CMAKE_PROJECT_INCLUDE` and `CMAKE_PROJECT_INCLUDE_BEFORE` variables were added to allow injection of custom code at the sites of `project()` calls without knowing the project name a priori.

### Properties

- The `ADDITIONAL_CLEAN_FILES` target property and `ADDITIONAL_CLEAN_FILES` directory property were added. They allow to register additional files that should be removed during the clean stage.
- The `PUBLIC_HEADER` and `PRIVATE_HEADER` properties may now be set on Interface Libraries. The headers specified by those properties can be installed using the `install(TARGETS)` command by passing the `PUBLIC_HEADER` and `PRIVATE_HEADER` arguments respectively.
- The `VS_PACKAGE_REFERENCES` target property was added to tell Visual Studio Generators to add references to `nuget` packages.
- The `VS_PROJECT_IMPORT` target property was added to allow managed Visual Studio project files to import external `.props` files.
- The `VS_NO_SOLUTION_DEPLOY` target property was added to tell Visual Studio Generators whether to deploy an artifact to the WinCE or Windows Phone target device.

### Modules

- The `FindBoost` module was reworked to expose a more consistent user experience between its “Config” and “Module” modes and with other find modules in general.
  - A new imported target `Boost::headers` is now defined (same as `Boost::boost`).
  - New output variables `Boost_VERSION_MACRO`, `Boost_VERSION_MAJOR`, `Boost_VERSION_MINOR`, `Boost_VERSION_PATCH`, and `Boost_VERSION_COUNT` were added.
  - The `QUIET` argument passed to `find_package()` is no longer ignored in config mode. Note that the CMake package shipped with Boost `1.70.0` ignores the `QUIET` argument passed to `find_package()`. This is fixed in the next Boost release.
  - The input switch `Boost_DETAILED_FAILURE_MSG` was removed.
  - `Boost_VERSION` now reports the version in `x.y.z` format in module mode. See policy `CMP0093`.
- The `FindCups` module now provides imported targets.
- The `FindEnvModules` module was added to use Lua- and TCL-based environment modules in CTest Scripts.
- The `FindGLEW` module now provides an interface more consistent with what upstream GLEW provides in its own CMake package files.
- The `FindPkgConfig` now populates `INTERFACE_LINK_OPTIONS` property of imported targets with other (non-library) linker flags.
- The `FindPostgreSQL` module learned to find debug and release variants separately.
- Modules `FindPython3`, `FindPython2` and `FindPython` gained additional lookup strategies and controls, and a new default. See policy `CMP0094`.
- Modules `FindPython`, `FindPython2` and `FindPython3` gain a new target (respectively `Python::Module`, `Python2::Module` and `Python3::Module`) which can be used to develop Python modules.
- Modules `FindPython3`, `FindPython2` and `FindPython` gain capability to control how virtual environments are handled.
- The `UseSWIG` module learned to manage alternate library names by passing `-interface <library_name>` for `python` language or `-dllimport <library_name>` for `CSharp` language to the `SWIG` compiler.

### Generator Expressions

- The `generator expressions` `C_COMPILER_ID`, `CXX_COMPILER_ID`, `CUDA_COMPILER_ID`, `Fortran_COMPILER_ID`, `COMPILE_LANGUAGE`, `COMPILE_LANG_AND_ID`, and `PLATFORM_ID` learned to support matching one value from a comma-separated list.
- The `$<CUDA_COMPILER_ID:...>` and `$<CUDA_COMPILER_VERSION:...>` `generator expressions` were added.
- The `$<COMPILE_LANG_AND_ID:...>` generator expression was introduced to allow specification of compile options for target files based on the `CMAKE_<LANG>_COMPILER_ID` and `LANGUAGE` of each source file.
- A `$<FILTER:list,INCLUDE|EXCLUDE,regex>` `generator expression` has been added.
- A `$<REMOVE_DUPLICATES:list>` `generator expression` has been added.
- The `$<SHELL_PATH:...>` `generator expression` gained support for a list of paths.
- New `$<TARGET_FILE*>` `generator expressions` were added to retrieve the prefix, base name, and suffix of the file names of various artifacts:
  - `$<TARGET_FILE_PREFIX:...>`
  - `$<TARGET_FILE_BASE_NAME:...>`
  - `$<TARGET_FILE_SUFFIX:...>`
  - `$<TARGET_LINKER_FILE_PREFIX:...>`
  - `$<TARGET_LINKER_FILE_BASE_NAME:...>`
  - `$<TARGET_LINKER_FILE_SUFFIX:...>`
  - `$<TARGET_PDB_FILE_BASE_NAME:...>`
- The `$<TARGET_OBJECTS:...>` `generator expression` is now supported on `SHARED`, `STATIC`, `MODULE` libraries and executables.

### CTest

- The `ctest_submit()` command learned a new option: `BUILD_ID`. This can be used to store the ID assigned to this build by CDash to a variable.
- The `ctest_update()` command learned to honor a new variable: `CTEST_UPDATE_VERSION_OVERRIDE`. This can be used to specify the current version of your source tree rather than using the update command to discover the current version that is checked out.

### CPack

- The `CPack IFW Generator` gained a new `CPACK_IFW_PACKAGE_STYLE_SHEET` variable to customize the installer stylesheet.

## Deprecated and Removed Features

- The `cmake-server(7)` mode has been deprecated and will be removed from a future version of CMake. Please port clients to use the `cmake-file-api(7)` instead.
- The `ADDITIONAL_MAKE_CLEAN_FILES` directory property is now deprecated. Use the `ADDITIONAL_CLEAN_FILES` directory property instead.
- The variable `CMAKE_AUTOMOC_RELAXED_MODE` is considered deprecated. Support still exists but will be removed in future versions.
- The `export(PACKAGE)` command now does nothing unless enabled via `CMAKE_EXPORT_PACKAGE_REGISTRY`. See policy `CMP0090`.
- The `Xcode` generator now requires at least Xcode 5.
- An explicit deprecation diagnostic was added for policy `CMP0066` (`CMP0065` 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.

## Other Changes

- CMake learned how to compile C++14 with the IBM AIX XL compiler and the SunPro compiler and to compile C++20 with the AppleClang compiler.
- With MSVC-like compilers the value of `CMAKE_<LANG>_FLAGS` no longer contains warning flags like `/W3` by default. See policy `CMP0092`.
- IBM Clang-based XL compilers that define `__ibmxl__` now use the compiler id `XLClang` instead of `XL`. See policy `CMP0089`.
- The `file(REMOVE)` and `file(REMOVE_RECURSE)` commands were changed to ignore empty arguments with a warning instead of treating them as a relative path and removing the contents of the current directory.