# CMake 3.18 Release Notes

Contents

- CMake 3.18 Release Notes

  - New Features

    - Languages

    - Command-Line

    - Commands

    - Variables

    - Properties

    - Modules

    - Generator Expressions

    - CTest

    - CPack

    - Other

  - Deprecated and Removed Features

  - Other Changes

Changes made since CMake 3.17 include the following.

## New Features

### Languages

- The `CUDA` language can now be compiled using Clang on non-Windows platforms. Separable compilation is not yet supported on any platform.

### Command-Line

- `cmake(1)` gained support for profiling of CMake scripts through the parameters `--profiling-output` and `--profiling-format`.

- `cmake(1)` gained a `cat` command line option that can be used to concatenate files and print them on standard output.

### Commands

- The `add_library()` and `add_executable()` commands learned to create Alias Targets referencing non-`GLOBAL` Imported Targets.

- The `cmake_language()` command was added for meta-operations on scripted or built-in commands, starting with a mode to `CALL` other commands, and `EVAL CODE` to inplace evaluate a CMake script.

- The `execute_process()` command gained the `ECHO_OUTPUT_VARIABLE` and `ECHO_ERROR_VARIABLE` options.

- The `export()` command now raise an error if used multiple times with same `FILE` without `APPEND`. See policy `CMP0103`.

- The `file()` command gained the `ARCHIVE_CREATE` and `ARCHIVE_EXTRACT` subcommands to expose the `cmake(1)` `-E tar` functionality to CMake scripting code.

- The `file(CONFIGURE)` subcommand was created in order to replicate the `configure_file()` functionality without resorting to a pre-existing file on disk as input. The content is instead passed as a string.

- The `file(UPLOAD)` command gained `TLS_VERIFY` and `TLS_CAINFO` options to control server certificate verification.

- The `find_program()`, `find_library()`, `find_path()` and `find_file()` commands gained a new `REQUIRED` option that will stop processing with an error message if nothing is found.

- The `get_property()` command with `SOURCE` scope gained the `DIRECTORY` and `TARGET_DIRECTORY` options to get a property from the provided directory scope.

- The `get_source_file_property()` command gained the `DIRECTORY` and `TARGET_DIRECTORY` options to get a property from the provided directory scope.

- The `list()` operation `SORT` gained the `NATURAL` sort option to sort using natural order (see `strverscmp(3)` manual).

- The `set_property()` command with the `SOURCE` scope gained the `DIRECTORY` and `TARGET_DIRECTORY` options to set properties in the provided directory scopes.

- The `set_source_files_properties()` command gained the `DIRECTORY` and `TARGET_DIRECTORY` options to set properties in the provided directory scopes.

- The `string()` command learned a new `HEX` sub-command, which converts strings into their hexadecimal representation.

### Variables

- A `CMAKE_CUDA_ARCHITECTURES` variable was added to specify CUDA output architectures. Users are encouraged to use this instead of specifying options manually, as this approach is compiler-agnostic. The variable is initialized automatically when `CMAKE_CUDA_COMPILER_ID` is `NVIDIA`. The variable is used to initialize the new `CUDA_ARCHITECTURES` target property. See policy `CMP0104`.

- The `CMAKE_PCH_WARN_INVALID` variable was added to initialize the `PCH_WARN_INVALID` target property to allow the removal of the precompiled header invalid warning.

### Properties

- The `CUDA_ARCHITECTURES` target property was added to specify CUDA output architectures. Users are encouraged to use this instead of specifying options manually, as this approach is compiler-agnostic. The property is initialized by the new `CMAKE_CUDA_ARCHITECTURES` variable. See policy `CMP0104`.

- The `Fortran_PREPROCESS` target property and `Fortran_PREPROCESS` source-file property were added to control preprocessing of Fortran source files.

