1CMake 3.1 Release Notes
2***********************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.0 include the following.
9
10Documentation Changes
11=====================
12
13* A new :manual:`cmake-compile-features(7)` manual was added.
14
15New Features
16============
17
18Generators
19----------
20
21* The :generator:`Visual Studio 14 2015` generator was added.
22
23Windows Phone and Windows Store
24^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
25
26* Generators for Visual Studio 11 (2012) and above learned to generate
27  projects for Windows Phone and Windows Store.  One may set the
28  :variable:`CMAKE_SYSTEM_NAME` variable to ``WindowsPhone``
29  or ``WindowsStore`` on the :manual:`cmake(1)` command-line
30  or in a :variable:`CMAKE_TOOLCHAIN_FILE` to activate these platforms.
31  Also set :variable:`CMAKE_SYSTEM_VERSION` to ``8.0`` or ``8.1`` to
32  specify the version of Windows to be targeted.
33
34NVIDIA Nsight Tegra
35^^^^^^^^^^^^^^^^^^^
36
37* Generators for Visual Studio 10 (2010) and above learned to generate
38  projects for NVIDIA Nsight Tegra Visual Studio Edition.  One may set
39  the :variable:`CMAKE_SYSTEM_NAME` variable to ``Android`` on the
40  :manual:`cmake(1)` command-line or in a :variable:`CMAKE_TOOLCHAIN_FILE`
41  to activate this platform.
42
43Syntax
44------
45
46* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and
47  :ref:`Escape Sequences` was simplified in order to allow a much faster
48  implementation.  See policy :policy:`CMP0053`.
49
50* The :command:`if` command no longer automatically dereferences
51  variables named in quoted or bracket arguments.  See policy
52  :policy:`CMP0054`.
53
54Commands
55--------
56
57* The :command:`add_custom_command` command learned to interpret
58  :manual:`cmake-generator-expressions(7)` in arguments to ``DEPENDS``.
59
60* The :command:`export(PACKAGE)` command learned to check the
61  :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip
62  exporting the package.
63
64* The :command:`file(STRINGS)` command gained a new ``ENCODING``
65  option to enable extraction of ``UTF-8`` strings.
66
67* The :command:`find_package` command learned to check the
68  :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and
69  :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`
70  variables to skip searching the package registries.
71
72* The :command:`get_property` command learned a new ``INSTALL`` scope
73  for properties.
74
75* The :command:`install` command learned a ``MESSAGE_NEVER`` option
76  to avoid output during installation.
77
78* The :command:`set_property` command learned a new ``INSTALL`` scope
79  for properties.
80
81* The :command:`string` command learned a new ``GENEX_STRIP`` subcommand
82  which removes
83  :manual:`generator expression <cmake-generator-expressions(7)>`.
84
85* The :command:`string` command learned a new ``UUID`` subcommand
86  to generate a universally unique identifier.
87
88* New :command:`target_compile_features` command allows populating the
89  :prop_tgt:`COMPILE_FEATURES` target property, just like any other
90  build variable.
91
92* The :command:`target_sources` command was added to add to the
93  :prop_tgt:`SOURCES` target property.
94
95Variables
96---------
97
98* The Visual Studio generators for versions 8 (2005) and above
99  learned to read the target platform name from a new
100  :variable:`CMAKE_GENERATOR_PLATFORM` variable when it is
101  not specified as part of the generator name.  The platform
102  name may be specified on the :manual:`cmake(1)` command line
103  with the ``-A`` option, e.g. ``-G "Visual Studio 12 2013" -A x64``.
104
105* The :variable:`CMAKE_GENERATOR_TOOLSET` variable may now be
106  initialized in a toolchain file specified by the
107  :variable:`CMAKE_TOOLCHAIN_FILE` variable.  This is useful
108  when cross-compiling with the Xcode or Visual Studio
109  generators.
110
111* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to
112  optionally reduce output installation.
113
114Properties
115----------
116
117* New :prop_tgt:`CXX_STANDARD` and :prop_tgt:`CXX_EXTENSIONS` target
118  properties may specify values which CMake uses to compute required
119  compile options such as ``-std=c++11`` or ``-std=gnu++11``. The
120  :variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_EXTENSIONS`
121  variables may be set to initialize the target properties.
122
123* New :prop_tgt:`C_STANDARD` and :prop_tgt:`C_EXTENSIONS` target
124  properties may specify values which CMake uses to compute required
125  compile options such as ``-std=c11`` or ``-std=gnu11``. The
126  :variable:`CMAKE_C_STANDARD` and :variable:`CMAKE_C_EXTENSIONS`
127  variables may be set to initialize the target properties.
128
129* New :prop_tgt:`COMPILE_FEATURES` target property may contain a list
130  of features required to compile a target.  CMake uses this
131  information to ensure that the compiler in use is capable of building
132  the target, and to add any necessary compile flags to support language
133  features.
134
135* New :prop_tgt:`COMPILE_PDB_NAME` and
136  :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties
137  were introduced to specify the MSVC compiler program database
138  file location (``cl /Fd``).  This complements the existing
139  :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY`
140  target properties that specify the linker program database
141  file location (``link /pdb``).
142
143* The :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property now supports
144  a ``$<LINK_ONLY:...>``
145  :manual:`generator expression <cmake-generator-expressions(7)>`.
146
147* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is
148  consumed by dependent targets, which compile and link the listed sources.
149
150* The :prop_tgt:`SOURCES` target property now contains
151  :manual:`generator expression <cmake-generator-expressions(7)>`
152  such as ``TARGET_OBJECTS`` when read at configure time, if
153  policy :policy:`CMP0051` is ``NEW``.
154
155* The :prop_tgt:`SOURCES` target property now generally supports
156  :manual:`generator expression <cmake-generator-expressions(7)>`.  The
157  generator expressions may be used in the :command:`add_library` and
158  :command:`add_executable` commands.
159
160* It is now possible to write and append to the :prop_tgt:`SOURCES` target
161  property.  The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be
162  used to trace the origin of sources.
163
164* A :prop_sf:`VS_DEPLOYMENT_CONTENT` source file property was added
165  to tell the Visual Studio generators to mark content for deployment
166  in Windows Phone and Windows Store projects.
167
168* A :prop_sf:`VS_DEPLOYMENT_LOCATION` source file property was added
169  to tell the Visual Studio generators the relative location of content
170  marked for deployment in Windows Phone and Windows Store projects.
171
172* The :prop_tgt:`VS_WINRT_COMPONENT` target property was created to
173  tell Visual Studio generators to compile a shared library as a
174  Windows Runtime (WinRT) component.
175
176* The :generator:`Xcode` generator learned to check source
177  file properties  :prop_sf:`XCODE_EXPLICIT_FILE_TYPE` and
178  :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE` for a custom Xcode
179  file reference type.
180
181Modules
182-------
183
184* The :module:`BundleUtilities` module learned to resolve and replace
185  ``@rpath`` placeholders on OS X to correctly bundle applications
186  using them.
187
188* The :module:`CMakePackageConfigHelpers` module
189  :command:`configure_package_config_file` command learned a new
190  ``INSTALL_PREFIX`` option to generate package configuration files
191  meant for a prefix other than :variable:`CMAKE_INSTALL_PREFIX`.
192
193* The :module:`CheckFortranSourceCompiles` module was added to
194  provide a ``CHECK_Fortran_SOURCE_COMPILES`` macro.
195
196* The :module:`ExternalData` module learned to tolerate a ``DATA{}``
197  reference to a missing source file with a warning instead of
198  rejecting it with an error.  This helps developers write new
199  ``DATA{}`` references to test reference outputs that have not
200  yet been created.
201
202* The :module:`ExternalProject` module learned to support lzma-compressed
203  source tarballs with ``.7z``, ``.tar.xz``, and ``.txz`` extensions.
204
205* The :module:`ExternalProject` module ``ExternalProject_Add`` command
206  learned a new ``BUILD_ALWAYS`` option to cause the external project
207  build step to run every time the host project is built.
208
209* The :module:`ExternalProject` module ``ExternalProject_Add`` command
210  learned a new ``EXCLUDE_FROM_ALL`` option to cause the external
211  project target to have the :prop_tgt:`EXCLUDE_FROM_ALL` target
212  property set.
213
214* The :module:`ExternalProject` module ``ExternalProject_Add_Step`` command
215  learned a new ``EXCLUDE_FROM_MAIN`` option to cause the step to not be
216  a direct dependency of the main external project target.
217
218* The :module:`ExternalProject` module ``ExternalProject_Add`` command
219  learned a new ``DOWNLOAD_NO_PROGRESS`` option to disable progress
220  output while downloading the source tarball.
221
222* The :module:`FeatureSummary` module ``feature_summary`` API
223  learned to accept multiple values for the ``WHAT`` option and
224  combine them appropriately.
225
226* The :module:`FindCUDA` module learned to support ``fatbin`` and ``cubin``
227  modules.
228
229* The :module:`FindGTest` module ``gtest_add_tests`` macro learned
230  a new ``AUTO`` option to automatically read the :prop_tgt:`SOURCES`
231  target property of the test executable and scan the source files
232  for tests to be added.
233
234* The :module:`FindGLEW` module now provides imported targets.
235
236* The :module:`FindGLUT` module now provides imported targets.
237
238* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to
239  help run ``hg`` to extract information about a Mercurial work copy.
240
241* The :module:`FindOpenCL` module was introduced.
242
243* The :module:`FindOpenMP` module learned to support Fortran.
244
245* The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG``
246  environment variable value as the ``pkg-config`` executable, if set.
247
248* The :module:`FindXercesC` module was introduced.
249
250* The :module:`FindZLIB` module now provides imported targets.
251
252* The :module:`GenerateExportHeader` module ``generate_export_header``
253  function learned to allow use with :ref:`Object Libraries`.
254
255* The :module:`InstallRequiredSystemLibraries` module gained a new
256  ``CMAKE_INSTALL_OPENMP_LIBRARIES`` option to install MSVC OpenMP
257  runtime libraries.
258
259* The :module:`UseSWIG` module learned to detect the module name
260  from ``.i`` source files if possible to avoid the need to set
261  the ``SWIG_MODULE_NAME`` source file property explicitly.
262
263* The :module:`WriteCompilerDetectionHeader` module was added to allow
264  creation of a portable header file for compiler optional feature detection.
265
266Generator Expressions
267---------------------
268
269* New ``COMPILE_FEATURES``
270  :manual:`generator expression <cmake-generator-expressions(7)>` allows
271  setting build properties based on available compiler features.
272
273CTest
274-----
275
276* The :command:`ctest_coverage` command learned to read variable
277  ``CTEST_COVERAGE_EXTRA_FLAGS`` to set ``CoverageExtraFlags``.
278
279* The :command:`ctest_coverage` command learned to support
280  Intel coverage files with the ``codecov`` tool.
281
282* The :command:`ctest_memcheck` command learned to support sanitizer
283  modes, including ``AddressSanitizer``, ``MemorySanitizer``,
284  ``ThreadSanitizer``, and ``UndefinedBehaviorSanitizer``.
285  Options may be set using the new
286  :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable.
287
288CPack
289-----
290
291* :manual:`cpack(1)` gained an ``IFW`` generator to package using
292  Qt Framework Installer tools.  See the :cpack_gen:`CPack IFW Generator`.
293
294* :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting
295  lzma-compressed archives.
296
297* The :cpack_gen:`CPack DEB Generator` learned a new
298  :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the
299  tarball compression type.
300
301* The :cpack_gen:`CPack WIX Generator` learned to support
302  a :prop_inst:`CPACK_WIX_ACL` installed file property to
303  specify an Access Control List.
304
305Other
306-----
307
308* The :manual:`cmake(1)` ``-E`` option learned a new ``env`` command.
309
310* The :manual:`cmake(1)` ``-E tar`` command learned to support
311  lzma-compressed files.
312
313* :ref:`Object Libraries` may now have extra sources that do not
314  compile to object files so long as they would not affect linking
315  of a normal library (e.g. ``.dat`` is okay but not ``.def``).
316
317* Visual Studio generators for VS 8 and later learned to support
318  the ``ASM_MASM`` language.
319
320* The Visual Studio generators learned to treat ``.hlsl`` source
321  files as High Level Shading Language sources (using ``FXCompile``
322  in ``.vcxproj`` files).  Source file properties
323  :prop_sf:`VS_SHADER_TYPE`, :prop_sf:`VS_SHADER_MODEL`, and
324  :prop_sf:`VS_SHADER_ENTRYPOINT` were added added to specify the
325  shader type, model, and entry point name.
326
327New Diagnostics
328===============
329
330* Policy :policy:`CMP0052` introduced to control directories in the
331  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of exported targets.
332
333Deprecated and Removed Features
334===============================
335
336* In CMake 3.0 the :command:`target_link_libraries` command
337  accidentally began allowing unquoted arguments to use
338  :manual:`generator expressions <cmake-generator-expressions(7)>`
339  containing a (``;`` separated) list within them.  For example::
340
341    set(libs B C)
342    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:${libs}>)
343
344  This is equivalent to writing::
345
346    target_link_libraries(A PUBLIC $<BUILD_INTERFACE:B C>)
347
348  and was never intended to work.  It did not work in CMake 2.8.12.
349  Such generator expressions should be in quoted arguments::
350
351    set(libs B C)
352    target_link_libraries(A PUBLIC "$<BUILD_INTERFACE:${libs}>")
353
354  CMake 3.1 again requires the quotes for this to work correctly.
355
356* Prior to CMake 3.1 the Makefile generators did not escape ``#``
357  correctly inside make variable assignments used in generated
358  makefiles, causing them to be treated as comments.  This made
359  code like::
360
361    add_compile_options(-Wno-#pragma-messages)
362
363  not work in Makefile generators, but work in other generators.
364  Now it is escaped correctly, making the behavior consistent
365  across generators.  However, some projects may have tried to
366  workaround the original bug with code like::
367
368    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-\\#pragma-messages")
369
370  This added the needed escape for Makefile generators but also
371  caused other generators to pass ``-Wno-\#pragma-messages`` to
372  the shell, which would work only in POSIX shells.
373  Unfortunately the escaping fix could not be made in a compatible
374  way so this platform- and generator-specific workaround no
375  longer works.  Project code may test the :variable:`CMAKE_VERSION`
376  variable value to make the workaround version-specific too.
377
378* Callbacks established by the :command:`variable_watch` command will no
379  longer receive the ``ALLOWED_UNKNOWN_READ_ACCESS`` access type when
380  the undocumented ``CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS`` variable is
381  set.  Uninitialized variable accesses will always be reported as
382  ``UNKNOWN_READ_ACCESS``.
383
384* The :module:`CMakeDetermineVSServicePack` module now warns that
385  it is deprecated and should not longer be used.  Use the
386  :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable instead.
387
388* The :module:`FindITK` module has been removed altogether.
389  It was a thin-wrapper around ``find_package(ITK ... NO_MODULE)``.
390  This produces much clearer error messages when ITK is not found.
391
392* The :module:`FindVTK` module has been removed altogether.
393  It was a thin-wrapper around ``find_package(VTK ... NO_MODULE)``.
394  This produces much clearer error messages when VTK is not found.
395
396  The module also provided compatibility support for finding VTK 4.0.
397  This capability has been dropped.
398
399Other Changes
400=============
401
402* The :manual:`cmake-gui(1)` learned to capture output from child
403  processes started by the :command:`execute_process` command
404  and display it in the output window.
405
406* The :manual:`cmake-language(7)` internal implementation of generator
407  expression and list expansion parsers have been optimized and shows
408  non-trivial speedup on large projects.
409
410* The Makefile generators learned to use response files with GNU tools
411  on Windows to pass library directories and names to the linker.
412
413* When generating linker command-lines, CMake now avoids repeating
414  items corresponding to SHARED library targets.
415
416* Support for the Open Watcom compiler has been overhauled.
417  The :variable:`CMAKE_<LANG>_COMPILER_ID` is now ``OpenWatcom``,
418  and the :variable:`CMAKE_<LANG>_COMPILER_VERSION` now uses
419  the Open Watcom external version numbering.  The external
420  version numbers are lower than the internal version number
421  by 11.
422
423* The ``cmake-mode.el`` major Emacs editing mode no longer
424  treats ``_`` as part of words, making it more consistent
425  with other major modes.
426