# CMake 3.17 Release Notes

Contents

- CMake 3.17 Release Notes
  - New Features
    - Generators
    - Languages
    - Compilers
    - Command-Line
    - Commands
    - Variables
    - Properties
    - Modules
    - Autogen
    - CTest
    - CPack
    - Other
  - Deprecated and Removed Features
  - Other Changes
  - Updates
    - 3.17.1

Changes made since CMake 3.16 include the following.

## New Features

### Generators

- `cmake(1)` gained a `Ninja Multi-Config` generator, which is similar to the `Ninja` generator but can be used to build multiple configurations at once.
- Visual Studio Generators learned to support per-config sources. Previously only Command-Line Build Tool Generators supported them.
- Visual Studio Generators for VS 2010 and above now support specifying the `VCTargetsPath` value for project files in `CMAKE_GENERATOR_TOOLSET` setting.
- Visual Studio Generators for VS 2010 and above learned to support .NET Standard and .NET Core. See the `DOTNET_TARGET_FRAMEWORK` target property and associated `CMAKE_DOTNET_TARGET_FRAMEWORK` variable.

### Languages

- The `Compile Features` functionality now offers meta-features for the CUDA language standard levels (e.g. `cuda_std_03`, `cuda_std_14`). See `CMAKE_CUDA_KNOWN_FEATURES`.

### Compilers

- The IBM XL Fortran compiler is now supported by the `Ninja` generator.

### Command-Line

- `cmake(1)` gained a `--debug-find` command-line option to enable additional human-readable output on where `find_*` commands search.
- `cmake(1)` gained a `--trace-format` command-line option that can be used to set the `--trace` output format. Currently, the old human readable and the new JSON format are supported. The new JSON format is easier to parse automatically than the existing format.
- `cmake(1)` gained a `-E rm` command-line tool that can be used to remove directories and files. This supersedes the existing `-E remove` and `-E remove_directory` tools and has better semantics.

### Commands

- The `add_custom_command()` command learned to interpret paths in `DEPENDS` arguments that are specified relative to the current binary directory.
- The `foreach()` command learned a new `ZIP_LISTS` option to iterate over multiple lists simultaneously.
- The `load_cache(READ_WITH_PREFIX)` command mode is now allowed when using `cmake -P` to Run a Script.
- The `message()` command learned to output context provided in the `CMAKE_MESSAGE_CONTEXT` variable for log levels `NOTICE` and below. Enable this output with the new `--log-context` command-line option or `CMAKE_MESSAGE_CONTEXT_SHOW` variable.
- The `message()` command gained new keywords `CHECK_START`, `CHECK_PASS` and `CHECK_FAIL`.
- The `target_compile_options()` command now honors the `BEFORE` keyword more consistently. See policy `CMP0101`.

### Variables

- A `CMAKE_CTEST_ARGUMENTS` variable was added to specify a list of command-line arguments passed to CTest when running through the `test` (or `RUN_TESTS`) target of the generated build system.
- The following variables are now defined inside a `function()`:
  - `CMAKE_CURRENT_FUNCTION`
  - `CMAKE_CURRENT_FUNCTION_LIST_DIR`
  - `CMAKE_CURRENT_FUNCTION_LIST_FILE`
  - `CMAKE_CURRENT_FUNCTION_LIST_LINE`
- The `CMAKE_CUDA_RUNTIME_LIBRARY` variable and `CUDA_RUNTIME_LIBRARY` target property were introduced to select the CUDA runtime library used when linking targets that use CUDA.
- The `CMAKE_FIND_DEBUG_MODE` variable was introduced to print extra `find_*` call information during the cmake run to standard error. Output is designed for human consumption and not for parsing.
- The `CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its initial value from the `CMAKE_EXPORT_COMPILE_COMMANDS` environment variable if no explicit configuration is given.
- The `CMAKE_<LANG>_COMPILER_LAUNCHER` variable, if not set explicitly, now takes its initial value from the `CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable.
- The `CMAKE_MESSAGE_LOG_LEVEL` variable can now be used to persist a log level between CMake runs, unlike the `--log-level` command line option which only applies to that particular run.
- The `CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added to initialize the `XCODE_SCHEME_ENVIRONMENT` target property.
- The `CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` variable and associated `XCODE_SCHEME_WORKING_DIRECTORY` target property were added to tell the `Xcode` generator to set the value of the `Custom Working Directory` schema option.

### Properties

- The `AIX_EXPORT_ALL_SYMBOLS` target property and associated `CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to optionally explicitly disable automatic export of symbols from shared libraries on AIX.
- The `DEPRECATION` target property was added to mark a target as deprecated. If a linked target is marked as deprecated, a warning with the deprecation message is issued at generate time.
- The `INSTALL_NAME_DIR` target property now supports `generator expressions`. In particular, the `$<INSTALL_PREFIX>` generator expression can be used to set the directory relative to the install-time prefix.
- Target properties `MACHO_COMPATIBILITY_VERSION` and `MACHO_CURRENT_VERSION` were added to set the `compatibility_version` and `curent_version`, respectively, for Mach-O binaries. For backwards compatibility, if these properties are not set, `SOVERSION` and `VERSION` are used respectively as fallbacks.
- The `VS_DOTNET_DOCUMENTATION_FILE` target property was added to tell Visual Studio Generators to generate a `DocumentationFile` reference in `.csproj` files.

### Modules

