summaryrefslogtreecommitdiffstats
path: root/Help/release/3.0.rst
blob: d02f94093c426d6953f06844afd43e0160126d16 (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
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
CMake 3.0 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 2.8.12 include the following.

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

* The CMake documentation has been converted to reStructuredText and
  now transforms via Sphinx (`<http://sphinx-doc.org>`__) into man and
  html pages.  This allows the documentation to be properly indexed
  and to contain cross-references.

  Conversion from the old internal documentation format was done by
  an automatic process so some documents may still contain artifacts.
  They will be updated incrementally over time.

  A basic reStructuredText processor has been implemented to support
  ``cmake --help-command`` and similar command-line options.

* New manuals were added:

  - :manual:`cmake-buildsystem(7)`
  - :manual:`cmake-commands(7)`, replacing ``cmakecommands(1)``
    and ``cmakecompat(1)``
  - :manual:`cmake-developer(7)`
  - :manual:`cmake-generator-expressions(7)`
  - :manual:`cmake-generators(7)`
  - :manual:`cmake-language(7)`
  - :manual:`cmake-modules(7)`, replacing ``cmakemodules(1)``
  - :manual:`cmake-packages(7)`
  - :manual:`cmake-policies(7)`, replacing ``cmakepolicies(1)``
  - :manual:`cmake-properties(7)`, replacing ``cmakeprops(1)``
  - :manual:`cmake-qt(7)`
  - :manual:`cmake-toolchains(7)`
  - :manual:`cmake-variables(7)`, replacing ``cmakevars(1)``

* Release notes for CMake 3.0.0 and above will now be included with
  the html documentation.

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

Syntax
------

* The CMake language has been extended with
  :ref:`Bracket Argument` and  :ref:`Bracket Comment`
  syntax inspired by Lua long brackets::

    set(x [===[bracket argument]===] #[[bracket comment]])

  Content between equal-length open- and close-brackets is taken
  literally with no variable replacements.

  .. warning::
    This syntax change could not be made in a fully compatible
    way.  No policy is possible because syntax parsing occurs before
    any chance to set a policy.  Existing code using an unquoted
    argument that starts with an open bracket will be interpreted
    differently without any diagnostic.  Fortunately the syntax is
    obscure enough that this problem is unlikely in practice.

Generators
----------

* A new :generator:`CodeLite` extra generator is available
  for use with the Makefile or Ninja generators.

* A new :generator:`Kate` extra generator is available
  for use with the Makefile or Ninja generators.

* The :generator:`Ninja` generator learned to use ``ninja`` job pools
  when specified by a new :prop_gbl:`JOB_POOLS` global property.

Commands
--------

* The :command:`add_library` command learned a new ``INTERFACE``
  library type.  Interface libraries have no build rules but may
  have properties defining
  :manual:`usage requirements <cmake-buildsystem(7)>`
  and may be installed, exported, and imported.  This is useful to
  create header-only libraries that have concrete link dependencies
  on other libraries.

* The :command:`export()` command learned a new ``EXPORT`` mode that
  retrieves the list of targets to export from an export set configured
  by the :command:`install(TARGETS)` command ``EXPORT`` option.  This
  makes it easy to export from the build tree the same targets that
  are exported from the install tree.

* The :command:`export` command learned to work with multiple dependent
  export sets, thus allowing multiple packages to be built and exported
  from a single tree.  The feature requires CMake to wait until the
  generation step to write the output file.  This means one should not
  :command:`include` the generated targets file later during project
  configuration because it will not be available.
  Use :ref:`Alias Targets` instead.  See policy :policy:`CMP0024`.

* The :command:`install(FILES)` command learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  in the list of files.

* The :command:`project` command learned to set some version variables
  to values specified by the new ``VERSION`` option or to empty strings.
  See policy :policy:`CMP0048`.

* The :command:`string` command learned a new ``CONCAT`` mode.
  It is particularly useful in combination with the new
  :ref:`Bracket Argument` syntax.

* The :command:`unset` command learned a ``PARENT_SCOPE`` option
  matching that of the :command:`set` command.

* The :command:`include_external_msproject` command learned
  to handle non-C++ projects like ``.vbproj`` or ``.csproj``.

* The :command:`ctest_update` command learned to update work trees
  managed by the Perforce (p4) version control tool.

* The :command:`message` command learned a ``DEPRECATION`` mode. Such
  messages are not issued by default, but may be issued as a warning if
  :variable:`CMAKE_WARN_DEPRECATED` is enabled, or as an error if
  :variable:`CMAKE_ERROR_DEPRECATED` is enabled.

* The :command:`target_link_libraries` command now allows repeated use of
  the ``LINK_PUBLIC`` and ``LINK_PRIVATE`` keywords.

Variables
---------

* Variable :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` has been
  introduced to tell CMake not to add the value of
  :variable:`CMAKE_INSTALL_PREFIX` to the
  :variable:`CMAKE_SYSTEM_PREFIX_PATH` variable by default.
  This is useful when building a project that installs some
  of its own dependencies to avoid finding files it is about
  to replace.

* Variable :variable:`CMAKE_STAGING_PREFIX` was introduced for use
  when cross-compiling to specify an installation prefix on the
  host system that differs from a :variable:`CMAKE_INSTALL_PREFIX`
  value meant for the target system.

* Variable :variable:`CMAKE_SYSROOT` was introduced to specify the
  toolchain SDK installation prefix, typically for cross-compiling.
  This is used to pass a ``--sysroot`` option to the compiler and
  as a prefix searched by ``find_*`` commands.

* Variable :variable:`CMAKE_<LANG>_COMPILER_TARGET` was introduced
  for use when cross-compiling to specify the target platform in the
  :ref:`toolchain file <Cross Compiling Toolchain>` specified by the
  :variable:`CMAKE_TOOLCHAIN_FILE` variable.
  This is used to pass an option such as ``--target=<triple>`` to some
  cross-compiling compiler drivers.

* Variable :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` has been
  introduced to optionally initialize the
  :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property.

Properties
----------

* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property
  learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* A new directory property :prop_dir:`CMAKE_CONFIGURE_DEPENDS`
  was introduced to allow projects to specify additional
  files on which the configuration process depends.  CMake will
  re-run at build time when one of these files is modified.
  Previously this was only possible to achieve by specifying
  such files as the input to a :command:`configure_file` command.

* A new :ref:`Qt AUTORCC` feature replaces the need to
  invoke ``qt4_add_resources()`` by allowing ``.qrc`` files to
  be listed as target sources.

* A new :ref:`Qt AUTOUIC` feature replaces the need to
  invoke ``qt4_wrap_ui()``.

* Test properties learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.
  This is useful to specify per-configuration values for test
  properties like :prop_test:`REQUIRED_FILES` and
  :prop_test:`WORKING_DIRECTORY`.

* A new :prop_test:`SKIP_RETURN_CODE` test property was introduced
  to tell :manual:`ctest(1)` to treat a particular test return code as
  if the test were not run.  This is useful for test drivers to report
  that certain test requirements were not available.

* New types of :ref:`Compatible Interface Properties` were introduced,
  namely the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and
  :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` for calculating numeric
  maximum and minimum values respectively.

Modules
-------

* The :module:`CheckTypeSize` module ``check_type_size`` macro and
  the :module:`CheckStructHasMember` module ``check_struct_has_member``
  macro learned a new ``LANGUAGE`` option to optionally check C++ types.

* The :module:`ExternalData` module learned to work with no
  URL templates if a local store is available.

* The :module:`ExternalProject` function ``ExternalProject_Add``
  learned a new ``GIT_SUBMODULES`` option to specify a subset
  of available submodules to checkout.

* A new :module:`FindBacktrace` module has been added to support
  :command:`find_package(Backtrace)` calls.

* A new :module:`FindLua` module has been added to support
  :command:`find_package(Lua)` calls.

* The :module:`FindBoost` module learned a new ``Boost_NAMESPACE``
  option to change the ``boost`` prefix on library names.

* The :module:`FindBoost` module learned to control search
  for libraies with the ``g`` tag (for MS debug runtime) with
  a new ``Boost_USE_DEBUG_RUNTIME`` option.  It is ``ON`` by
  default to preserve existing behavior.

* The :module:`FindJava` and :module:`FindJNI` modules learned
  to use a ``JAVA_HOME`` CMake variable or environment variable,
  and then try ``/usr/libexec/java_home`` on OS X.

* The :module:`UseJava` module ``add_jar`` function learned a new
  ``MANIFEST`` option to pass the ``-m`` option to ``jar``.

* A new :module:`CMakeFindDependencyMacro` module was introduced with
  a ``find_dependency`` macro to find transitive dependencies in
  a :manual:`package configuration file <cmake-packages(7)>`.  Such
  dependencies are omitted by the listing of the :module:`FeatureSummary`
  module.

* The :module:`FindQt4` module learned to create :ref:`Imported Targets`
  for Qt executables.  This helps disambiguate when using multiple
  :manual:`Qt versions <cmake-qt(7)>` in the same buildsystem.

* The :module:`FindRuby` module learned to search for Ruby 2.0 and 2.1.

Generator Expressions
---------------------

* New ``$<PLATFORM_ID>`` and ``$<PLATFORM_ID:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  have been added.

* The ``$<CONFIG>``
  :manual:`generator expression <cmake-generator-expressions(7)>` now has
  a variant which takes no argument.  This is equivalent to the
  ``$<CONFIGURATION>`` expression.

* New ``$<UPPER_CASE:...>`` and ``$<LOWER_CASE:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  generator expressions have been added.

* A new ``$<MAKE_C_IDENTIFIER:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>` has
  been added.

Other
-----

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

* The :manual:`ccmake(1)` dialog learned to honor the
  :prop_cache:`STRINGS` cache entry property to cycle through
  the enumerated list of possible values.

* The :manual:`cmake-gui(1)` dialog learned to remember window
  settings between sessions.

* The :manual:`cmake-gui(1)` dialog learned to remember the type
  of a cache entry for completion in the ``Add Entry`` dialog.

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

* Directories named in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
  target property of imported targets linked conditionally by a
  :manual:`generator expression <cmake-generator-expressions(7)>`
  were not checked for existence.  Now they are checked.
  See policy :policy:`CMP0027`.

* Build target names must now match a validity pattern and may no longer
  conflict with CMake-defined targets.  See policy :policy:`CMP0037`.

* Build targets that specify themselves as a link dependency were
  silently accepted but are now diagnosed.  See :policy:`CMP0038`.

* The :command:`target_link_libraries` command used to silently ignore
  calls specifying as their first argument build targets created by
  :command:`add_custom_target` but now diagnoses this mistake.
  See policy :policy:`CMP0039`.

* The :command:`add_custom_command` command used to silently ignore
  calls specifying the ``TARGET`` option with a non-existent target
  but now diagnoses this mistake.  See policy :policy:`CMP0040`.

* Relative paths in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
  target property used to be silently accepted if they contained a
  :manual:`generator expression <cmake-generator-expressions(7)>`
  but are now rejected.  See policy :policy:`CMP0041`.

* The :command:`get_target_property` command learned to reject calls
  specifying a non-existent target.  See policy :policy:`CMP0045`.

* The :command:`add_dependencies` command learned to reject calls
  specifying a dependency on a non-existent target.
  See policy :policy:`CMP0046`.

* Link dependency analysis learned to assume names containing ``::``
  refer to :ref:`Alias Targets` or :ref:`Imported Targets`.  It will
  now produce an error if such a linked target is missing.  Previously
  in this case CMake generated a link line that failed at build time.
  See policy :policy:`CMP0028`.

* When the :command:`project` or :command:`enable_language` commands
  initialize support for a language, it is now an error if the full
  path to the compiler cannot be found and stored in the corresponding
  :variable:`CMAKE_<LANG>_COMPILER` variable.  This produces nicer error
  messages up front and stops processing when no working compiler
  is known to be available.

* Target sources specified with the :command:`add_library` or
  :command:`add_executable` command learned to reject items which
  require an undocumented extra layer of variable expansion.
  See policy :policy:`CMP0049`.

* Use of :command:`add_custom_command` undocumented ``SOURCE``
  signatures now results in an error.  See policy :policy:`CMP0050`.

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

* Compatibility options supporting code written for CMake versions
  prior to 2.4 have been removed.

* Several long-outdated commands that should no longer be called
  have been disallowed in new code by policies:

  - Policy :policy:`CMP0029` disallows :command:`subdir_depends`
  - Policy :policy:`CMP0030` disallows :command:`use_mangled_mesa`
  - Policy :policy:`CMP0031` disallows :command:`load_command`
  - Policy :policy:`CMP0032` disallows :command:`output_required_files`
  - Policy :policy:`CMP0033` disallows :command:`export_library_dependencies`
  - Policy :policy:`CMP0034` disallows :command:`utility_source`
  - Policy :policy:`CMP0035` disallows :command:`variable_requires`
  - Policy :policy:`CMP0036` disallows :command:`build_name`

* The :manual:`cmake(1)` ``-i`` wizard mode has been removed.
  Instead use an interactive dialog such as :manual:`ccmake(1)`
  or use the ``-D`` option to set cache values from the command line.

* The builtin documentation formatters that supported command-line
  options such as ``--help-man`` and ``--help-html`` have been removed
  in favor of the above-mentioned new documentation system.  These and
  other command-line options that used to generate man- and html-
  formatted pages no longer work.  The :manual:`cmake(1)`
  ``--help-custom-modules`` option now produces a warning at runtime
  and generates a minimal document that reports the limitation.

* The :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` directory properties and the
  :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target properties have been
  deprecated.  Instead set the corresponding :prop_dir:`COMPILE_DEFINITIONS`
  directory property or :prop_tgt:`COMPILE_DEFINITIONS` target property and
  use :manual:`generator expressions <cmake-generator-expressions(7)>` like
  ``$<CONFIG:...>`` to specify per-configuration definitions.
  See policy :policy:`CMP0043`.

* The :prop_tgt:`LOCATION` target property should no longer be read from
  non-IMPORTED targets.  It does not make sense in multi-configuration
  generators since the build configuration is not known while configuring
  the project.  It has been superseded by the ``$<TARGET_FILE>`` generator
  expression.  See policy :policy:`CMP0026`.

* The :prop_tgt:`COMPILE_FLAGS` target property is now documented
  as deprecated, though no warning is issued.  Use the
  :prop_tgt:`COMPILE_OPTIONS` target property or the
  :command:`target_compile_options` command instead.

* The :module:`GenerateExportHeader` module ``add_compiler_export_flags``
  function is now deprecated.  It has been superseded by the
  :prop_tgt:`<LANG>_VISIBILITY_PRESET` and
  :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties.

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

* The version scheme was changed to use only two components for
  the feature level instead of three.  The third component will
  now be used for bug-fix releases or the date of development versions.
  See the :variable:`CMAKE_VERSION` variable documentation for details.

* The default install locations of CMake itself on Windows and
  OS X no longer contain the CMake version number.  This allows
  for easy replacement without re-generating local build trees
  manually.

* Generators for Visual Studio 10 (2010) and later were renamed to
  include the product year like generators for older VS versions:

  - ``Visual Studio 10`` -> :generator:`Visual Studio 10 2010`
  - ``Visual Studio 11`` -> :generator:`Visual Studio 11 2012`
  - ``Visual Studio 12`` -> :generator:`Visual Studio 12 2013`

  This clarifies which generator goes with each Visual Studio
  version.  The old names are recognized for compatibility.

* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for Apple-provided
  Clang is now ``AppleClang``.  It must be distinct from upstream
  Clang because the version numbers differ.
  See policy :policy:`CMP0025`.

* The :variable:`CMAKE_<LANG>_COMPILER_ID` value for ``qcc`` on QNX
  is now ``QCC``.  It must be distinct from ``GNU`` because the
  command-line options differ.  See policy :policy:`CMP0047`.

* On 64-bit OS X the :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` value
  is now correctly detected as ``x86_64`` instead of ``i386``.

* On OS X, CMake learned to enable behavior specified by the
  :prop_tgt:`MACOSX_RPATH` target property by default.  This activates
  use of ``@rpath`` for runtime shared library searches.
  See policy :policy:`CMP0042`.

* The :command:`build_command` command now returns a :manual:`cmake(1)`
  ``--build`` command line instead of a direct invocation of the native
  build tool.  When using ``Visual Studio`` generators, CMake and CTest
  no longer require :variable:`CMAKE_MAKE_PROGRAM` to be located up front.
  Selection of the proper msbuild or devenv tool is now performed as
  late as possible when the solution (``.sln``) file is available so
  it can depend on project content.

* The :manual:`cmake(1)` ``--build`` command now shares its own stdout
  and stderr pipes with the native build tool by default.
  The ``--use-stderr`` option that once activated this is now ignored.

* The ``$<C_COMPILER_ID:...>`` and ``$<CXX_COMPILER_ID:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  used to perform case-insensitive comparison but have now been
  corrected to perform case-sensitive comparison.
  See policy :policy:`CMP0044`.

* The builtin ``edit_cache`` target will no longer select
  :manual:`ccmake(1)` by default when no interactive terminal will
  be available (e.g. with :generator:`Ninja` or an IDE generator).
  Instead :manual:`cmake-gui(1)` will be preferred if available.

* The :module:`ExternalProject` download step learned to
  re-attempt download in certain cases to be more robust to
  temporary network failure.

* The :module:`FeatureSummary` no longer lists transitive
  dependencies since they were not directly requested by the
  current project.

* The ``cmake-mode.el`` major Emacs editing mode has been cleaned
  up and enhanced in several ways.

* Include directories specified in the
  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :ref:`Imported Targets`
  are treated as ``SYSTEM`` includes by default when handled as
  :ref:`usage requirements <Include Directories and Usage Requirements>`.