CMake 3.9 Release Notes

Changes made since CMake 3.8 include the following.

New Features

Languages

• CUDA is now supported by the Visual Studio Generators for VS 2010 and above. This complements the existing support by the Makefile Generators and the Ninja generator. CUDA 8.0.61 or higher is recommended due to known bugs in the VS integration by earlier versions.

• CMake is now aware of the C++ standards and C standards and their associated meta-features for the following compiler ids: Cray, PGI, and XL.

Generators

• Visual Studio Generators for VS 2010 and above learned to support the ASM_NASM language when nasm is installed.

• The Xcode generator learned to create Xcode schema files. This is an experimental feature and can be activated by setting the CMAKE_XCODE_GENERATE_SCHEME variable to a TRUE value.

Commands

• The add_library() command IMPORTED option learned to support Object Libraries.

• The find_library() command learned to search libx32 paths when the build targets the x32 ABI. See the FIND_LIBRARY_USE_LIBX32_PATHS global property.

• The include_external_msproject() command learned to use the MAP_IMPORTED_CONFIG_<CONFIG> target property to map current configurations to the external configurations.

• The install(TARGETS) command learned a new OBJECTS option to specify where to install Object Libraries.

• The install(EXPORT) command learned how to export Object Libraries.

• The project() command learned an optional DESCRIPTION parameter to set the PROJECT_DESCRIPTION variable.

• The separate_arguments() command gained a NATIVE_COMMAND mode that performs argument separation depending on the host operating system.

Variables

• A CMAKE_ANDROID_NDK_DEPRECATED_HEADERS variable was added for use when Cross Compiling for Android with the NDK to request use of the deprecated headers even when unified headers are available. The default is now to use unified headers if available.

• A CMAKE_AUTOMOC_DEPEND_FILTERS variable was introduced to allow CMAKE_AUTOMOC to extract additional dependency file names for moc from the contents of source files.

• A CMAKE_AUTOUIC_SEARCH_PATHS variable was introduced to allow CMAKE_AUTOUIC to search for foo.ui in more places than the vicinity of the file including ui_foo.h.

• A CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable was added to tell the find_library() command to search in a lib<suffix> directory before each lib directory that would normally be searched.

• A CMAKE_INTERPROCEDURAL_OPTIMIZATION variable was added to initialize the INTERPROCEDURAL_OPTIMIZATION property on all targets.

• A CMAKE_<LANG>_COMPILER_AR variable was added to hold the path to the GCC/Clang wrapper of ar.

• A CMAKE_<LANG>_COMPILER_RANLIB variable was added to hold the path to the GCC/Clang wrapper of ranlib.

• The CMAKE_SYSROOT_COMPILE and CMAKE_SYSROOT_LINK variables were added to use separate sysroots for compiling and linking.

Properties

• A new AUTOGEN_BUILD_DIR target property was introduced to set a custom output directory for AUTOMOC, AUTOUIC, and AUTORCC.

• A new AUTOMOC_DEPEND_FILTERS target property was introduced to allow AUTOMOC to extract additional dependency file names for moc from the contents of source files.

• A new AUTOUIC_SEARCH_PATHS target property was introduced to allow AUTOUIC to search for foo.ui in more places than the vicinity of the file including ui_foo.h.

• Global properties AUTOGEN_SOURCE_GROUP, AUTOMOC_SOURCE_GROUP and AUTORCC_SOURCE_GROUP were introduced to allow files generated by AUTOMOC or AUTORCC to be placed in a source_group().

• A BUILD_WITH_INSTALL_NAME_DIR target property and corresponding CMAKE_BUILD_WITH_INSTALL_NAME_DIR variable were added to control whether to use the INSTALL_NAME_DIR target property value for binaries in the build tree. This is for macOS install_name as BUILD_WITH_INSTALL_RPATH is for RPATH.

• A CUDA_PTX_COMPILATION target property was added to Object Libraries to support compiling to .ptx files instead of host object files.

• A GENERATOR_IS_MULTI_CONFIG global property was added to determine whether the current generator is a multi-configuration generator (such as Visual Studio Generators or Xcode).

• The INTERPROCEDURAL_OPTIMIZATION target property is now enforced when enabled. CMake will add IPO flags unconditionally or produce an error if it does not know the flags for the current compiler. The project is now responsible to use the CheckIPOSupported module to check for IPO support before enabling the target property. See policy CMP0069.

• The WINDOWS_EXPORT_ALL_SYMBOLS target property may now be used in combination with explicit .def files in order to export all symbols from the object files within a target plus an explicit list of symbols that the linker finds in dependencies (e.g. msvcrt.lib).

Modules

• A CheckIPOSupported module was added to help projects check whether interprocedural optimization (IPO) is supported by the current toolchain and CMake version.

• The CMakeFindDependencyMacro module find_dependency macro now forwards all arguments to the underlying find_package() call. Existing uses will continue to function as before, but callers can now access the full suite of arguments that find_package() accepts.

• The FeatureSummary module feature_summary() command now accepts the new DEFAULT_DESCRIPTION option that will print the default title for the selected package type.

• The FeatureSummary module gained a new FeatureSummary_<TYPE>_DESCRIPTION variable that can be defined for each <TYPE> to replace the type name with the specified string whenever the package type is used in an output string by the module.

• The FindDoxygen module learned to control Doxygen behavior using CMake variables and generate documentation via the newly added doxygen_add_docs() function. The Doxygen input file (Doxyfile) is automatically generated and doxygen is run as part of a custom target. Additional components can be specified to find optional tools: dot, mscgen and dia.

• The FindMPI module now provides imported targets.

• The FindProtobuf module protobuf_generate_cpp() command gained an EXPORT_MACRO option to specify the name of a DLL export markup macro.