- The `ExternalProject` module `ExternalProject_Add()` command gained a `GIT_SUBMODULES_RECURSE` option to specify whether Git submodules should be updated recursively. The default is on to preserve existing behavior.
- The `FindCUDAToolkit` module was added to find the CUDA Toolkit without enabling CUDA as a language.
- The `FindCURL` module learned to find CURL using the `CURLConfig.cmake` package configuration file generated by CURL’s cmake buildsystem. It also gained a new `CURL_NO_CURL_CMAKE` option to disable this behavior.
- The `FindFLEX` module’s `FLEX_TARGET` command now runs `flex` with `CMAKE_CURRENT_BINARY_DIR` as the working directory. See policy `CMP0098`.
- The `FindLibArchive` module now provides an imported target for libarchive.
- The `FindPython` module has learned to find Python components in active virtual environments managed by `conda`.
- The `FindPython3` and `FindPython` modules gained, respectively, variable `Python3_SOABI` and `Python_SOABI` giving the standard extension suffix for modules. Moreover, commands `Python3_add_library()` and `Python_add_library()` gained the option `WITH_SOABI` to prefix the library suffix with the value of `SOABI`.
- The `FindLibXml2` module now provides an imported target for the `xmllint` executable.

### Autogen

- `AUTOMOC` and `AUTOUIC` learned to process headers with a `.hh` extension. See policy `CMP0100`.

### CTest

- The `CTEST_CONFIGURATION_TYPE` variable is now set from the command line when `ctest(1)` is invoked with `-C <cfg>`.
- The `ctest(1)` tool gained support for Dr. Memory to run memcheck runs.
- The `ctest(1)` tool gained a `--no-tests=<[error|ignore]>` option to explicitly set and unify the behavior between direct invocation and script mode if no tests were found.
- The `ctest(1)` tool gained a `--repeat <mode>:<n>` option to specify conditions in which to repeat tests. This generalizes the existing `--repeat-until-fail <n>` option to add modes for `until-pass` and `after-timeout`.
- The `ctest_test()` command gained a `REPEAT <mode>:<n>` option to specify conditions in which to repeat tests.

### CPack

- The `CPack DragNDrop Generator` learned to use the `CPACK_DMG_<component>_FILE_NAME` variable to set a custom filename when packaging components into their own DMGs.
- The `CPack DragNDrop Generator` learned to handle RTF formatted license files. When `CPACK_DMG_SLA_DIR` variable is set, `<language>.license.rtf` is considered, but only as a fallback when the plaintext (`.txt`) file is not found in order to maintain backwards compatibility.
- The `CPack NSIS Generator` gained a new variable `CPACK_NSIS_MUI_HEADERIMAGE` to set the header image. To not break existing setups, it still defaults to `CPACK_PACKAGE_ICON` if the new variable is not set.
- The `CPack NSIS Generator` now supports `CPACK_NSIS_UNINSTALL_NAME`. This can be used to specify the name of the Uninstall program.
- The `CPack NSIS Generator` now supports `CPACK_NSIS_WELCOME_TITLE` and `CPACK_NSIS_WELCOME_TITLE_3LINES`. These can be used to specify the welcome page title and display it in 3 lines.
- The `CPack NSIS Generator` now supports `CPACK_NSIS_FINISH_TITLE` and `CPACK_NSIS_FINISH_TITLE_3LINES`. These can be used to specify the finish page title and display it in 3 lines.
- The `CPack productbuild Generator` gained support for a `CPACK_PRODUCTBUILD_BACKGROUND` variable to specify a background image for the macOS installer.

### Other

- `ccmake(1)` now displays cache values using colors based on the entry type if the terminal supports color.
- `ccmake(1)` now displays messages and a progress bar during configure and generate. It will keep the output displayed if any errors or warnings occurred.

## Deprecated and Removed Features

- An explicit deprecation diagnostic was added for policy `CMP0068` and policy `CMP0069` (`CMP0067` 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.
- The `CPack PackageMaker Generator` generator has been deprecated because Xcode no longer distributes the PackageMaker tools. The undocumented `OSXX11` generator has also been deprecated.
- The `cmake(1)` command-line `-E remove` and `-E remove_directory` tools are deprecated in favor of the new `-E rm` tool. The older tools always returned 0 if a named path did not exist even without the force option and cannot be fixed without breaking compatibility, and so have been superseded.
- The `CPack NSIS Generator` now requires NSIS 3.0 or later.

## Other Changes

- The `file API` index file now emits a `multiConfig` flag specifying whether or not the generator supports multiple output configurations.
- Target link properties `INTERFACE_LINK_OPTIONS`, `INTERFACE_LINK_DIRECTORIES` and `INTERFACE_LINK_DEPENDS` are now transitive over private dependencies on static libraries. See policy `CMP0099`.
- When using MinGW tools, the `find_library()` command no longer finds `.dll` files by default. Instead, it expects `.dll.a` import libraries to be available.
- The `MinGW Makefiles` generator no longer issues an error if `sh.exe` is present in the environment’s `PATH`.
- The `Ninja` generator now prefers the first ninja build tool to appear in the `PATH` no matter whether it is called `ninja-build`, `ninja`, or `samu`. Previously the first of those names to appear anywhere in the `PATH` would be preferred.
- With SDCC the `sdar` tool is now preferred over `sdcclib` as librarian. The latter was deprecated by SDCC 3.2.0 and removed in SDCC 3.8.6.
- With SDCC the default flags no longer include any target-specific flags. Previously the default flags were hard-coded for 8051.
- The `CMAKE_VS_GLOBALS` variable value now applies during compiler identification and in targets created by the `add_custom_target()` command.
- The `Xcode` generator no longer hard-codes `-Wmost`, `-Wno-four-char-constants`, and `-Wno-unknown-pragmas` warning flags.

## Updates

Changes made since CMake 3.17.0 include the following.

### 3.17.1

- CMake 3.17.0 updated the `CPack NSIS Generator` with changes that require NSIS 3.0 or later. CMake 3.17.1 now enforces the use of a sufficiently new version.