CMake 3.0 Release Notes¶
Changes made since CMake 2.8.12 include the following.
Documentation Changes¶
- The CMake documentation has been converted to reStructuredText and now transforms via Sphinx (https://www.sphinx-doc.org) into man and html pages. This allows the documentation to be properly indexed and to contain cross-references. - Conversion from the old internal documentation format was done by an automatic process so some documents may still contain artifacts. They will be updated incrementally over time. - A basic reStructuredText processor has been implemented to support - cmake --help-commandand similar command-line options.
- New manuals were added: 
- cmake-commands(7), replacing- cmakecommands(1)and- cmakecompat(1)
- cmake-modules(7), replacing- cmakemodules(1)
- cmake-policies(7), replacing- cmakepolicies(1)
- cmake-properties(7), replacing- cmakeprops(1)
- cmake-variables(7), replacing- cmakevars(1)
 
- Release notes for CMake 3.0.0 and above will now be included with the html documentation. 
New Features¶
Syntax¶
- The CMake language has been extended with Bracket Argument and Bracket Comment syntax inspired by Lua long brackets: - set(x [===[bracket argument]===] #[[bracket comment]]) - Content between equal-length open- and close-brackets is taken literally with no variable replacements. - Warning - This syntax change could not be made in a fully compatible way. No policy is possible because syntax parsing occurs before any chance to set a policy. Existing code using an unquoted argument that starts with an open bracket will be interpreted differently without any diagnostic. Fortunately the syntax is obscure enough that this problem is unlikely in practice. 
Generators¶
Commands¶
- The - add_library()command learned a new- INTERFACElibrary type. Interface libraries have no build rules but may have properties defining- usage requirementsand may be installed, exported, and imported. This is useful to create header-only libraries that have concrete link dependencies on other libraries.
- The - export()command learned a new- EXPORTmode that retrieves the list of targets to export from an export set configured by the- install(TARGETS)command- EXPORToption. This makes it easy to export from the build tree the same targets that are exported from the install tree.
- The - export()command learned to work with multiple dependent export sets, thus allowing multiple packages to be built and exported from a single tree. The feature requires CMake to wait until the generation step to write the output file. This means one should not- include()the generated targets file later during project configuration because it will not be available. Use Alias Targets instead. See policy- CMP0024.
- The - install(FILES)command learned to support- generator expressionsin the list of files.
- The - project()command learned to set some version variables to values specified by the new- VERSIONoption or to empty strings. See policy- CMP0048.
- The - string()command learned a new- CONCATmode. It is particularly useful in combination with the new Bracket Argument syntax.
- The - unset()command learned a- PARENT_SCOPEoption matching that of the- set()command.
- The - include_external_msproject()command learned to handle non-C++ projects like- .vbprojor- .csproj.
- The - ctest_update()command learned to update work trees managed by the Perforce (p4) version control tool.
- The - message()command learned a- DEPRECATIONmode. Such messages are not issued by default, but may be issued as a warning if- CMAKE_WARN_DEPRECATEDis enabled, or as an error if- CMAKE_ERROR_DEPRECATEDis enabled.
- The - target_link_libraries()command now allows repeated use of the- LINK_PUBLICand- LINK_PRIVATEkeywords.
Variables¶
- Variable - CMAKE_FIND_NO_INSTALL_PREFIXhas been introduced to tell CMake not to add the value of- CMAKE_INSTALL_PREFIXto the- CMAKE_SYSTEM_PREFIX_PATHvariable by default. This is useful when building a project that installs some of its own dependencies to avoid finding files it is about to replace.
- Variable - CMAKE_STAGING_PREFIXwas introduced for use when cross-compiling to specify an installation prefix on the host system that differs from a- CMAKE_INSTALL_PREFIXvalue meant for the target system.
- Variable - CMAKE_SYSROOTwas introduced to specify the toolchain SDK installation prefix, typically for cross-compiling. This is used to pass a- --sysrootoption to the compiler and as a prefix searched by- find_*commands.
- Variable - CMAKE_<LANG>_COMPILER_TARGETwas introduced for use when cross-compiling to specify the target platform in the toolchain file specified by the- CMAKE_TOOLCHAIN_FILEvariable. This is used to pass an option such as- --target=<triple>to some cross-compiling compiler drivers.
- Variable - CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>has been introduced to optionally initialize the- MAP_IMPORTED_CONFIG_<CONFIG>target property.
Properties¶
- The - ADDITIONAL_MAKE_CLEAN_FILESdirectory property learned to support- generator expressions.
- A new directory property - CMAKE_CONFIGURE_DEPENDSwas introduced to allow projects to specify additional files on which the configuration process depends. CMake will re-run at build time when one of these files is modified. Previously this was only possible to achieve by specifying such files as the input to a- configure_file()command.
- A new AUTORCC feature replaces the need to invoke - qt4_add_resources()by allowing- .qrcfiles to be listed as target sources.
- A new AUTOUIC feature replaces the need to invoke - qt4_wrap_ui().
- Test properties learned to support - generator expressions. This is useful to specify per-configuration values for test properties like- REQUIRED_FILESand- WORKING_DIRECTORY.
- A new - SKIP_RETURN_CODEtest property was introduced to tell- ctest(1)to treat a particular test return code as if the test were not run. This is useful for test drivers to report that certain test requirements were not available.
- New types of Compatible Interface Properties were introduced, namely the - COMPATIBLE_INTERFACE_NUMBER_MAXand- COMPATIBLE_INTERFACE_NUMBER_MINfor calculating numeric maximum and minimum values respectively.
Modules¶
- The - CheckTypeSizemodule- check_type_sizemacro and the- CheckStructHasMembermodule- check_struct_has_membermacro learned a new- LANGUAGEoption to optionally check C++ types.
- The - ExternalDatamodule learned to work with no URL templates if a local store is available.
- The - ExternalProjectfunction- ExternalProject_Addlearned a new- GIT_SUBMODULESoption to specify a subset of available submodules to checkout.
- A new - FindBacktracemodule has been added to support- find_package(Backtrace)calls.
- A new - FindLuamodule has been added to support- find_package(Lua)calls.
- The - FindBoostmodule learned a new- Boost_NAMESPACEoption to change the- boostprefix on library names.
- The - FindBoostmodule learned to control search for libraries with the- gtag (for MS debug runtime) with a new- Boost_USE_DEBUG_RUNTIMEoption. It is- ONby default to preserve existing behavior.
- The - FindJavaand- FindJNImodules learned to use a- JAVA_HOMECMake variable or environment variable, and then try- /usr/libexec/java_homeon OS X.
- The - UseJavamodule- add_jarfunction learned a new- MANIFESToption to pass the- -moption to- jar.
- A new - CMakeFindDependencyMacromodule was introduced with a- find_dependencymacro to find transitive dependencies in a- package configuration file. Such dependencies are omitted by the listing of the- FeatureSummarymodule.
- The - FindQt4module learned to create Imported Targets for Qt executables. This helps disambiguate when using multiple- Qt versionsin the same buildsystem.
- The - FindRubymodule learned to search for Ruby 2.0 and 2.1.
Generator Expressions¶
- New - $<PLATFORM_ID>and- $<PLATFORM_ID:...>- generator expressionshave been added.
- The - $<CONFIG>- generator expressionnow has a variant which takes no argument. This is equivalent to the- $<CONFIGURATION>expression.
- New - $<UPPER_CASE:...>and- $<LOWER_CASE:...>- generator expressionsgenerator expressions have been added.
- A new - $<MAKE_C_IDENTIFIER:...>- generator expressionhas been added.
Other¶
- The - cmake(1)- -Eoption learned a new- sleepcommand.
- The - ccmake(1)dialog learned to honor the- STRINGScache entry property to cycle through the enumerated list of possible values.
- The - cmake-gui(1)dialog learned to remember window settings between sessions.
- The - cmake-gui(1)dialog learned to remember the type of a cache entry for completion in the- Add Entrydialog.
New Diagnostics¶
- Directories named in the - INTERFACE_INCLUDE_DIRECTORIEStarget property of imported targets linked conditionally by a- generator expressionwere not checked for existence. Now they are checked. See policy- CMP0027.
- Build target names must now match a validity pattern and may no longer conflict with CMake-defined targets. See policy - CMP0037.
- Build targets that specify themselves as a link dependency were silently accepted but are now diagnosed. See - CMP0038.
- The - target_link_libraries()command used to silently ignore calls specifying as their first argument build targets created by- add_custom_target()but now diagnoses this mistake. See policy- CMP0039.
- The - add_custom_command()command used to silently ignore calls specifying the- TARGEToption with a non-existent target but now diagnoses this mistake. See policy- CMP0040.
- Relative paths in the - INTERFACE_INCLUDE_DIRECTORIEStarget property used to be silently accepted if they contained a- generator expressionbut are now rejected. See policy- CMP0041.
- The - get_target_property()command learned to reject calls specifying a non-existent target. See policy- CMP0045.
- The - add_dependencies()command learned to reject calls specifying a dependency on a non-existent target. See policy- CMP0046.
- Link dependency analysis learned to assume names containing - ::refer to Alias Targets or Imported Targets. It will now produce an error if such a linked target is missing. Previously in this case CMake generated a link line that failed at build time. See policy- CMP0028.
- When the - project()or- enable_language()commands initialize support for a language, it is now an error if the full path to the compiler cannot be found and stored in the corresponding- CMAKE_<LANG>_COMPILERvariable. This produces nicer error messages up front and stops processing when no working compiler is known to be available.
- Target sources specified with the - add_library()or- add_executable()command learned to reject items which require an undocumented extra layer of variable expansion. See policy- CMP0049.
- Use of - add_custom_command()undocumented- SOURCEsignatures now results in an error. See policy- CMP0050.
Deprecated and Removed Features¶
- Compatibility options supporting code written for CMake versions prior to 2.4 have been removed. 
- Several long-outdated commands that should no longer be called have been disallowed in new code by policies: - Policy - CMP0029disallows- subdir_depends()
- Policy - CMP0030disallows- use_mangled_mesa()
- Policy - CMP0031disallows- load_command()
- Policy - CMP0032disallows- output_required_files()
- Policy - CMP0033disallows- export_library_dependencies()
- Policy - CMP0034disallows- utility_source()
- Policy - CMP0035disallows- variable_requires()
- Policy - CMP0036disallows- build_name()
 
- The - cmake(1)- -iwizard mode has been removed. Instead use an interactive dialog such as- ccmake(1)or use the- -Doption to set cache values from the command line.
- The builtin documentation formatters that supported command-line options such as - --help-manand- --help-htmlhave been removed in favor of the above-mentioned new documentation system. These and other command-line options that used to generate man- and html- formatted pages no longer work. The- cmake(1)- --help-custom-modulesoption now produces a warning at runtime and generates a minimal document that reports the limitation.
- The - COMPILE_DEFINITIONS_<CONFIG>directory properties and the- COMPILE_DEFINITIONS_<CONFIG>target properties have been deprecated. Instead set the corresponding- COMPILE_DEFINITIONSdirectory property or- COMPILE_DEFINITIONStarget property and use- generator expressionslike- $<CONFIG:...>to specify per-configuration definitions. See policy- CMP0043.
- The - LOCATIONtarget property should no longer be read from non-IMPORTED targets. It does not make sense in multi-configuration generators since the build configuration is not known while configuring the project. It has been superseded by the- $<TARGET_FILE>generator expression. See policy- CMP0026.
- The - COMPILE_FLAGStarget property is now documented as deprecated, though no warning is issued. Use the- COMPILE_OPTIONStarget property or the- target_compile_options()command instead.
- The - GenerateExportHeadermodule- add_compiler_export_flagsfunction is now deprecated. It has been superseded by the- <LANG>_VISIBILITY_PRESETand- VISIBILITY_INLINES_HIDDENtarget properties.
Other Changes¶
- The version scheme was changed to use only two components for the feature level instead of three. The third component will now be used for bug-fix releases or the date of development versions. See the - CMAKE_VERSIONvariable documentation for details.
- The default install locations of CMake itself on Windows and OS X no longer contain the CMake version number. This allows for easy replacement without re-generating local build trees manually. 
- Generators for Visual Studio 10 (2010) and later were renamed to include the product year like generators for older VS versions: - Visual Studio 10->- Visual Studio 10 2010
- Visual Studio 11->- Visual Studio 11 2012
- Visual Studio 12->- Visual Studio 12 2013
 - This clarifies which generator goes with each Visual Studio version. The old names are recognized for compatibility. 
- The - CMAKE_<LANG>_COMPILER_IDvalue for Apple-provided Clang is now- AppleClang. It must be distinct from upstream Clang because the version numbers differ. See policy- CMP0025.
- The - CMAKE_<LANG>_COMPILER_IDvalue for- qccon QNX is now- QCC. It must be distinct from- GNUbecause the command-line options differ. See policy- CMP0047.
- On 64-bit OS X the - CMAKE_HOST_SYSTEM_PROCESSORvalue is now correctly detected as- x86_64instead of- i386.
- On OS X, CMake learned to enable behavior specified by the - MACOSX_RPATHtarget property by default. This activates use of- @rpathfor runtime shared library searches. See policy- CMP0042.
- The - build_command()command now returns a- cmake(1)- --buildcommand line instead of a direct invocation of the native build tool. When using- Visual Studiogenerators, CMake and CTest no longer require- CMAKE_MAKE_PROGRAMto be located up front. Selection of the proper msbuild or devenv tool is now performed as late as possible when the solution (- .sln) file is available so it can depend on project content.
- The - cmake(1)- --buildcommand now shares its own stdout and stderr pipes with the native build tool by default. The- --use-stderroption that once activated this is now ignored.
- The - $<C_COMPILER_ID:...>and- $<CXX_COMPILER_ID:...>- generator expressionsused to perform case-insensitive comparison but have now been corrected to perform case-sensitive comparison. See policy- CMP0044.
- The builtin - edit_cachetarget will no longer select- ccmake(1)by default when no interactive terminal will be available (e.g. with- Ninjaor an IDE generator). Instead- cmake-gui(1)will be preferred if available.
- The - ExternalProjectdownload step learned to re-attempt download in certain cases to be more robust to temporary network failure.
- The - FeatureSummaryno longer lists transitive dependencies since they were not directly requested by the current project.
- The - cmake-mode.elmajor Emacs editing mode has been cleaned up and enhanced in several ways.
- Include directories specified in the - INTERFACE_INCLUDE_DIRECTORIESof Imported Targets are treated as- SYSTEMincludes by default when handled as usage requirements.