- The `FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property and associated `CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` variable were created to allow adding a postfix to the name of a framework file name when using a multi-config generator.

- The `OBJECT_OUTPUTS` source file property now supports `generator expressions`.

- The `PCH_WARN_INVALID` target property was added to allow the removal of the precompiled header invalid warning.

- The `UNITY_BUILD_MODE` target property was added to tell generators which algorithm to use for grouping included source files.

- The `VS_SOURCE_SETTINGS_<tool>` target property was added to tell Visual Studio Generators for VS 2010 and above to add metadata to non-built source files using `<tool>`.

- The `VS_SETTINGS` source file property was added to tell Visual Studio Generators for VS 2010 and above to add metadata to a non-built source file.

- The `VS_PLATFORM_TOOLSET` target property was added to tell Visual Studio Generators for VS 2010 and above to override the platform toolset.

- The `VS_SOLUTION_DEPLOY` target property was added to tell Visual Studio Generators for VS 2010 and above to mark a target for deployment even when not building for Windows Phone/Store/CE.

### Modules

- The `CheckLinkerFlag` module has been added to provide a facility to check validity of link flags.

- The `ExternalProject` module `ExternalProject_Add()` command gained a new `GIT_REMOTE_UPDATE_STRATEGY` keyword. This can be used to specify how failed rebase operations during a git update should be handled. The `CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY` variable was also added as a global default and is honored by both the `ExternalProject` and `FetchContent` modules.

- The `FetchContent` module `FetchContent_Declare()` command now supports a `SOURCE_SUBDIR` option. It can be used to direct `FetchContent_MakeAvailable()` to look in a different location for the `CMakeLists.txt` file.

- The `FindBLAS` module now provides an imported target.

- The `FindCUDAToolkit` module:

  - gained the variable `CUDAToolkit_LIBRARY_ROOT`, which is the directory containing the `nvvm` directory and `version.txt`.

  - uses toolkit and library root found during `CUDA` compiler detection.

- The `FindLAPACK` module now provides an imported target.

- The `FindPython3`, `FindPython2` and `FindPython` modules:

  - gained the possibility to create per-artifact cache variables for interactive editing in `cmake-gui(1)` and `ccmake(1)`.

  - gained sub-components `Development.Module` and `Development.Embed` under the `Development` component.

  - gained the capability to specify which Python implementations to find, including `IronPython` and `PyPy`.

- The `FindRuby` module input and output variables were all renamed from `RUBY_` to `Ruby_` for consistency with other find modules. Input variables of the old case will be honored if provided, and output variables of the old case are always provided.

- The `FindSWIG` module now accepts target languages as `COMPONENTS` and `OPTIONAL_COMPONENTS` arguments to `find_package`.

- The `GoogleTest` module `gtest_discover_tests()` command:

  - gained a new `DISCOVERY_MODE` option to control when the test discovery step is run. It offers a new `PRE_TEST` setting to run the discovery at test time instead of build time. A new `CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE` variable can be used to change the default globally.

  - gained a new optional parameter `XML_OUTPUT_DIR`. When set the JUnit XML test results are stored in that directory.

- The `FindLibXslt` module now provides imported targets.

- The `UseSWIG` module now supports Fortran as a target language if the `SWIG_EXECUTABLE` is SWIG-Fortran.

### Generator Expressions

- The `$<DEVICE_LINK:...>` and `$<HOST_LINK:...>` `generator expressions` were added to manage device and host link steps.

- The `$<LINK_LANGUAGE:...>` and `$<LINK_LANG_AND_ID:...>` `generator expressions` were added.

### CTest

- `ctest(1)` gained a new `CTEST_RESOURCE_SPEC_FILE` variable, which can be used to specify a resource specification file.

- `ctest(1)` gained a `--stop-on-failure` option, which can be used to stop running the tests once one has failed.

- The `ctest_test()` command gained a `STOP_ON_FAILURE` option which can be used to stop running the tests once one has failed.

- The `CTestCoverageCollectGCOV` module `ctest_coverage_collect_gcov()` command gained a `TARBALL_COMPRESSION` option to control compression of the tarball of collected results.

### CPack

- The `CPack Archive Generator`’s `TXZ` format learned the `CPACK_ARCHIVE_THREADS` variable to enable parallel compression. Requires support in the `liblzma` used by CMake.

- The `CPack NSIS Generator` gained a new variable `CPACK_NSIS_MANIFEST_DPI_AWARE` to declare that the installer is DPI-aware.

- The `CPack RPM Generator` gained `CPACK_RPM_PRE_TRANS_SCRIPT_FILE` and `CPACK_RPM_POST_TRANS_SCRIPT_FILE` variables to specify pre- and post-transaction scripts.

### Other

- `cmake-gui(1)` now populates its generator selection widget default value from the `CMAKE_GENERATOR` environment variable. Additionally, environment variables `CMAKE_GENERATOR_PLATFORM` and `CMAKE_GENERATOR_TOOLSET` are used to populate their respective widget defaults.

- `ccmake(1)` learned to read a `CCMAKE_COLORS` environment variable to customize colors.

## Deprecated and Removed Features

- The `Documentation` module has been deprecated via `CMP0106`. This module was essentially VTK code that CMake should not be shipping anymore.

- An explicit deprecation diagnostic was added for policy `CMP0070` and policy `CMP0071` (`CMP0069` 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

- On Windows, the `Ninja` and `Ninja Multi-Config` generators, when a compiler is not explicitly specified, now select the first compiler (of any name) found in directories listed by the `PATH` environment variable.

- The `LINK_OPTIONS` and `INTERFACE_LINK_OPTIONS` target properties are now used for the device link step. See policy `CMP0105`.

- Creation of an `ALIAS` target overwriting an existing target now raises an error. See policy `CMP0107`.

- Linking a target to itself through an alias now raises an error. See policy `CMP0108`.

- The `FindPackageHandleStandardArgs` module option `REQUIRED_VARS` is now optional if `HANDLE_COMPONENTS` is specified.

- The `source_group()` command now also recognizes forward slashes as subgroup delimiters, not just backslashes.

- `ctest(1)` now logs environment variables that it sets for each test, either due to the `ENVIRONMENT` property or the resource allocation feature, and submits this log to CDash. It does not log environment variables that were set outside of CTest.

- When building CMake itself from source and not using a system-provided libcurl, HTTP/2 support is now enabled for commands supporting network communication via `http(s)`, such as `file(DOWNLOAD)`, `file(UPLOAD)`, and `ctest_submit()`. The precompiled binaries provided on `cmake.org` now support HTTP/2.

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

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