• The FindProtobuf module now supports usage of static libraries for Unix via a new Protobuf_USE_STATIC_LIBS input variable.

• The FindProtobuf module now provides imported targets when the libraries are found.

• A new GoogleTest module was added to provide the gtest_add_tests() function independently of the FindGTest module. The function was also updated to support keyword arguments, with functionality expanded to allow a test name prefix and suffix to be specified, the dependency on the source files to be optional and the list of discovered test cases to be returned to the caller.

CTest

• The ctest_submit() command gained a HTTPHEADER option to specify custom headers to send during submission.

• The ctest(1) executable gained new options which allow the developer to disable automatically adding tests to the test set to satisfy fixture dependencies. -FS prevents adding setup tests for fixtures matching the provided regular expression, -FC prevents adding cleanup tests for matching fixtures and -FA prevents adding any test for matching fixtures.

• A DISABLED test property was added to mark tests that are configured but explicitly disabled so they do not run.

CPack

• The CPack Archive Generator learned to modify the filename per-component. See the CPACK_ARCHIVE_FILE_NAME variable and its per-component version CPACK_ARCHIVE_<component>_FILE_NAME.

• The CPackComponent module cpack_add_component() command gained a new PLIST <filename> option to specify the pkgbuild --component-plist argument when using the productbuild generator.

• The CPackIFW module cpack_ifw_configure_component() and cpack_ifw_configure_component_group() commands gained internationalization support for DISPLAY_NAME and DESCRIPTION options.

• The CPack IFW Generator learned the new hint CPACK_IFW_ROOT variable for finding the QtIFW tool suite installed in a non-standard place.

• The CPack productbuild Generator gained a new CPACK_PRODUCTBUILD_RESOURCES_DIR variable to specify resources to be copied into the Resources directory.

• The CPack RPM Generator learned to modify the debuginfo package name. See the CPACK_RPM_DEBUGINFO_FILE_NAME variable.

• The CPack WIX Generator patching system now has the ability to set additional attributes. This can be done by specifying attributes with the CPackWiXFragment XML tag after the Id attribute. See the CPACK_WIX_PATCH_FILE variable.

• The CPack WIX Generator implemented a new CPACK_WIX_ROOT_FOLDER_ID variable which allows using a custom root folder ID instead of the default ProgramFilesFolder / ProgramFiles64Folder.

Other

• Interprocedural optimization (IPO) is now supported for GNU and Clang compilers using link time optimization (LTO) flags. See the INTERPROCEDURAL_OPTIMIZATION target property and CheckIPOSupported module.

• The TARGET_OBJECTS generator expression is now supported by the add_custom_command() and file(GENERATE) commands.

• Two new informational generator expressions to retrieve Apple Bundle directories have been added. The first one $<TARGET_BUNDLE_DIR:tgt> outputs the full path to the Bundle directory, the other one $<TARGET_BUNDLE_CONTENT_DIR:tgt> outputs the full path to the Contents directory of macOS Bundles and App Bundles. For all other bundle types and SDKs it is identical with $<TARGET_BUNDLE_DIR:tgt>. The new expressions are helpful to query Bundle locations independent of the different Bundle types and layouts on macOS and iOS.

Deprecated and Removed Features

• An explicit deprecation diagnostic was added for policies CMP0036 and below. The cmake-policies(7) manual explains that the OLD behaviors of all policies are deprecated and that projects should always port to the NEW behaviors as soon as possible.

• The Visual Studio 8 2005 generator is now deprecated and will be removed in a future version of CMake.

• The Visual Studio 7 .NET 2003 generator has been removed.

• The Xcode generator dropped support for Xcode versions older than 3.

• The FindDoxygen module has deprecated several variables.

• The version of curl bundled with CMake no longer accepts URLs of the form file://c:/... on Windows due to a change in upstream curl 7.52. Use the form file:///c:/... instead to work on all versions.

Other Changes

• When using AUTOMOC, CMake now scans for the presence of the Q_PLUGIN_METADATA macro and reruns moc when the file from the macro's FILE argument changes.

• When AUTOMOC detects an include statement of the form #include "moc_<basename>.cpp" the search for the respective header file now looks in the INCLUDE_DIRECTORIES of the target as well.

• When running tests, CTest learned to treat skipped tests (using the SKIP_RETURN_CODE property) the same as tests with the new DISABLED property. Due to this change, CTest will not indicate failure when all tests are either skipped or pass.

• The Ninja generator has loosened the dependencies of object compilation. Object compilation now depends only on custom targets and custom commands associated with libraries on which the object's target depends and no longer depends on the libraries themselves. Source files in dependent targets may now compile without waiting for their targets' dependencies to link.

• On macOS, RPATH settings such as BUILD_WITH_INSTALL_RPATH no longer affect the install_name field. See policy CMP0068.

• The Visual Studio 14 2015 generator has been taught about a change to the v140 toolset made by a VS 2015 update. VS changed the set of values it understands for the GenerateDebugInformation linker setting that produces the -DEBUG linker flag variants.

Updates

Changes made since CMake 3.9.0 include the following.

3.9.1

• The find_ command PACKAGE_ROOT search path group added by CMake 3.9.0 has been removed for the 3.9 series due to regressions caused by new use of <PackageName>_ROOT variables. The behavior may be re-introduced in the future in a more-compatible way.

3.9.2

• On macOS, the default application bundle Info.plist file no longer enables Hi-DPI support as it did in 3.9.0 and 3.9.1. The change had to be reverted because it broke iOS applications.

• The Xcode generator no longer adds "outputPaths" to custom script build phases as it did in 3.9.0 and 3.9.1. This was added in an attempt to support Xcode 9's new build system, but broke incremental rebuilds for both the old and new Xcode build systems.