# CMake 3.12 Release Notes

Contents

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

Changes made since CMake 3.11 include the following.

## New Features

### Generators

- The Visual Studio Generators for VS 2017 learned to support a `version=14.##` option in the `CMAKE_GENERATOR_TOOLSET` value (e.g. via the `cmake(1)` `-T` option) to specify a toolset version number.

### Command-Line

- The `cmake(1)` Build Tool Mode (`cmake --build`) gained `--parallel [<jobs>]` and `-j [<jobs>]` options to specify a parallel build level. They map to corresponding options of the native build tool.

### Commands

- The `add_compile_definitions()` command was added to set preprocessor definitions at directory level. This supersedes `add_definitions()`.
- The `cmake_minimum_required()` and `cmake_policy(VERSION)` commands now accept a version range using the form `<min>[...<max>]`. The `<min>` version is required but policies are set based on the `<max>` version. This allows projects to specify a range of versions for which they have been updated and avoid explicit policy settings.
- The `file(GLOB)` and `file(GLOB_RECURSE)` commands learned a new flag `CONFIGURE_DEPENDS` which enables expression of build system dependency on globbed directory’s contents.
- The `file(TOUCH)` and `file(TOUCH_NOCREATE)` commands were added to expose `TOUCH` functionality without having to use CMake’s command-line tool mode with `execute_process()`.
- The `find_package()` command now searches a prefix specified by a `PackageName_ROOT` CMake or environment variable. Package roots are maintained as a stack so nested calls to all `find_*` commands inside find modules also search the roots as prefixes. See policy `CMP0074`.
- The `install()` command learned an optional `NAMELINK_COMPONENT` parameter, which allows you to change the component for a shared library’s namelink. If none is specified, the value of `COMPONENT` is used by default.
- The `list()` command learned a `JOIN` sub-command to concatenate list’s elements separated by a glue string.
- The `list()` command learned a `SUBLIST` sub-command to get a sublist of the list.
- The `list()` command learned a `TRANSFORM` sub-command to apply various string transformation to list’s elements.
- The `project()` command learned an optional `HOMEPAGE_URL` parameter which has the effect of setting variables like `PROJECT_HOMEPAGE_URL`, `<PROJECT-NAME>_HOMEPAGE_URL` and `CMAKE_PROJECT_HOMEPAGE_URL`.
- The `string()` command learned a `JOIN` sub-command to concatenate input strings separated by a glue string.
- `target_compile_options()` and `add_compile_options()` commands gained a `SHELL:` prefix to specify a group of related options using shell-like quoting.
- The `target_link_libraries()` command now supports Object Libraries. Linking to an object library uses its object files in direct dependents and also propagates usage requirements.
- The `target_link_libraries()` command may now be called to modify targets created outside the current directory.

### Variables

