# CMake 3.11 Release Notes

Contents

- CMake 3.11 Release Notes
  - New Features
    - Platforms
    - Generators
    - Commands
    - Variables
    - Properties
    - Modules
    - Autogen
    - CTest
    - CPack
    - Other
  - Deprecated and Removed Features
  - Other Changes
  - Updates
    - 3.11.1

Changes made since CMake 3.10 include the following.

## New Features

### Platforms

- TI C/C++ compilers are now supported by the `Ninja` generator.

### Generators

- The `CodeBlocks` extra generator learned to check a `CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom compiler identification value to place in the project file.
- The Makefile Generators and the `Ninja` generator learned to add compiler launcher tools along with the compiler for the `Fortran` language (`C`, `CXX`, and `CUDA` were supported previously). See the `CMAKE_<LANG>_COMPILER_LAUNCHER` variable and `<LANG>_COMPILER_LAUNCHER` target property for details.
- Visual Studio Generators learned to support the `COMPILE_LANGUAGE` `generator expression` in target-wide `COMPILE_DEFINITIONS`, `INCLUDE_DIRECTORIES`, `COMPILE_OPTIONS`, and `file(GENERATE)`. See generator expression documentation for caveats.
- The `Xcode` generator learned to support the `COMPILE_LANGUAGE` `generator expression` in target-wide `COMPILE_DEFINITIONS` and `INCLUDE_DIRECTORIES`. It previously supported only `COMPILE_OPTIONS` and `file(GENERATE)`. See generator expression documentation for caveats.

### Commands

- `add_library()` and `add_executable()` commands can now be called without any sources and will not complain as long as sources are added later via the `target_sources()` command.
- The `file(DOWNLOAD)` and `file(UPLOAD)` commands gained `NETRC` and `NETRC_FILE` options to specify use of a `.netrc` file.
- The `target_compile_definitions()` command learned to set the `INTERFACE_COMPILE_DEFINITIONS` property on Imported Targets.
- The `target_compile_features()` command learned to set the `INTERFACE_COMPILE_FEATURES` property on Imported Targets.
- The `target_compile_options()` command learned to set the `INTERFACE_COMPILE_OPTIONS` property on Imported Targets.
- The `target_include_directories()` command learned to set the `INTERFACE_INCLUDE_DIRECTORIES` property on Imported Targets.
- The `target_sources()` command learned to set the `INTERFACE_SOURCES` property on Imported Targets.
- The `target_link_libraries()` command learned to set the `INTERFACE_LINK_LIBRARIES` property on Imported Targets.

### Variables

- A `CMAKE_GENERATOR_INSTANCE` variable was introduced to hold the selected instance of the generator’s corresponding native tools if multiple are available. This is used by the `Visual Studio 15 2017` generator to hold the selected instance of Visual Studio persistently.
- A `CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added to enable setting of default permissions for directories created implicitly during installation of files by `install()` and `file(INSTALL)`, e.g. during `make install`.
- A `CMAKE_JOB_POOLS` variable was added specify a value to use for the `JOB_POOLS` property. This enables control over build parallelism with command line configuration parameters when using the Ninja generator.
- The `CMAKE_NETRC` and `CMAKE_NETRC_FILE` variables were added to specify use of a `.netrc` file by the `file(DOWNLOAD)` and `file(UPLOAD)` commands and the `ExternalProject` module.
- A `CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to initialize the `CUDA_SEPARABLE_COMPILATION` target property on targets when they are created.

### Properties

- The `COMPILE_DEFINITIONS` source file property learned to support `generator expressions`.
- A `COMPILE_OPTIONS` source file property was added to manage list of options to pass to the compiler.
- An `IMPORTED_GLOBAL` target property was added to indicate whether an IMPORTED target is globally visible. It is automatically set to a true value for targets created with the `GLOBAL` option to `add_library()` or `add_executable()`. Additionally, project code may now promote a local imported target to be globally visible by setting this property to `TRUE`.
- An `INCLUDE_DIRECTORIES` source file property was added to specify list of preprocessor include file search directories.
- Source file properties `VS_SHADER_DISABLE_OPTIMIZATIONS` and `VS_SHADER_ENABLE_DEBUG` have been added to specify more details of `.hlsl` sources with Visual Studio Generators.

### Modules

- The `CheckIncludeFiles` module `CHECK_INCLUDE_FILES()` command gained a `LANGUAGE` option to specify whether to check using the `C` or `CXX` compiler.
- The `CMakePackageConfigHelpers` module `write_basic_package_version_file()` command learned a new `SameMinorVersion` mode for the `COMPATIBILITY` argument.
- The `ExternalProject` module learned to substitute `<DOWNLOAD_DIR>` in comments, commands, working directory and byproducts.
- The `ExternalProject` module gained `NETRC` and `NETRC_FILE` options to specify use of a `.netrc` file.
- A new `FetchContent` module was added which supports populating content at configure time using any of the download/update methods supported by `ExternalProject_Add()`. This allows the content to be used immediately during the configure stage, such as with `add_subdirectory()`, etc. Hierarchical project structures are well supported, allowing parent projects to override the content details of child projects and ensuring content is not populated multiple times throughout the whole project tree.
- The `FindBLAS` and `FindLAPACK` modules learned to support FLAME `blis` and `libflame`.
- The `FindDoxygen` module `doxygen_add_docs()` function now supports a new `DOXYGEN_VERBATIM_VARS` list variable. Any `DOXYGEN_...` variable contained in that list will bypass the automatic quoting logic, leaving its contents untouched when transferring them to the output `Doxyfile`.
- A `FindIconv` module was added to locate iconv support.
- The `GenerateExportHeader` module `GENERATE_EXPORT_HEADER` command gained an `INCLUDE_GUARD_NAME` option to change the name of the include guard symbol written to the generated export header. Additionally, it now adds a comment after the closing `#endif` on the generated export header’s include guard.
- The `UseJava` module `add_jar` command gained a `GENERATE_NATIVE_HEADERS` option to generate native header files using `javac -h` for `javac` 1.8 or above. This supersedes `create_javah`, which no longer works with JDK 1.10 and above due to removal of the `javah` tool by JEP 313.

