3.1.rst 16.2 KB
Newer Older
1 2
CMake 3.1 Release Notes
***********************
3 4 5 6 7

.. only:: html

  .. contents::

8
Changes made since CMake 3.0 include the following.
9

Brad King's avatar
Brad King committed
10 11
Documentation Changes
=====================
12

Brad King's avatar
Brad King committed
13
* A new :manual:`cmake-compile-features(7)` manual was added.
14

Brad King's avatar
Brad King committed
15 16
New Features
============
17

Brad King's avatar
Brad King committed
18 19
Generators
----------
20

21
* The :generator:`Visual Studio 14 2015` generator was added.
22

Brad King's avatar
Brad King committed
23 24
Windows Phone and Windows Store
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
25

Brad King's avatar
Brad King committed
26 27 28 29 30 31 32
* Generators for Visual Studio 11 (2012) and above learned to generate
  projects for Windows Phone and Windows Store.  One may set the
  :variable:`CMAKE_SYSTEM_NAME` variable to ``WindowsPhone``
  or ``WindowsStore`` on the :manual:`cmake(1)` command-line
  or in a :variable:`CMAKE_TOOLCHAIN_FILE` to activate these platforms.
  Also set :variable:`CMAKE_SYSTEM_VERSION` to ``8.0`` or ``8.1`` to
  specify the version of Windows to be targeted.
33

Brad King's avatar
Brad King committed
34 35
NVIDIA Nsight Tegra
^^^^^^^^^^^^^^^^^^^
36

Brad King's avatar
Brad King committed
37 38 39 40 41
* Generators for Visual Studio 10 (2010) and above learned to generate
  projects for NVIDIA Nsight Tegra Visual Studio Edition.  One may set
  the :variable:`CMAKE_SYSTEM_NAME` variable to ``Android`` on the
  :manual:`cmake(1)` command-line or in a :variable:`CMAKE_TOOLCHAIN_FILE`
  to activate this platform.
42

Brad King's avatar
Brad King committed
43 44
Syntax
------
45 46 47 48 49

* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and
  :ref:`Escape Sequences` was simplified in order to allow a much faster
  implementation.  See policy :policy:`CMP0053`.

Brad King's avatar
Brad King committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
* The :command:`if` command no longer automatically dereferences
  variables named in quoted or bracket arguments.  See policy
  :policy:`CMP0054`.

Commands
--------

* The :command:`add_custom_command` command learned to interpret
  :manual:`cmake-generator-expressions(7)` in arguments to ``DEPENDS``.

* The :command:`export(PACKAGE)` command learned to check the
  :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip
  exporting the package.

* The :command:`file(STRINGS)` command gained a new ``ENCODING``
  option to enable extraction of ``UTF-8`` strings.

* The :command:`find_package` command learned to check the
  :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and
  :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`
  variables to skip searching the package registries.

72 73 74
* The :command:`get_property` command learned a new ``INSTALL`` scope
  for properties.

Brad King's avatar
Brad King committed
75 76 77
* The :command:`install` command learned a ``MESSAGE_NEVER`` option
  to avoid output during installation.

78 79 80
* The :command:`set_property` command learned a new ``INSTALL`` scope
  for properties.

Brad King's avatar
Brad King committed
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
* The :command:`string` command learned a new ``GENEX_STRIP`` subcommand
  which removes
  :manual:`generator expression <cmake-generator-expressions(7)>`.

* The :command:`string` command learned a new ``UUID`` subcommand
  to generate a univerally unique identifier.

* New :command:`target_compile_features` command allows populating the
  :prop_tgt:`COMPILE_FEATURES` target property, just like any other
  build variable.

* The :command:`target_sources` command was added to add to the
  :prop_tgt:`SOURCES` target property.

Variables
---------

* The Visual Studio generators for versions 8 (2005) and above
  learned to read the target platform name from a new
  :variable:`CMAKE_GENERATOR_PLATFORM` variable when it is
  not specified as part of the generator name.  The platform
  name may be specified on the :manual:`cmake(1)` command line
  with the ``-A`` option, e.g. ``-G "Visual Studio 12 2013" -A x64``.

* The :variable:`CMAKE_GENERATOR_TOOLSET` variable may now be
  initialized in a toolchain file specified by the
  :variable:`CMAKE_TOOLCHAIN_FILE` variable.  This is useful
  when cross-compiling with the Xcode or Visual Studio
  generators.

* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to
  optionally reduce output installation.

Properties
----------

117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
* New :prop_tgt:`CXX_STANDARD` and :prop_tgt:`CXX_EXTENSIONS` target
  properties may specify values which CMake uses to compute required
  compile options such as ``-std=c++11`` or ``-std=gnu++11``. The
  :variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_EXTENSIONS`
  variables may be set to initialize the target properties.

