summaryrefslogtreecommitdiffstats
path: root/Help/release/3.1.0.rst
blob: 96717c638b25f423831f6a40372f3a90eabb7231 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
CMake 3.1.0 Release Notes
*************************

.. only:: html

  .. contents::

Changes made since CMake 3.0.0 include the following.

Documentation Changes
=====================

* A new :manual:`cmake-compile-features(7)` manual was added.

New Features
============

Generators
----------

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

Windows Phone and Windows Store
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* 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.

NVIDIA Nsight Tegra
^^^^^^^^^^^^^^^^^^^

* 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.

Syntax
------

* 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`.

* 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.

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

* The :command:`install` command learned a ``MESSAGE_NEVER`` option
  to avoid output during installation.

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

* 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
----------

* 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.

* 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``).

* The :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property now supports
  a ``$<LINK_ONLY:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`.

* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is
  consumed by dependent targets, which compile and link the listed sources.

* 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``.

* 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.

* 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.

* 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.

* 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.

* 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.

* 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.

Modules
-------

* 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.

* 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.

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

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

* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to
  help run ``hg`` to extract information about a Mercurial work copy.

* The :module:`FindOpenCL` module was introduced.

* 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.

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

* The :module:`GenerateExportHeader` module ``generate_export_header``
  function learned to allow use with :ref:`Object Libraries`.

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

* 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.

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

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
  Qt Framework Installer tools.  See the :module:`CPackIFW` module.

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

* The :module:`CPackDeb` module learned a new
  :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the
  tarball compression type.

* The :manual:`cpack(1)` ``WiX`` generator learned to support
  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``
  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.

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

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

Deprecated and Removed Features
===============================

* 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.

* 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``.

* 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.

* 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.

Other Changes
=============

* 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.

* 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.

* The Makefile generators learned to use response files with GNU tools
  on Windows to pass library directories and names to the linker.

* When generating linker command-lines, CMake now avoids repeating
  items corresponding to SHARED library targets.

* 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.

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