### Autogen

- When using `AUTOMOC` or `AUTOUIC`, CMake now starts multiple parallel `moc` or `uic` processes to reduce the build time. A new `CMAKE_AUTOGEN_PARALLEL` variable and `AUTOGEN_PARALLEL` target property may be set to specify the number of parallel `moc` or `uic` processes to start. The default is derived from the number of CPUs on the host.

### CTest

- The `ctest_start()` command no longer sets `CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is called from inside a function. Instead, it sets an internal variable in CTest. However, setting `CTEST_RUN_CURRENT_SCRIPT` to 0 at the global scope still prevents the script from being re-run at the end.

### CPack

- `cpack(1)` gained `--trace` and `--trace-expand` options.
- The `CPackIFW` module gained new `CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control if the target directory should not be deleted when uninstalling.
- The `CPackRPM` module learned to enable enforcing of execute privileges on programs and shared libraries. See `CPACK_RPM_INSTALL_WITH_EXEC` variable.
- A `CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added which serves the same purpose during packaging (e.g. `make package`) as the `CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during installation (e.g. `make install`).

### Other

- Alias Targets may now alias Imported Targets that are created with the `GLOBAL` option to `add_library()`.
- Interface Libraries may now have custom properties set on them if they start with either an underscore (`_`) or a lowercase ASCII character. The original intention was to only allow properties which made sense for `INTERFACE` libraries, but it also blocked usage of custom properties.
- The `cmake(1)` `--open <dir>` command-line option was added to open generated IDE projects like Visual Studio solutions or Xcode projects.

## Deprecated and Removed Features

- An explicit deprecation diagnostic was added for policies `CMP0037` through `CMP0054` (`CMP0036` 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 `KDevelop3` generator has been removed.

## Other Changes

- Policy `CMP0037` no longer reserves target names associated with optional features, such as `test` and `package`, unless the corresponding feature is enabled.
- The `FindOpenGL` module now prefers GLVND libraries if available. See policy `CMP0072`.
- The minimum deployment target set in the `CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only applied for macOS regardless of the selected SDK. It is now properly set for the target platform selected by `CMAKE_OSX_SYSROOT`. For example, if the sysroot variable specifies an iOS SDK then the value in `CMAKE_OSX_DEPLOYMENT_TARGET` is interpreted as minimum iOS version.
- The `Xcode` generator behavior of generating one project file per `project()` command may now be controlled with the `CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable. This could be useful to speed up the CMake generation step for large projects and to work-around a bug in the `ZERO_CHECK` logic.
- Since the `CMakeCache.txt` format does not support newlines in values, values containing newlines are now truncated before writing to the file. In addition, a warning comment is written to the cache file, and a warning message is displayed to the user on the console.

## Updates

Changes made since CMake 3.11.0 include the following.

### 3.11.1

- The `CheckIncludeFile` module `check_include_file` macro, `CheckIncludeFileCXX` module `check_include_file_cxx` macro, and `CheckIncludeFiles` module `check_include_files` macro were taught to honor the `CMAKE_REQUIRED_LIBRARIES` variable in CMake 3.11.0. This has been reverted due to changing behavior of checks for existing projects. It may be restored in the future with a policy for compatibility.