CMake 3.8 Release Notes — CMake 3.31.6 Documentation

# CMake 3.8 Release Notes

Changes made since CMake 3.7 include the following.

## New Features

### Languages

#### C#

- CMake learned to support `CSharp` (C#) as a first-class language that can be enabled via the `project()` and `enable_language()` commands. It is currently supported by the Visual Studio Generators for VS 2010 and above.

  C# assemblies and programs can be added just like common C++ targets using the `add_library()` and `add_executable()` commands. References between C# targets in the same source tree may be specified by `target_link_libraries()` like for C++. References to system or 3rd-party assemblies may be specified by the target properties `VS_DOTNET_REFERENCE_<refname>` and `VS_DOTNET_REFERENCES`.

- More fine tuning of C# targets may be done using target and source file properties. Specifically the target properties related to Visual Studio (`VS_*`) are worth a look (for setting toolset versions, root namespaces, assembly icons, ...).

#### CUDA

- CMake learned to support `CUDA` as a first-class language that can be enabled via the `project()` and `enable_language()` commands.

- `CUDA` is currently supported by the Makefile Generators and the `Ninja` generator on Linux, macOS, and Windows. Support for the Visual Studio IDE is under development but not included in this release.

- The NVIDIA CUDA Toolkit compiler (`nvcc`) is supported.

#### C & C++

- The `Compile Features` functionality now offers meta-features that request compiler modes for specific language standard levels (e.g. `cxx_std_11`). See `CMAKE_C_KNOWN_FEATURES` and `CMAKE_CXX_KNOWN_FEATURES`.

- The `Compile Features` functionality is now aware of C++ 17. No specific features are yet enumerated besides the `cxx_std_17` meta-feature.

- The `Compile Features` functionality is now aware of the availability of C99 in gcc since version 3.4.

### Platforms

- A new minimal platform file for `Fuchsia` was added.

### Generators

- The `CodeBlocks` extra generator may now be used to generate with `NMake Makefiles JOM`.

- The Visual Studio Generators for VS 2013 and above learned to support a `host=x64` option in the `CMAKE_GENERATOR_TOOLSET` value (e.g. via the `cmake(1)` `-T` option) to request use of a VS 64-bit toolchain on 64-bit hosts.

- The Visual Studio Generators learned to treat files passed to `target_link_libraries()` whose names end in `.targets` as MSBuild "targets" files to be imported into generated project files.

### Commands

- The `add_custom_command()` and `add_custom_target()` commands learned the option `COMMAND_EXPAND_LISTS` which causes lists in the `COMMAND` argument to be expanded, including lists created by generator expressions.

- The `execute_process()` command gained an `ENCODING` option to specify on Windows which encoding is used for output from child process.

- The `math(EXPR)` command gained support for unary `+` and `-` operators.

- The `source_group()` command gained `TREE` and `PREFIX` options to add groups following source tree directory structure.

- The `string(TIMESTAMP)` command learned to treat `%%` as a way to encode plain `%`.

- The `string(TIMESTAMP)` command will now honor the `SOURCE_DATE_EPOCH` environment variable and use its value instead of the current time.

- The `try_compile()` command source file signature gained new options to specify the language standard to use in the generated test project.

- The `try_compile()` command source file signature now honors language standard variables like `CMAKE_CXX_STANDARD`. See policy `CMP0067`.

### Variables

- A `CMAKE_CODELITE_USE_TARGETS` variable was added to tell the `CodeLite` extra generator to change the generated project to have target-centric organization. The `build`, `rebuild`, and `clean` operations within `CodeLite` then work on a selected target rather than the whole workspace. (Note that the `Ninja` clean operation on a target includes its dependencies, though.)

- The `CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS` variable was added to tell the `Sublime Text 2` extra generator to place specified environment variables in the generated `.sublime-project`.

- The `CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable was added to tell the `Sublime Text 2` extra generator whether to exclude the build tree from the `.sublime-project` when it is inside the source tree.

- A `CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD` variable was added to tell Visual Studio Generators for VS 2010 and above to include the `PACKAGE` target in the default build, similar to the existing `CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` variable for the `INSTALL` target.

### Properties

- A `BUILD_RPATH` target property and corresponding `CMAKE_BUILD_RPATH` variable were added to support custom `RPATH` locations to be added to binaries in the build tree.

- The `COMPILE_FLAGS` source file property learned to support `generator expressions`.

- The `FRAMEWORK` target property may now also be applied to static libraries on Apple targets. It will result in a proper Framework but with a static library inside.

- Imported Interface Libraries learned new `IMPORTED_LIBNAME` and `IMPORTED_LIBNAME_<CONFIG>` target properties to specify a link library name since interface libraries do not build their own library files.

- A `<LANG>_CPPLINT` target property and supporting `CMAKE_<LANG>_CPPLINT` variable were introduced to tell the Makefile Generators and the `Ninja` generator to run the `cpplint` style checker along with the compiler for `C` and `CXX` languages.

- A `MANUALLY_ADDED_DEPENDENCIES` target property has been added. It provides a read-only list of dependencies that have been added with the `add_dependencies()` command.

- The `MAP_IMPORTED_CONFIG_<CONFIG>` target property learned to interpret empty list elements as referring to the configuration-less imported location specified by `IMPORTED_LOCATION`.

- The `NO_SYSTEM_FROM_IMPORTED` target property is now supported on Imported Interface Libraries.

- New source file properties `SKIP_AUTOMOC`, `SKIP_AUTOUIC`, `SKIP_AUTORCC`, and `SKIP_AUTOGEN` were added to allow source files to be excluded from processing by `AUTOMOC`, `AUTOUIC`, and `AUTORCC` target properties.

- A `VS_COPY_TO_OUT_DIR` source file property was added to tell Visual Studio Generators for VS 2010 and above whether or not a file should e copied to the output directory.

- A `VS_DEBUGGER_WORKING_DIRECTORY` target property was added to tell Visual Studio Generators for VS 2010 and above what debugger working directory should be set for the target.

- A `VS_DOTNET_REFERENCES_COPY_LOCAL` target property was added to specify whether to copy referenced assemblies to the output directory.

- A `VS_DOTNET_REFERENCE_<refname>` target property was added to tell Visual Studio Generators for VS 2010 and above to add a .NET reference with a given hint path.

- A `VS_INCLUDE_IN_VSIX` source file property was added to tell Visual Studio Generators for VS 2010 and above whether to include the file in a Visual Studio extension package.

- A `VS_RESOURCE_GENERATOR` source file property was added to give Visual Studio Generators for VS 2010 and above a setting for the resource generator (`C#` only).

- A `VS_USER_PROPS` target property was added to tell Visual Studio Generators for VS 2010 and above to use a custom MSBuild user `.props` file.

- A `XCODE_EMIT_EFFECTIVE_PLATFORM_NAME` global property was added to tell the `Xcode` generator whether to emit the `EFFECTIVE_PLATFORM_NAME` variable. This is useful when building with multiple SDKs like `macosx` and `iphoneos` in parallel.

- New `XCODE_PRODUCT_TYPE` and `XCODE_EXPLICIT_FILE_TYPE` target properties were created to tell the `Xcode` generator to use custom values of the corresponding attributes for a target in the generated Xcode project.

### Modules

- A `CSharpUtilities` module was added to aid parameterization of Visual Studio C# targets. It provides functions to allow automated setting of source file properties to support Windows Forms, WPF/XAML or other technologies as needed.

- The `ExternalData` module learned to support multiple content links for one data file using different hashes, e.g. `img.png.sha256` and `img.png.sha1`. This allows objects to be fetched from sources indexed by different hash algorithms.

- The `ExternalProject` module gained the `GIT_PROGRESS` option to force Git to show progress when cloning repositories.

- The `ExternalProject` module gained a `GIT_CONFIG` option to pass `--config` options to Git when cloning repositories.

- The `FeatureSummary` module `feature_summary()` command now accepts a new `QUIET_ON_EMPTY` option that suppresses the output when the list of packages that belong to the selected category is empty.

- The `FeatureSummary` module `add_feature_info()` command now accepts lists of dependencies for deciding whether a feature is enabled or not.

- The package types accepted by the `FeatureSummary` module can now be tweaked by changing the `FeatureSummary_PKG_TYPES`, `FeatureSummary_REQUIRED_PKG_TYPES` and `FeatureSummary_DEFAULT_PKG_TYPE` global properties.

- The `FindOpenGL` module now provides imported targets `OpenGL::GL` and `OpenGL::GLU` when the libraries are found.

- The `UseSWIG` module gained a `swig_add_library` command to give more flexibility over the old `swig_add_module` command.

- The `UseSWIG` module `swig_add_source_to_module` command learned a new `SWIG_OUTFILE_DIR` option to control the output file location (`swig -o`).

- The `WriteCompilerDetectionHeader` module gained the `ALLOW_UNKNOWN_COMPILERS` and `ALLOW_UNKNOWN_COMPILER_VERSIONS` options that allow creation of headers that will work also with unknown or old compilers by simply assuming they do not support any of the requested features.

### CTest

- The `ctest_memcheck()` command gained a `DEFECT_COUNT <var>` option to capture the number of memory defects detected.

- The `ctest_memcheck()` command learned to read the location of suppressions files for sanitizers from the `CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` variable.

- The `ctest_memcheck()` command learned to support `LeakSanitizer` independently from `AddressSanitizer`.

- The `ctest_update()` command `CDASH_UPLOAD` signature was taught to honor the `RETRY_COUNT`, `RETRY_DELAY`, and `QUIET` options.

### CPack

- The `CPackIFWConfigureFile` module was added to define a new `cpack_ifw_configure_file()` command to configure file templates prepared in QtIFW/SDK/Creator style.

- The `CPackIFW` module `cpack_ifw_configure_component()` and `cpack_ifw_configure_component_group()` commands gained a new `DEFAULT`, `VIRTUAL`, `FORCED_INSTALLATION`, `REQUIRES_ADMIN_RIGHTS`, `DISPLAY_NAME`, `UPDATE_TEXT`, `DESCRIPTION`, `RELEASE_DATE`, `AUTO_DEPEND_ON` and `TRANSLATIONS` options to more specific configuration.

- The `CPackIFW` module `cpack_ifw_configure_component()` command gained a new `DEPENDENCIES` alias for `DEPENDS` option.

- The `CPackIFW` module `cpack_ifw_configure_component_group()` command gained a new `DEPENDS` option. The `DEPENDENCIES` alias also added.

- The `CPackIFW` module `cpack_ifw_configure_component()` and `cpack_ifw_configure_component_group()` commands `PRIORITY` option now is deprecated and will be removed in a future version of CMake. Please use new `SORTING_PRIORITY` option instead.

- The `CPack IFW Generator` gained new `CPACK_IFW_PACKAGE_WATERMARK`, `CPACK_IFW_PACKAGE_BANNER`, `CPACK_IFW_PACKAGE_BACKGROUND`, `CPACK_IFW_PACKAGE_WIZARD_STYLE`, `CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH`, `CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT`, and `CPACK_IFW_PACKAGE_TITLE_COLOR` variables to customize a QtIFW installer look.

- The `CPack productbuild Generator` gained options to sign packages. See the variables `CPACK_PRODUCTBUILD_IDENTITY_NAME`, `CPACK_PRODUCTBUILD_KEYCHAIN_PATH`, `CPACK_PKGBUILD_IDENTITY_NAME`, and `CPACK_PKGBUILD_KEYCHAIN_PATH`.

- The `CPack RPM Generator` learned to omit tags that are not supported by provided `rpmbuild` tool. If unsupported tags are set they are ignored and a developer warning is printed out.

- The `CPack RPM Generator` learned to generate main component package which forces generation of a rpm for defined component without component suffix in filename and package name. See `CPACK_RPM_MAIN_COMPONENT` variable.

- The `CPack RPM Generator` learned to generate a single `debuginfo` package on demand even if components packaging is used. See `CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable.

- The `CPack RPM Generator` learned to support multiple directives per file when using `CPACK_RPM_USER_FILELIST` variable.

### Other

- CMake functionality using cryptographic hashes now supports SHA-3 algorithms.

- A new generator expression `$<IF:cond,true-value,false-value>` was added. It resolves to the true-value if the condition is `1` and resolves to the false-value if the condition is `0`.

## Deprecated and Removed Features

- The `FeatureSummary` module commands `set_package_info()`, `set_feature_info()`, `print_enabled_features()`, and `print_disabled_features()` are now deprecated.

- The `UseSWIG` module `swig_add_module` command is now deprecated in favor of `swig_add_library`.

## Other Changes

- If a command specified by the `<LANG>_CLANG_TIDY` target property returns non-zero at build time this is now treated as an error instead of silently ignored.

- The `ctest_memcheck()` command no longer automatically adds `leak_check=1` to the options used by `AddressSanitizer`. The default behavior of `AddressSanitizer` is to run LeakSanitizer to check leaks unless `leak_check=0`.

- The `ctest_memcheck()` command was fixed to correctly append extra sanitizer options read from the `CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable to the environment variables used internally by the sanitizers.

- The `FeatureSummary` module `set_package_properties()` command no longer forces the package type to `OPTIONAL` when the type is not explicitly set.

- The `Compile Features` functionality is now aware of features supported by Intel C++ compilers versions 12.1 through 17.0 on UNIX and Windows platforms.

- Calls to the `FindPkgConfig` module `pkg_check_modules()` command following a successful call learned to re-evaluate the cached values for a given prefix after changes to the parameters to the command for that prefix.

- When using `AUTOMOC` or `AUTOUIC`, generated `moc_*`, `*.moc` and `ui_*` are placed in the `<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include` directory which is automatically added to the target's `INCLUDE_DIRECTORIES`. It is therefore not necessary anymore to have `CMAKE_CURRENT_BINARY_DIR` in the target's `INCLUDE_DIRECTORIES`.

- The `Sublime Text 2` generator no longer runs the native build command (e.g. `ninja` or `make`) with verbose build output enabled.

- The `try_compile()` command source file signature now honors the `CMAKE_WARN_DEPRECATED` variable value in the generated test project.

- The Visual Studio Generators for VS 2010 and above now place per-source file flags after target-wide flags when they are classified as raw flags with no project file setting (`AdditionalOptions`). This behavior is more consistent with the ordering of flags produced by other generators, and allows flags on more-specific properties (per-source) to override those on more general ones (per-target).

- The precompiled Windows binary MSI package provided on `cmake.org` now records the installation directory in the Windows Registry under the key `HKLM\Software\Kitware\CMake` with a value named `InstallDir`.