Help/release/3.0.rst

   1 CMake 3.0 Release Notes
   2 ***********************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 2.8.12 include the following.
   9
  10 Documentation Changes
  11 =====================
  12
  13 * The CMake documentation has been converted to reStructuredText and
  14   now transforms via Sphinx (`<https://www.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
  45 New Features
  46 ============
  47
  48 Syntax
  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
  68 Generators
  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
  80 Commands
  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
 134 Variables
 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
 166 Properties
 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
 203 Modules
 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
 250 Generator 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
 270 Other
 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
 285 New 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
 342 Deprecated 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
 396 Other 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>`.