* New :prop_tgt:`C_STANDARD` and :prop_tgt:`C_EXTENSIONS` target
  properties may specify values which CMake uses to compute required
  compile options such as ``-std=c11`` or ``-std=gnu11``. The
  :variable:`CMAKE_C_STANDARD` and :variable:`CMAKE_C_EXTENSIONS`
  variables may be set to initialize the target properties.

* New :prop_tgt:`COMPILE_FEATURES` target property may contain a list
  of features required to compile a target.  CMake uses this
  information to ensure that the compiler in use is capable of building
  the target, and to add any necessary compile flags to support language
  features.

Brad King's avatar
Brad King committed
135 136 137 138 139 140 141
* New :prop_tgt:`COMPILE_PDB_NAME` and
  :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties
  were introduced to specify the MSVC compiler program database
  file location (``cl /Fd``).  This complements the existing
  :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
  target properties that specify the linker program database
  file location (``link /pdb``).
142

Brad King's avatar
Brad King committed
143 144 145
* The :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property now supports
  a ``$<LINK_ONLY:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`.
146

Brad King's avatar
Brad King committed
147 148
* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is
  consumed by dependent targets, which compile and link the listed sources.
149

Brad King's avatar
Brad King committed
150 151 152 153
* The :prop_tgt:`SOURCES` target property now contains
  :manual:`generator expression <cmake-generator-expressions(7)>`
  such as ``TARGET_OBJECTS`` when read at configure time, if
  policy :policy:`CMP0051` is ``NEW``.
154

Brad King's avatar
Brad King committed
155 156 157 158
* The :prop_tgt:`SOURCES` target property now generally supports
  :manual:`generator expression <cmake-generator-expressions(7)>`.  The
  generator expressions may be used in the :command:`add_library` and
  :command:`add_executable` commands.
159

Brad King's avatar
Brad King committed
160 161 162
* It is now possible to write and append to the :prop_tgt:`SOURCES` target
  property.  The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be
  used to trace the origin of sources.
163

Brad King's avatar
Brad King committed
164 165 166
* A :prop_sf:`VS_DEPLOYMENT_CONTENT` source file property was added
  to tell the Visual Studio generators to mark content for deployment
  in Windows Phone and Windows Store projects.
167

168 169 170 171
* A :prop_sf:`VS_DEPLOYMENT_LOCATION` source file property was added
  to tell the Visual Studio generators the relative location of content
  marked for deployment in Windows Phone and Windows Store projects.

Brad King's avatar
Brad King committed
172 173 174
* The :prop_tgt:`VS_WINRT_COMPONENT` target property was created to
  tell Visual Studio generators to compile a shared library as a
  Windows Runtime (WinRT) component.
175

Brad King's avatar
Brad King committed
176 177 178 179
* The :generator:`Xcode` generator learned to check source
  file properties  :prop_sf:`XCODE_EXPLICIT_FILE_TYPE` and
  :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE` for a custom Xcode
  file reference type.
180

Brad King's avatar
Brad King committed
181 182
Modules
-------
183

Brad King's avatar
Brad King committed
184 185 186 187 188 189 190 191 192 193 194
* The :module:`BundleUtilities` module learned to resolve and replace
  ``@rpath`` placeholders on OS X to correctly bundle applications
  using them.

* The :module:`CMakePackageConfigHelpers` module
  :command:`configure_package_config_file` command learned a new
  ``INSTALL_PREFIX`` option to generate package configuration files
  meant for a prefix other than :variable:`CMAKE_INSTALL_PREFIX`.

* The :module:`CheckFortranSourceCompiles` module was added to
  provide a ``CHECK_Fortran_SOURCE_COMPILES`` macro.
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233

* The :module:`ExternalData` module learned to tolerate a ``DATA{}``
  reference to a missing source file with a warning instead of
  rejecting it with an error.  This helps developers write new
  ``DATA{}`` references to test reference outputs that have not
  yet been created.

* The :module:`ExternalProject` module learned to support lzma-compressed
  source tarballs with ``.7z``, ``.tar.xz``, and ``.txz`` extensions.

* The :module:`ExternalProject` module ``ExternalProject_Add`` command
  learned a new ``BUILD_ALWAYS`` option to cause the external project
  build step to run every time the host project is built.

