1CMake 3.0 Release Notes 2*********************** 3 4.. only:: html 5 6 .. contents:: 7 8Changes made since CMake 2.8.12 include the following. 9 10Documentation Changes 11===================== 12 13* The CMake documentation has been converted to reStructuredText and 14 now transforms via Sphinx (`<http://sphinx-doc.org>`__) into man and 15 html pages. This allows the documentation to be properly indexed 16 and to contain cross-references. 17 18 Conversion from the old internal documentation format was done by 19 an automatic process so some documents may still contain artifacts. 20 They will be updated incrementally over time. 21 22 A basic reStructuredText processor has been implemented to support 23 ``cmake --help-command`` and similar command-line options. 24 25* New manuals were added: 26 27 - :manual:`cmake-buildsystem(7)` 28 - :manual:`cmake-commands(7)`, replacing ``cmakecommands(1)`` 29 and ``cmakecompat(1)`` 30 - :manual:`cmake-developer(7)` 31 - :manual:`cmake-generator-expressions(7)` 32 - :manual:`cmake-generators(7)` 33 - :manual:`cmake-language(7)` 34 - :manual:`cmake-modules(7)`, replacing ``cmakemodules(1)`` 35 - :manual:`cmake-packages(7)` 36 - :manual:`cmake-policies(7)`, replacing ``cmakepolicies(1)`` 37 - :manual:`cmake-properties(7)`, replacing ``cmakeprops(1)`` 38 - :manual:`cmake-qt(7)` 39 - :manual:`cmake-toolchains(7)` 40 - :manual:`cmake-variables(7)`, replacing ``cmakevars(1)`` 41 42* Release notes for CMake 3.0.0 and above will now be included with 43 the html documentation. 44 45New Features 46============ 47 48Syntax 49------ 50 51* The CMake language has been extended with 52 :ref:`Bracket Argument` and :ref:`Bracket Comment` 53 syntax inspired by Lua long brackets:: 54 55 set(x [===[bracket argument]===] #[[bracket comment]]) 56 57 Content between equal-length open- and close-brackets is taken 58 literally with no variable replacements. 59 60 .. warning:: 61 This syntax change could not be made in a fully compatible 62 way. No policy is possible because syntax parsing occurs before 63 any chance to set a policy. Existing code using an unquoted 64 argument that starts with an open bracket will be interpreted 65 differently without any diagnostic. Fortunately the syntax is 66 obscure enough that this problem is unlikely in practice. 67 68Generators 69---------- 70 71* A new :generator:`CodeLite` extra generator is available 72 for use with the Makefile or Ninja generators. 73 74* A new :generator:`Kate` extra generator is available 75 for use with the Makefile or Ninja generators. 76 77* The :generator:`Ninja` generator learned to use ``ninja`` job pools 78 when specified by a new :prop_gbl:`JOB_POOLS` global property. 79 80Commands 81-------- 82 83* The :command:`add_library` command learned a new ``INTERFACE`` 84 library type. Interface libraries have no build rules but may 85 have properties defining 86 :manual:`usage requirements <cmake-buildsystem(7)>` 87 and may be installed, exported, and imported. This is useful to 88 create header-only libraries that have concrete link dependencies 89 on other libraries. 90 91* The :command:`export()` command learned a new ``EXPORT`` mode that 92 retrieves the list of targets to export from an export set configured 93 by the :command:`install(TARGETS)` command ``EXPORT`` option. This 94 makes it easy to export from the build tree the same targets that 95 are exported from the install tree. 96 97* The :command:`export` command learned to work with multiple dependent 98 export sets, thus allowing multiple packages to be built and exported 99 from a single tree. The feature requires CMake to wait until the 100 generation step to write the output file. This means one should not 101 :command:`include` the generated targets file later during project 102 configuration because it will not be available. 103 Use :ref:`Alias Targets` instead. See policy :policy:`CMP0024`. 104 105* The :command:`install(FILES)` command learned to support 106 :manual:`generator expressions <cmake-generator-expressions(7)>` 107 in the list of files. 108 109* The :command:`project` command learned to set some version variables 110 to values specified by the new ``VERSION`` option or to empty strings. 111 See policy :policy:`CMP0048`. 112 113* The :command:`string` command learned a new ``CONCAT`` mode. 114 It is particularly useful in combination with the new 115 :ref:`Bracket Argument` syntax. 116 117* The :command:`unset` command learned a ``PARENT_SCOPE`` option 118 matching that of the :command:`set` command. 119 120* The :command:`include_external_msproject` command learned 121 to handle non-C++ projects like ``.vbproj`` or ``.csproj``. 122 123* The :command:`ctest_update` command learned to update work trees 124 managed by the Perforce (p4) version control tool. 125 126* The :command:`message` command learned a ``DEPRECATION`` mode. Such 127 messages are not issued by default, but may be issued as a warning if 128 :variable:`CMAKE_WARN_DEPRECATED` is enabled, or as an error if 129 :variable:`CMAKE_ERROR_DEPRECATED` is enabled. 130 131* The :command:`target_link_libraries` command now allows repeated use of 132 the ``LINK_PUBLIC`` and ``LINK_PRIVATE`` keywords. 133 134Variables 135--------- 136 137* Variable :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` has been 138 introduced to tell CMake not to add the value of 139 :variable:`CMAKE_INSTALL_PREFIX` to the 140 :variable:`CMAKE_SYSTEM_PREFIX_PATH` variable by default. 141 This is useful when building a project that installs some 142 of its own dependencies to avoid finding files it is about 143 to replace. 144 145* Variable :variable:`CMAKE_STAGING_PREFIX` was introduced for use 146 when cross-compiling to specify an installation prefix on the 147 host system that differs from a :variable:`CMAKE_INSTALL_PREFIX` 148 value meant for the target system. 149 150* Variable :variable:`CMAKE_SYSROOT` was introduced to specify the 151 toolchain SDK installation prefix, typically for cross-compiling. 152 This is used to pass a ``--sysroot`` option to the compiler and 153 as a prefix searched by ``find_*`` commands. 154 155* Variable :variable:`CMAKE_<LANG>_COMPILER_TARGET` was introduced 156 for use when cross-compiling to specify the target platform in the 157 :ref:`toolchain file <Cross Compiling Toolchain>` specified by the 158 :variable:`CMAKE_TOOLCHAIN_FILE` variable. 159 This is used to pass an option such as ``--target=<triple>`` to some 160 cross-compiling compiler drivers. 161 162* Variable :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` has been 163 introduced to optionally initialize the 164 :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property. 165 166Properties 167---------- 168 169* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property 170 learned to support 171 :manual:`generator expressions <cmake-generator-expressions(7)>`. 172 173* A new directory property :prop_dir:`CMAKE_CONFIGURE_DEPENDS` 174 was introduced to allow projects to specify additional 175 files on which the configuration process depends. CMake will 176 re-run at build time when one of these files is modified. 177 Previously this was only possible to achieve by specifying 178 such files as the input to a :command:`configure_file` command. 179 180* A new :ref:`Qt AUTORCC` feature replaces the need to 181 invoke ``qt4_add_resources()`` by allowing ``.qrc`` files to 182 be listed as target sources. 183 184* A new :ref:`Qt AUTOUIC` feature replaces the need to 185 invoke ``qt4_wrap_ui()``. 186 187* Test properties learned to support 188 :manual:`generator expressions <cmake-generator-expressions(7)>`. 189 This is useful to specify per-configuration values for test 190 properties like :prop_test:`REQUIRED_FILES` and 191 :prop_test:`WORKING_DIRECTORY`. 192 193* A new :prop_test:`SKIP_RETURN_CODE` test property was introduced 194 to tell :manual:`ctest(1)` to treat a particular test return code as 195 if the test were not run. This is useful for test drivers to report 196 that certain test requirements were not available. 197 198* New types of :ref:`Compatible Interface Properties` were introduced, 199 namely the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and 200 :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` for calculating numeric 201 maximum and minimum values respectively. 202 203Modules 204------- 205 206* The :module:`CheckTypeSize` module ``check_type_size`` macro and 207 the :module:`CheckStructHasMember` module ``check_struct_has_member`` 208 macro learned a new ``LANGUAGE`` option to optionally check C++ types. 209 210* The :module:`ExternalData` module learned to work with no 211 URL templates if a local store is available. 212 213* The :module:`ExternalProject` function ``ExternalProject_Add`` 214 learned a new ``GIT_SUBMODULES`` option to specify a subset 215 of available submodules to checkout. 216 217* A new :module:`FindBacktrace` module has been added to support 218 :command:`find_package(Backtrace)` calls. 219 220* A new :module:`FindLua` module has been added to support 221 :command:`find_package(Lua)` calls. 222 223* The :module:`FindBoost` module learned a new ``Boost_NAMESPACE`` 224 option to change the ``boost`` prefix on library names. 225 226* The :module:`FindBoost` module learned to control search 227 for libraries with the ``g`` tag (for MS debug runtime) with 228 a new ``Boost_USE_DEBUG_RUNTIME`` option. It is ``ON`` by 229 default to preserve existing behavior. 230 231* The :module:`FindJava` and :module:`FindJNI` modules learned 232 to use a ``JAVA_HOME`` CMake variable or environment variable, 233 and then try ``/usr/libexec/java_home`` on OS X. 234 235* The :module:`UseJava` module ``add_jar`` function learned a new 236 ``MANIFEST`` option to pass the ``-m`` option to ``jar``. 237 238* A new :module:`CMakeFindDependencyMacro` module was introduced with 239 a ``find_dependency`` macro to find transitive dependencies in 240 a :manual:`package configuration file <cmake-packages(7)>`. Such 241 dependencies are omitted by the listing of the :module:`FeatureSummary` 242 module. 243 244* The :module:`FindQt4` module learned to create :ref:`Imported Targets` 245 for Qt executables. This helps disambiguate when using multiple 246 :manual:`Qt versions <cmake-qt(7)>` in the same buildsystem. 247 248* The :module:`FindRuby` module learned to search for Ruby 2.0 and 2.1. 249 250Generator Expressions 251--------------------- 252 253* New ``$<PLATFORM_ID>`` and ``$<PLATFORM_ID:...>`` 254 :manual:`generator expressions <cmake-generator-expressions(7)>` 255 have been added. 256 257* The ``$<CONFIG>`` 258 :manual:`generator expression <cmake-generator-expressions(7)>` now has 259 a variant which takes no argument. This is equivalent to the 260 ``$<CONFIGURATION>`` expression. 261 262* New ``$<UPPER_CASE:...>`` and ``$<LOWER_CASE:...>`` 263 :manual:`generator expressions <cmake-generator-expressions(7)>` 264 generator expressions have been added. 265 266* A new ``$<MAKE_C_IDENTIFIER:...>`` 267 :manual:`generator expression <cmake-generator-expressions(7)>` has 268 been added. 269 270Other 271----- 272 273* The :manual:`cmake(1)` ``-E`` option learned a new ``sleep`` command. 274 275* The :manual:`ccmake(1)` dialog learned to honor the 276 :prop_cache:`STRINGS` cache entry property to cycle through 277 the enumerated list of possible values. 278 279* The :manual:`cmake-gui(1)` dialog learned to remember window 280 settings between sessions. 281 282* The :manual:`cmake-gui(1)` dialog learned to remember the type 283 of a cache entry for completion in the ``Add Entry`` dialog. 284 285New Diagnostics 286=============== 287 288* Directories named in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` 289 target property of imported targets linked conditionally by a 290 :manual:`generator expression <cmake-generator-expressions(7)>` 291 were not checked for existence. Now they are checked. 292 See policy :policy:`CMP0027`. 293 294* Build target names must now match a validity pattern and may no longer 295 conflict with CMake-defined targets. See policy :policy:`CMP0037`. 296 297* Build targets that specify themselves as a link dependency were 298 silently accepted but are now diagnosed. See :policy:`CMP0038`. 299 300* The :command:`target_link_libraries` command used to silently ignore 301 calls specifying as their first argument build targets created by 302 :command:`add_custom_target` but now diagnoses this mistake. 303 See policy :policy:`CMP0039`. 304 305* The :command:`add_custom_command` command used to silently ignore 306 calls specifying the ``TARGET`` option with a non-existent target 307 but now diagnoses this mistake. See policy :policy:`CMP0040`. 308 309* Relative paths in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` 310 target property used to be silently accepted if they contained a 311 :manual:`generator expression <cmake-generator-expressions(7)>` 312 but are now rejected. See policy :policy:`CMP0041`. 313 314* The :command:`get_target_property` command learned to reject calls 315 specifying a non-existent target. See policy :policy:`CMP0045`. 316 317* The :command:`add_dependencies` command learned to reject calls 318 specifying a dependency on a non-existent target. 319 See policy :policy:`CMP0046`. 320 321* Link dependency analysis learned to assume names containing ``::`` 322 refer to :ref:`Alias Targets` or :ref:`Imported Targets`. It will 323 now produce an error if such a linked target is missing. Previously 324 in this case CMake generated a link line that failed at build time. 325 See policy :policy:`CMP0028`. 326 327* When the :command:`project` or :command:`enable_language` commands 328 initialize support for a language, it is now an error if the full 329 path to the compiler cannot be found and stored in the corresponding 330 :variable:`CMAKE_<LANG>_COMPILER` variable. This produces nicer error 331 messages up front and stops processing when no working compiler 332 is known to be available. 333 334* Target sources specified with the :command:`add_library` or 335 :command:`add_executable` command learned to reject items which 336 require an undocumented extra layer of variable expansion. 337 See policy :policy:`CMP0049`. 338 339* Use of :command:`add_custom_command` undocumented ``SOURCE`` 340 signatures now results in an error. See policy :policy:`CMP0050`. 341 342Deprecated and Removed Features 343=============================== 344 345* Compatibility options supporting code written for CMake versions 346 prior to 2.4 have been removed. 347 348* Several long-outdated commands that should no longer be called 349 have been disallowed in new code by policies: 350 351 - Policy :policy:`CMP0029` disallows :command:`subdir_depends` 352 - Policy :policy:`CMP0030` disallows :command:`use_mangled_mesa` 353 - Policy :policy:`CMP0031` disallows :command:`load_command` 354 - Policy :policy:`CMP0032` disallows :command:`output_required_files` 355 - Policy :policy:`CMP0033` disallows :command:`export_library_dependencies` 356 - Policy :policy:`CMP0034` disallows :command:`utility_source` 357 - Policy :policy:`CMP0035` disallows :command:`variable_requires` 358 - Policy :policy:`CMP0036` disallows :command:`build_name` 359 360* The :manual:`cmake(1)` ``-i`` wizard mode has been removed. 361 Instead use an interactive dialog such as :manual:`ccmake(1)` 362 or use the ``-D`` option to set cache values from the command line. 363 364* The builtin documentation formatters that supported command-line 365 options such as ``--help-man`` and ``--help-html`` have been removed 366 in favor of the above-mentioned new documentation system. These and 367 other command-line options that used to generate man- and html- 368 formatted pages no longer work. The :manual:`cmake(1)` 369 ``--help-custom-modules`` option now produces a warning at runtime 370 and generates a minimal document that reports the limitation. 371 372* The :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` directory properties and the 373 :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target properties have been 374 deprecated. Instead set the corresponding :prop_dir:`COMPILE_DEFINITIONS` 375 directory property or :prop_tgt:`COMPILE_DEFINITIONS` target property and 376 use :manual:`generator expressions <cmake-generator-expressions(7)>` like 377 ``$<CONFIG:...>`` to specify per-configuration definitions. 378 See policy :policy:`CMP0043`. 379 380* The :prop_tgt:`LOCATION` target property should no longer be read from 381 non-IMPORTED targets. It does not make sense in multi-configuration 382 generators since the build configuration is not known while configuring 383 the project. It has been superseded by the ``$<TARGET_FILE>`` generator 384 expression. See policy :policy:`CMP0026`. 385 386* The :prop_tgt:`COMPILE_FLAGS` target property is now documented 387 as deprecated, though no warning is issued. Use the 388 :prop_tgt:`COMPILE_OPTIONS` target property or the 389 :command:`target_compile_options` command instead. 390 391* The :module:`GenerateExportHeader` module ``add_compiler_export_flags`` 392 function is now deprecated. It has been superseded by the 393 :prop_tgt:`<LANG>_VISIBILITY_PRESET` and 394 :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties. 395 396Other Changes 397============= 398 399* The version scheme was changed to use only two components for 400 the feature level instead of three. The third component will 401 now be used for bug-fix releases or the date of development versions. 402 See the :variable:`CMAKE_VERSION` variable documentation for details. 403 404* The default install locations of CMake itself on Windows and 405 OS X no longer contain the CMake version number. This allows 406 for easy replacement without re-generating local build trees 407 manually. 408 409* Generators for Visual Studio 10 (2010) and later were renamed to 410 include the product year like generators for older VS versions: 411 412 - ``Visual Studio 10`` -> :generator:`Visual Studio 10 2010` 413 - ``Visual Studio 11`` -> :generator:`Visual Studio 11 2012` 414 - ``Visual Studio 12`` -> :generator:`Visual Studio 12 2013` 415 416 This clarifies which generator goes with each Visual Studio 417 version. The old names are recognized for compatibility. 418 419* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for Apple-provided 420 Clang is now ``AppleClang``. It must be distinct from upstream 421 Clang because the version numbers differ. 422 See policy :policy:`CMP0025`. 423 424* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for ``qcc`` on QNX 425 is now ``QCC``. It must be distinct from ``GNU`` because the 426 command-line options differ. See policy :policy:`CMP0047`. 427 428* On 64-bit OS X the :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` value 429 is now correctly detected as ``x86_64`` instead of ``i386``. 430 431* On OS X, CMake learned to enable behavior specified by the 432 :prop_tgt:`MACOSX_RPATH` target property by default. This activates 433 use of ``@rpath`` for runtime shared library searches. 434 See policy :policy:`CMP0042`. 435 436* The :command:`build_command` command now returns a :manual:`cmake(1)` 437 ``--build`` command line instead of a direct invocation of the native 438 build tool. When using ``Visual Studio`` generators, CMake and CTest 439 no longer require :variable:`CMAKE_MAKE_PROGRAM` to be located up front. 440 Selection of the proper msbuild or devenv tool is now performed as 441 late as possible when the solution (``.sln``) file is available so 442 it can depend on project content. 443 444* The :manual:`cmake(1)` ``--build`` command now shares its own stdout 445 and stderr pipes with the native build tool by default. 446 The ``--use-stderr`` option that once activated this is now ignored. 447 448* The ``$<C_COMPILER_ID:...>`` and ``$<CXX_COMPILER_ID:...>`` 449 :manual:`generator expressions <cmake-generator-expressions(7)>` 450 used to perform case-insensitive comparison but have now been 451 corrected to perform case-sensitive comparison. 452 See policy :policy:`CMP0044`. 453 454* The builtin ``edit_cache`` target will no longer select 455 :manual:`ccmake(1)` by default when no interactive terminal will 456 be available (e.g. with :generator:`Ninja` or an IDE generator). 457 Instead :manual:`cmake-gui(1)` will be preferred if available. 458 459* The :module:`ExternalProject` download step learned to 460 re-attempt download in certain cases to be more robust to 461 temporary network failure. 462 463* The :module:`FeatureSummary` no longer lists transitive 464 dependencies since they were not directly requested by the 465 current project. 466 467* The ``cmake-mode.el`` major Emacs editing mode has been cleaned 468 up and enhanced in several ways. 469 470* Include directories specified in the 471 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :ref:`Imported Targets` 472 are treated as ``SYSTEM`` includes by default when handled as 473 :ref:`usage requirements <Include Directories and Usage Requirements>`. 474