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-command
and similar command-line options.New manuals were added:
cmake-commands(7)
, replacingcmakecommands(1)
andcmakecompat(1)
cmake-modules(7)
, replacingcmakemodules(1)
cmake-policies(7)
, replacingcmakepolicies(1)
cmake-properties(7)
, replacingcmakeprops(1)
cmake-variables(7)
, replacingcmakevars(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 newINTERFACE
library type. Interface libraries have no build rules but may have properties definingusage requirements
and 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 newEXPORT
mode that retrieves the list of targets to export from an export set configured by theinstall(TARGETS)
commandEXPORT
option. 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 notinclude()
the generated targets file later during project configuration because it will not be available. Use Alias Targets instead. See policyCMP0024
.The
install(FILES)
command learned to supportgenerator expressions
in the list of files.The
project()
command learned to set some version variables to values specified by the newVERSION
option or to empty strings. See policyCMP0048
.The
string()
command learned a newCONCAT
mode. It is particularly useful in combination with the new Bracket Argument syntax.The
unset()
command learned aPARENT_SCOPE
option matching that of theset()
command.The
include_external_msproject()
command learned to handle non-C++ projects like.vbproj
or.csproj
.The
ctest_update()
command learned to update work trees managed by the Perforce (p4) version control tool.The
message()
command learned aDEPRECATION
mode. Such messages are not issued by default, but may be issued as a warning ifCMAKE_WARN_DEPRECATED
is enabled, or as an error ifCMAKE_ERROR_DEPRECATED
is enabled.The
target_link_libraries()
command now allows repeated use of theLINK_PUBLIC
andLINK_PRIVATE
keywords.
Variables¶
Variable
CMAKE_FIND_NO_INSTALL_PREFIX
has been introduced to tell CMake not to add the value ofCMAKE_INSTALL_PREFIX
to theCMAKE_SYSTEM_PREFIX_PATH
variable 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_PREFIX
was introduced for use when cross-compiling to specify an installation prefix on the host system that differs from aCMAKE_INSTALL_PREFIX
value meant for the target system.Variable
CMAKE_SYSROOT
was introduced to specify the toolchain SDK installation prefix, typically for cross-compiling. This is used to pass a--sysroot
option to the compiler and as a prefix searched byfind_*
commands.Variable
CMAKE_<LANG>_COMPILER_TARGET
was introduced for use when cross-compiling to specify the target platform in the toolchain file specified by theCMAKE_TOOLCHAIN_FILE
variable. 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 theMAP_IMPORTED_CONFIG_<CONFIG>
target property.
Properties¶
The
ADDITIONAL_MAKE_CLEAN_FILES
directory property learned to supportgenerator expressions
.A new directory property
CMAKE_CONFIGURE_DEPENDS
was 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 aconfigure_file()
command.A new AUTORCC feature replaces the need to invoke
qt4_add_resources()
by allowing.qrc
files 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 likeREQUIRED_FILES
andWORKING_DIRECTORY
.A new
SKIP_RETURN_CODE
test property was introduced to tellctest(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_MAX
andCOMPATIBLE_INTERFACE_NUMBER_MIN
for calculating numeric maximum and minimum values respectively.
Modules¶
The
CheckTypeSize
modulecheck_type_size
macro and theCheckStructHasMember
modulecheck_struct_has_member
macro learned a newLANGUAGE
option to optionally check C++ types.The
ExternalData
module learned to work with no URL templates if a local store is available.The
ExternalProject
functionExternalProject_Add
learned a newGIT_SUBMODULES
option to specify a subset of available submodules to checkout.A new
FindBacktrace
module has been added to supportfind_package(Backtrace)
calls.A new
FindLua
module has been added to supportfind_package(Lua)
calls.The
FindBoost
module learned a newBoost_NAMESPACE
option to change theboost
prefix on library names.The
FindBoost
module learned to control search for libraries with theg
tag (for MS debug runtime) with a newBoost_USE_DEBUG_RUNTIME
option. It isON
by default to preserve existing behavior.The
FindJava
andFindJNI
modules learned to use aJAVA_HOME
CMake variable or environment variable, and then try/usr/libexec/java_home
on OS X.The
UseJava
moduleadd_jar
function learned a newMANIFEST
option to pass the-m
option tojar
.A new
CMakeFindDependencyMacro
module was introduced with afind_dependency
macro to find transitive dependencies in apackage configuration file
. Such dependencies are omitted by the listing of theFeatureSummary
module.The
FindQt4
module learned to create Imported Targets for Qt executables. This helps disambiguate when using multipleQt versions
in the same buildsystem.The
FindRuby
module learned to search for Ruby 2.0 and 2.1.
Generator Expressions¶
New
$<PLATFORM_ID>
and$<PLATFORM_ID:...>
generator expressions
have been added.The
$<CONFIG>
generator expression
now has a variant which takes no argument. This is equivalent to the$<CONFIGURATION>
expression.New
$<UPPER_CASE:...>
and$<LOWER_CASE:...>
generator expressions
generator expressions have been added.A new
$<MAKE_C_IDENTIFIER:...>
generator expression
has been added.
Other¶
The
cmake(1)
-E
option learned a newsleep
command.The
ccmake(1)
dialog learned to honor theSTRINGS
cache 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 theAdd Entry
dialog.
New Diagnostics¶
Directories named in the
INTERFACE_INCLUDE_DIRECTORIES
target property of imported targets linked conditionally by agenerator expression
were not checked for existence. Now they are checked. See policyCMP0027
.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 byadd_custom_target()
but now diagnoses this mistake. See policyCMP0039
.The
add_custom_command()
command used to silently ignore calls specifying theTARGET
option with a non-existent target but now diagnoses this mistake. See policyCMP0040
.Relative paths in the
INTERFACE_INCLUDE_DIRECTORIES
target property used to be silently accepted if they contained agenerator expression
but are now rejected. See policyCMP0041
.The
get_target_property()
command learned to reject calls specifying a non-existent target. See policyCMP0045
.The
add_dependencies()
command learned to reject calls specifying a dependency on a non-existent target. See policyCMP0046
.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 policyCMP0028
.When the
project()
orenable_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 correspondingCMAKE_<LANG>_COMPILER
variable. 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()
oradd_executable()
command learned to reject items which require an undocumented extra layer of variable expansion. See policyCMP0049
.Use of
add_custom_command()
undocumentedSOURCE
signatures now results in an error. See policyCMP0050
.
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
CMP0029
disallowssubdir_depends()
Policy
CMP0030
disallowsuse_mangled_mesa()
Policy
CMP0031
disallowsload_command()
Policy
CMP0032
disallowsoutput_required_files()
Policy
CMP0033
disallowsexport_library_dependencies()
Policy
CMP0034
disallowsutility_source()
Policy
CMP0035
disallowsvariable_requires()
Policy
CMP0036
disallowsbuild_name()
The
cmake(1)
-i
wizard mode has been removed. Instead use an interactive dialog such asccmake(1)
or use the-D
option to set cache values from the command line.The builtin documentation formatters that supported command-line options such as
--help-man
and--help-html
have 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. Thecmake(1)
--help-custom-modules
option now produces a warning at runtime and generates a minimal document that reports the limitation.The
COMPILE_DEFINITIONS_<CONFIG>
directory properties and theCOMPILE_DEFINITIONS_<CONFIG>
target properties have been deprecated. Instead set the correspondingCOMPILE_DEFINITIONS
directory property orCOMPILE_DEFINITIONS
target property and usegenerator expressions
like$<CONFIG:...>
to specify per-configuration definitions. See policyCMP0043
.The
LOCATION
target 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 policyCMP0026
.The
COMPILE_FLAGS
target property is now documented as deprecated, though no warning is issued. Use theCOMPILE_OPTIONS
target property or thetarget_compile_options()
command instead.The
GenerateExportHeader
moduleadd_compiler_export_flags
function is now deprecated. It has been superseded by the<LANG>_VISIBILITY_PRESET
andVISIBILITY_INLINES_HIDDEN
target 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_VERSION
variable 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_ID
value for Apple-provided Clang is nowAppleClang
. It must be distinct from upstream Clang because the version numbers differ. See policyCMP0025
.The
CMAKE_<LANG>_COMPILER_ID
value forqcc
on QNX is nowQCC
. It must be distinct fromGNU
because the command-line options differ. See policyCMP0047
.On 64-bit OS X the
CMAKE_HOST_SYSTEM_PROCESSOR
value is now correctly detected asx86_64
instead ofi386
.On OS X, CMake learned to enable behavior specified by the
MACOSX_RPATH
target property by default. This activates use of@rpath
for runtime shared library searches. See policyCMP0042
.The
build_command()
command now returns acmake(1)
--build
command line instead of a direct invocation of the native build tool. When usingVisual Studio
generators, CMake and CTest no longer requireCMAKE_MAKE_PROGRAM
to 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)
--build
command now shares its own stdout and stderr pipes with the native build tool by default. The--use-stderr
option that once activated this is now ignored.The
$<C_COMPILER_ID:...>
and$<CXX_COMPILER_ID:...>
generator expressions
used to perform case-insensitive comparison but have now been corrected to perform case-sensitive comparison. See policyCMP0044
.The builtin
edit_cache
target will no longer selectccmake(1)
by default when no interactive terminal will be available (e.g. withNinja
or an IDE generator). Insteadcmake-gui(1)
will be preferred if available.The
ExternalProject
download step learned to re-attempt download in certain cases to be more robust to temporary network failure.The
FeatureSummary
no longer lists transitive dependencies since they were not directly requested by the current project.The
cmake-mode.el
major Emacs editing mode has been cleaned up and enhanced in several ways.Include directories specified in the
INTERFACE_INCLUDE_DIRECTORIES
of Imported Targets are treated asSYSTEM
includes by default when handled as usage requirements.