* The :module:`ExternalProject` module ``ExternalProject_Add`` command
  learned a new ``EXCLUDE_FROM_ALL`` option to cause the external
  project target to have the :prop_tgt:`EXCLUDE_FROM_ALL` target
  property set.

* The :module:`ExternalProject` module ``ExternalProject_Add_Step`` command
  learned a new ``EXCLUDE_FROM_MAIN`` option to cause the step to not be
  a direct dependency of the main external project target.

* The :module:`ExternalProject` module ``ExternalProject_Add`` command
  learned a new ``DOWNLOAD_NO_PROGRESS`` option to disable progress
  output while downloading the source tarball.

* The :module:`FeatureSummary` module ``feature_summary`` API
  learned to accept multiple values for the ``WHAT`` option and
  combine them appropriately.

* The :module:`FindCUDA` module learned to support ``fatbin`` and ``cubin``
  modules.

* The :module:`FindGTest` module ``gtest_add_tests`` macro learned
  a new ``AUTO`` option to automatically read the :prop_tgt:`SOURCES`
  target property of the test executable and scan the source files
  for tests to be added.

Brad King's avatar
Brad King committed
234
* The :module:`FindGLEW` module now provides imported targets.
235 236 237

* The :module:`FindGLUT` module now provides imported targets.

Brad King's avatar
Brad King committed
238 239
* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to
  help run ``hg`` to extract information about a Mercurial work copy.
240

Brad King's avatar
Brad King committed
241
* The :module:`FindOpenCL` module was introduced.
242 243 244 245 246 247

* The :module:`FindOpenMP` module learned to support Fortran.

* The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG``
  environment variable value as the ``pkg-config`` executable, if set.

248 249
* The :module:`FindXercesC` module was introduced.

Brad King's avatar
Brad King committed
250
* The :module:`FindZLIB` module now provides imported targets.
251

Brad King's avatar
Brad King committed
252 253
* The :module:`GenerateExportHeader` module ``generate_export_header``
  function learned to allow use with :ref:`Object Libraries`.
254 255 256 257 258

* The :module:`InstallRequiredSystemLibraries` module gained a new
  ``CMAKE_INSTALL_OPENMP_LIBRARIES`` option to install MSVC OpenMP
  runtime libraries.

Brad King's avatar
Brad King committed
259 260 261
* The :module:`UseSWIG` module learned to detect the module name
  from ``.i`` source files if possible to avoid the need to set
  the ``SWIG_MODULE_NAME`` source file property explicitly.
262 263 264 265

* The :module:`WriteCompilerDetectionHeader` module was added to allow
  creation of a portable header file for compiler optional feature detection.

Brad King's avatar
Brad King committed
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
Generator Expressions
---------------------

* New ``COMPILE_FEATURES``
  :manual:`generator expression <cmake-generator-expressions(7)>` allows
  setting build properties based on available compiler features.

CTest
-----

* The :command:`ctest_coverage` command learned to read variable
  ``CTEST_COVERAGE_EXTRA_FLAGS`` to set ``CoverageExtraFlags``.

* The :command:`ctest_coverage` command learned to support
  Intel coverage files with the ``codecov`` tool.

* The :command:`ctest_memcheck` command learned to support sanitizer
  modes, including ``AddressSanitizer``, ``MemorySanitizer``,
  ``ThreadSanitizer``, and ``UndefinedBehaviorSanitizer``.
  Options may be set using the new
  :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable.

CPack
-----

* :manual:`cpack(1)` gained an ``IFW`` generator to package using
292
  Qt Framework Installer tools.  See the :cpack_gen:`CPack IFW Generator`.
Brad King's avatar
Brad King committed
293 294 295 296

* :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting
  lzma-compressed archives.

297
* The :cpack_gen:`CPack DEB Generator` learned a new
Brad King's avatar
Brad King committed
298 299 300
  :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the
  tarball compression type.

301
* The :cpack_gen:`CPack WIX Generator` learned to support
Brad King's avatar
Brad King committed
302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
  a :prop_inst:`CPACK_WIX_ACL` installed file property to
  specify an Access Control List.

Other
-----

* The :manual:`cmake(1)` ``-E`` option learned a new ``env`` command.

* The :manual:`cmake(1)` ``-E tar`` command learned to support
  lzma-compressed files.

* :ref:`Object Libraries` may now have extra sources that do not
  compile to object files so long as they would not affect linking
  of a normal library (e.g. ``.dat`` is okay but not ``.def``).

* Visual Studio generators for VS 8 and later learned to support
  the ``ASM_MASM`` language.