- The `CMAKE_FOLDER` variable was added to initialize the `FOLDER` property on all targets.
- The `CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable was defined to initialize all `DOTNET_TARGET_FRAMEWORK_VERSION` target properties.
- `CMAKE_PROJECT_VERSION*` variables have been introduced:
  - `CMAKE_PROJECT_VERSION`
  - `CMAKE_PROJECT_VERSION_MAJOR`
  - `CMAKE_PROJECT_VERSION_MINOR`
  - `CMAKE_PROJECT_VERSION_PATCH`
  - `CMAKE_PROJECT_VERSION_TWEAK`
- The `CMAKE_SUPPRESS_REGENERATION` variable was extended to support the `Ninja` and Makefile Generators. It is also now documented.
- `CMAKE_VS_SDK_*_DIRECTORIES` variables were defined to tell Visual Studio Generators for VS 2010 and above how to populate fields in `.vcxproj` files that specify SDK directories. The variables are:
  - `CMAKE_VS_SDK_EXCLUDE_DIRECTORIES`
  - `CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES`
  - `CMAKE_VS_SDK_INCLUDE_DIRECTORIES`
  - `CMAKE_VS_SDK_LIBRARY_DIRECTORIES`
  - `CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES`
  - `CMAKE_VS_SDK_REFERENCE_DIRECTORIES`
  - `CMAKE_VS_SDK_SOURCE_DIRECTORIES`
- A `MSVC_TOOLSET_VERSION` variable was added to provide the MSVC toolset version associated with the current MSVC compiler version in `MSVC_VERSION`.

### Properties

- The `COMMON_LANGUAGE_RUNTIME` target property was introduced to configure the use of managed C++ for Visual Studio Generators for VS 2010 and above. A corresponding `IMPORTED_COMMON_LANGUAGE_RUNTIME` target property was added to support `C++/CLI` for imported targets.
- The `DOTNET_TARGET_FRAMEWORK_VERSION` target property was introduced as replacement for `VS_DOTNET_TARGET_FRAMEWORK_VERSION`, which is considered deprecated now.
- An `EXPORT_PROPERTIES` target property was added to specify a custom list of target properties to include in targets exported by the `install(EXPORT)` and `export()` commands.
- The `PDB_OUTPUT_DIRECTORY` property learned to support `generator expressions`.
- A `TESTS` directory property was added to hold the list of tests defined by the `add_test()` command.
- A `VS_DEBUGGER_COMMAND` target property was created to set the debugging command line with Visual Studio Generators for VS 2010 and above.
- HLSL source file properties `VS_SHADER_DISABLE_OPTIMIZATIONS` and `VS_SHADER_ENABLE_DEBUG` gained support for generator expressions.
- HLSL source file property `VS_SHADER_OBJECT_FILE_NAME` has been added to the Visual Studio Generators for VS 2010 and above. The property specifies the file name of the compiled shader object.

### Modules

- The `FindALSA` module now provides imported targets.
- The `FindCURL` module now provides imported targets.
- The `FindJPEG` module now provides imported targets.
- The `FindLibXml2` module now provides imported targets.
- The `FindMatlab` module now supports the Matlab Runtime Compiler (MCR) for compiling and linking matlab extensions.
- A `FindODBC` module was added to find an Open Database Connectivity (ODBC) library.
- The `FindPkgConfig` module has learned to export the found libraries with full path for direct consumption with the `target_link_libraries()` command.
- New `FindPython3` and `FindPython2` modules, as well as a new `FindPython` module, have been added to provide a new way to locate python environments.
- The `UseSWIG` module gained a whole refresh and is now more consistent with standard CMake commands to generate libraries and is fully configurable through properties.
- The `UseSWIG` module learned to manage multiple behaviors through `UseSWIG_MODULE_VERSION` variable to ensure legacy support as well as more robust handling of `SWIG` advanced features (like `%template`).
- The `UseSWIG` module learned to support CSHARP variant wrapper files.
- The `WriteCompilerDetectionHeader` module gained a `BARE_FEATURES` option to add a compatibility define for the exact keyword of a new language feature.

### Generator Expressions

- A new `$<GENEX_EVAL:...>` and `$<TARGET_GENEX_EVAL:target,...>` `generator expression` has been added to enable consumption of generator expressions whose evaluation results itself in generator expressions.
- A new `$<IN_LIST:...>` `generator expression` has been added.
- A new `$<TARGET_EXISTS:...>` `generator expression` has been added.
- A new `$<TARGET_NAME_IF_EXISTS:...>` `generator expression` has been added.

### CTest

- The `ctest_start()` command has been reworked so that you can simply call `ctest_start(APPEND)` and it will read all the needed information from the TAG file. The argument parsing has also been relaxed so that the order of the arguments is less significant.
- A `PROCESSOR_AFFINITY` test property was added to request that CTest run a test with CPU affinity for a set of processors disjoint from other concurrently running tests with the property set.

### CPack

- The `CPack` module now uses variables `CMAKE_PROJECT_VERSION_MAJOR`, `CMAKE_PROJECT_VERSION_MINOR` and `CMAKE_PROJECT_VERSION_PATCH` to initialize corresponding CPack variables.
- `cpack(1)` gained basic support for NuGet. See the `CPackNuGet` module.

### Other

- The `Compile Features` functionality is now aware of C++ 20. No specific features are yet enumerated besides the `cxx_std_20` meta-feature.
- The `Compile Features` functionality is now aware of the availability of C features in MSVC since VS 2010.
- The `Compile Features` functionality is now aware of C language standards supported by Texas Instruments C compilers.

## Deprecated and Removed Features

- The `Visual Studio 8 2005` generator has been removed.
- CMake no longer produces `<tgt>_LIB_DEPENDS` cache entries for library targets. See policy `CMP0073`.

## Other Changes

- Include flags for directories marked as `SYSTEM` are now moved after non-system directories. The `-isystem` flag does this automatically, so moving them explicitly to the end makes the behavior consistent on compilers that do not have any `-isystem` flag.
- Fortran dependency scanning now supports dependencies implied by Fortran Submodules.
- The existence and functionality of the file `${CMAKE_BINARY_DIR}/cmake_install.cmake` has now been documented in the `install()` documentation so that external packaging software can take advantage of CPack-style component installs.
- The `CheckIncludeFile` module `check_include_file` macro learned to honor the `CMAKE_REQUIRED_LIBRARIES` variable. See policy `CMP0075`.
- The `CheckIncludeFileCXX` module `check_include_file_cxx` macro learned to honor the `CMAKE_REQUIRED_LIBRARIES` variable. See policy `CMP0075`.
- The `CheckIncludeFiles` module `check_include_files` macro learned to honor the `CMAKE_REQUIRED_LIBRARIES` variable. See policy `CMP0075`.
- The `cmake(1)` `-E copy_directory` tool now fails when the source directory does not exist. Previously it succeeded by creating an empty destination directory.
- The `UseSWIG` module `swig_add_library()` command (and legacy `swig_add_module` command) now set the prefix of Java modules to `""` for MINGW, MSYS, and CYGWIN environments.