* The Visual Studio generators learned to treat ``.hlsl`` source
  files as High Level Shading Language sources (using ``FXCompile``
322 323 324 325
  in ``.vcxproj`` files).  Source file properties
  :prop_sf:`VS_SHADER_TYPE`, :prop_sf:`VS_SHADER_MODEL`, and
  :prop_sf:`VS_SHADER_ENTRYPOINT` were added added to specify the
  shader type, model, and entry point name.
Brad King's avatar
Brad King committed
326 327 328 329 330 331 332 333 334

New Diagnostics
===============

* Policy :policy:`CMP0052` introduced to control directories in the
  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of exported targets.

Deprecated and Removed Features
===============================
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355

* In CMake 3.0 the :command:`target_link_libraries` command
  accidentally began allowing unquoted arguments to use
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  containing a (``;`` separated) list within them.  For example::

    set(libs B C)
    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:${libs}>)

  This is equivalent to writing::

    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:B C>)

  and was never intended to work.  It did not work in CMake 2.8.12.
  Such generator expressions should be in quoted arguments::

    set(libs B C)
    target_link_libraries(A PUBLIC "$<BUILD_INTERFACE:${libs}>")

  CMake 3.1 again requires the quotes for this to work correctly.

356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377
* Prior to CMake 3.1 the Makefile generators did not escape ``#``
  correctly inside make variable assignments used in generated
  makefiles, causing them to be treated as comments.  This made
  code like::

    add_compile_options(-Wno-#pragma-messages)

  not work in Makefile generators, but work in other generators.
  Now it is escaped correctly, making the behavior consistent
  across generators.  However, some projects may have tried to
  workaround the original bug with code like::

    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-\\#pragma-messages")

  This added the needed escape for Makefile generators but also
  caused other generators to pass ``-Wno-\#pragma-messages`` to
  the shell, which would work only in POSIX shells.
  Unfortunately the escaping fix could not be made in a compatible
  way so this platform- and generator-specific workaround no
  longer works.  Project code may test the :variable:`CMAKE_VERSION`
  variable value to make the workaround version-specific too.

378 379 380 381 382 383
* Callbacks established by the :command:`variable_watch` command will no
  longer receive the ``ALLOWED_UNKNOWN_READ_ACCESS`` access type when
  the undocumented ``CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS`` variable is
  set.  Uninitialized variable accesses will always be reported as
  ``UNKNOWN_READ_ACCESS``.

Brad King's avatar
Brad King committed
384 385 386
* The :module:`CMakeDetermineVSServicePack` module now warns that
  it is deprecated and should not longer be used.  Use the
  :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable instead.
387

388 389 390 391 392 393 394 395 396 397 398
* The :module:`FindITK` module has been removed altogether.
  It was a thin-wrapper around ``find_package(ITK ... NO_MODULE)``.
  This produces much clearer error messages when ITK is not found.

* The :module:`FindVTK` module has been removed altogether.
  It was a thin-wrapper around ``find_package(VTK ... NO_MODULE)``.
  This produces much clearer error messages when VTK is not found.

  The module also provided compatibility support for finding VTK 4.0.
  This capability has been dropped.

Brad King's avatar
Brad King committed
399 400
Other Changes
=============
401

Brad King's avatar
Brad King committed
402 403 404
* The :manual:`cmake-gui(1)` learned to capture output from child
  processes started by the :command:`execute_process` command
  and display it in the output window.
405

Brad King's avatar
Brad King committed
406 407 408
* The :manual:`cmake-language(7)` internal implementation of generator
  expression and list expansion parsers have been optimized and shows
  non-trivial speedup on large projects.
409

Brad King's avatar
Brad King committed
410 411
* The Makefile generators learned to use response files with GNU tools
  on Windows to pass library directories and names to the linker.
412

Brad King's avatar
Brad King committed
413 414
* When generating linker command-lines, CMake now avoids repeating
  items corresponding to SHARED library targets.
415

Brad King's avatar
Brad King committed
416 417 418 419 420 421
* Support for the Open Watcom compiler has been overhauled.
  The :variable:`CMAKE_<LANG>_COMPILER_ID` is now ``OpenWatcom``,
  and the :variable:`CMAKE_<LANG>_COMPILER_VERSION` now uses
  the Open Watcom external version numbering.  The external
  version numbers are lower than the internal version number
  by 11.
422 423 424 425

* The ``cmake-mode.el`` major Emacs editing mode no longer
  treats ``_`` as part of words, making it more consistent
  with other major modes.