3.9.rst 14.4 KB
Newer Older
1
2
3
4
5
6
7
8
9
CMake 3.9 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.8 include the following.

10
11
12
13
14
15
16
17
18
New Features
============

Languages
---------

* ``CUDA`` is now supported by the :ref:`Visual Studio Generators`
  for VS 2010 and above.  This complements the existing support by the
  :ref:`Makefile Generators` and the :generator:`Ninja` generator.
19
20
  CUDA 8.0.61 or higher is recommended due to known bugs in the VS
  integration by earlier versions.
21

22
* CMake is now aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and
23
  :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features for
24
25
26
  the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>`: ``Cray``,
  ``PGI``, and ``XL``.

27
28
29
30
31
32
33
34
35
36
37
38
Generators
----------

* :ref:`Visual Studio Generators` for VS 2010 and above learned to support
  the ``ASM_NASM`` language when ``nasm`` is installed.

* The :generator:`Xcode` generator learned to create Xcode schema files.
  This is an experimental feature and can be activated by setting the
  :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value.

Commands
--------
39
40
41
42

* The :command:`add_library` command ``IMPORTED`` option learned to support
  :ref:`Object Libraries`.

43
44
45
* The :command:`find_library` command learned to search ``libx32`` paths
  when the build targets the ``x32`` ABI.  See the
  :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property.
46

47
48
49
* The :command:`include_external_msproject` command learned to use
  the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property
  to map current configurations to the external configurations.
50

51
52
* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to
  specify where to install :ref:`Object Libraries`.
53

54
55
* The :command:`install(EXPORT)` command learned how to export
  :ref:`Object Libraries`.
56

57
58
* The :command:`project` command learned an optional ``DESCRIPTION``
  parameter to set the :variable:`PROJECT_DESCRIPTION` variable.
59

60
61
* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode
  that performs argument separation depending on the host operating system.
62

63
64
Variables
---------
65

66
67
68
69
70
* A :variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` variable was added
  for use when :ref:`Cross Compiling for Android with the NDK` to request
  use of the deprecated headers even when unified headers are available.
  The default is now to use unified headers if available.

71
72
73
* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to
  allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names
  for ``moc`` from the contents of source files.
74

75
76
77
* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to
  allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more
  places than the vicinity of the file including ``ui_foo.h``.
78

79
80
81
* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to
  tell the :command:`find_library` command to search in a ``lib<suffix>``
  directory before each ``lib`` directory that would normally be searched.
82
83
84
85
86
87
88
89
90
91
92

* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to
  initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all
  targets.

* A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold
  the path to the GCC/Clang wrapper of ``ar``.

* A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold
  the path to the GCC/Clang wrapper of ``ranlib``.

93
94
* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK`
  variables were added to use separate sysroots for compiling and linking.
95

96
97
Properties
----------
98

99
100
101
* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set
  a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`,
  and :prop_tgt:`AUTORCC`.
102

103
104
105
* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to
  allow :prop_tgt:`AUTOMOC` to extract additional dependency file names
  for ``moc`` from the contents of source files.
106

107
108
109
* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to
  allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more
  places than the vicinity of the file including ``ui_foo.h``.
110

111
112
113
114
115
* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`,
  :prop_gbl:`AUTOMOC_SOURCE_GROUP` and
  :prop_gbl:`AUTORCC_SOURCE_GROUP` were
  introduced to allow files generated by :prop_tgt:`AUTOMOC` or
  :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`.
116

117
118
119
120
121
* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding
  :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to
  control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property
  value for binaries in the build tree.  This is for macOS ``install_name``
  as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``.
122

123
124
125
* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.ptx`` files
  instead of host object files.
126

127
128
129
* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was
  added to determine whether the current generator is a multi-configuration
  generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`).
130

131
132
133
134
135
* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced
  when enabled.  CMake will add IPO flags unconditionally or produce an error
  if it does not know the flags for the current compiler.  The project is now
  responsible to use the :module:`CheckIPOSupported` module to check for IPO
  support before enabling the target property.  See policy :policy:`CMP0069`.
136

137
138
139
140
141
* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now
  be used in combination with explicit ``.def`` files in order to
  export all symbols from the object files within a target plus
  an explicit list of symbols that the linker finds in dependencies
  (e.g. ``msvcrt.lib``).
142

143
144
Modules
-------
145

146
147
148
* A :module:`CheckIPOSupported` module was added to help projects
  check whether interprocedural optimization (IPO) is supported by
  the current toolchain and CMake version.
149

150
151
152
153
154
* The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro
  now forwards all arguments to the underlying :command:`find_package`
  call.  Existing uses will continue to function as before, but callers can
  now access the full suite of arguments that ``find_package`` accepts.

155
* The :module:`FeatureSummary` module :command:`feature_summary` command now
156
157
158
  accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default
  title for the selected package type.

159
160
161
162
* The :module:`FeatureSummary` module gained a new
  :variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that can be defined
  for each ``<TYPE>`` to replace the type name with the specified string
  whenever the package type is used in an output string by the module.
163

164
165
166
167
168
169
* The :module:`FindDoxygen` module learned to control Doxygen behavior using
  CMake variables and generate documentation via the newly added
  :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``)
  is automatically generated and doxygen is run as part of a custom target.
  Additional components can be specified to find optional tools: ``dot``,
  ``mscgen`` and ``dia``.
170
171
172
173
174
175
176
177
178
179
180
181
182

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

* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp`
  command gained an ``EXPORT_MACRO`` option to specify the name of
  a DLL export markup macro.

* The :module:`FindProtobuf` module now supports usage of static libraries
  for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable.

* The :module:`FindProtobuf` module now provides imported targets
  when the libraries are found.

183
184
185
186
187
188
* A new :module:`GoogleTest` module was added to provide the
  :command:`gtest_add_tests` function independently of the :module:`FindGTest`
  module. The function was also updated to support keyword arguments, with
  functionality expanded to allow a test name prefix and suffix to be
  specified, the dependency on the source files to be optional and the list of
  discovered test cases to be returned to the caller.
189

190
191
CTest
-----
192

193
194
* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option
  to specify custom headers to send during submission.
195

196
197
198
199
200
201
* The :manual:`ctest(1)` executable gained new options which allow the
  developer to disable automatically adding tests to the test set to satisfy
  fixture dependencies. ``-FS`` prevents adding setup tests for fixtures
  matching the provided regular expression, ``-FC`` prevents adding cleanup
  tests for matching fixtures and ``-FA`` prevents adding any test for matching
  fixtures.
202

203
204
* A :prop_test:`DISABLED` test property was added to mark tests that
  are configured but explicitly disabled so they do not run.
205

206
207
CPack
-----
208

209
210
211
* The :module:`CPackArchive` module learned to modify the filename
  per-component.  See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and
  its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`.
212
213
214
215
216
217

* The :module:`CPackComponent` module :command:`cpack_add_component` command
  gained a new ``PLIST <filename>`` option to specify the ``pkgbuild``
  ``--component-plist`` argument when using the
  :module:`productbuild <CPackProductBuild>` generator.

218
219
220
221
222
223
224
225
* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained
  internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION``
  options.

* The :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT`
  variable for finding the QtIFW tool suite installed in a non-standard place.

226
227
228
229
230
* The :module:`CPackProductBuild` module gained a new
  :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to
  specify resources to be copied into the ``Resources``
  directory.

231
232
* The :module:`CPackRPM` module learned to modify the ``debuginfo`` package
  name.  See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable.
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
* The :module:`CPackWIX` module patching system now has the ability to set
  additional attributes.  This can be done by specifying attributes with
  the ``CPackWiXFragment`` XML tag after the ``Id`` attribute.
  See the :variable:`CPACK_WIX_PATCH_FILE` variable.

* The CPack WIX generator implemented a new
  :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows
  using a custom root folder ID instead of the default
  ``ProgramFilesFolder`` / ``ProgramFiles64Folder``.

Other
-----

* Interprocedural optimization (IPO) is now supported for GNU and Clang
  compilers using link time optimization (LTO) flags.  See the
  :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and
  :module:`CheckIPOSupported` module.

* The ``TARGET_OBJECTS``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  is now supported by the :command:`add_custom_command` and
  :command:`file(GENERATE)` commands.

* Two new informational generator expressions to retrieve Apple Bundle
  directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>``
  outputs the full path to the Bundle directory, the other one
  ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the
  ``Contents`` directory of macOS Bundles and App Bundles. For all other
  bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``.
  The new expressions are helpful to query Bundle locations independent of
  the different Bundle types and layouts on macOS and iOS.

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

* An explicit deprecation diagnostic was added for policies ``CMP0036``
  and below.  The :manual:`cmake-policies(7)` manual explains that the
  OLD behaviors of all policies are deprecated and that projects should
  always port to the NEW behaviors as soon as possible.

* The :generator:`Visual Studio 8 2005` generator is now deprecated
  and will be removed in a future version of CMake.
276
277
278
279
280
281

* The :generator:`Visual Studio 7 .NET 2003` generator has been removed.

* The :generator:`Xcode` generator dropped support for Xcode versions
  older than 3.

282
* The :module:`FindDoxygen` module has deprecated several variables.
283
284
285
286
287

* The version of curl bundled with CMake no longer accepts URLs of the form
  ``file://c:/...`` on Windows due to a change in upstream curl 7.52.  Use
  the form ``file:///c:/...`` instead to work on all versions.

288
289
Other Changes
=============
290

291
292
293
* When using :prop_tgt:`AUTOMOC`, CMake now scans for the presence of the
  ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the
  macro's ``FILE`` argument changes.
294

295
296
297
* When :prop_tgt:`AUTOMOC` detects an include statement of the form
  ``#include "moc_<basename>.cpp"`` the search for the respective header file
  now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well.
298

299
300
301
302
* When running tests, CTest learned to treat skipped tests (using the
  :prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new
  :prop_test:`DISABLED` property. Due to this change, CTest will not indicate
  failure when all tests are either skipped or pass.
303

304
305
306
307
308
309
310
311
312
* The :generator:`Ninja` generator has loosened the dependencies of object
  compilation.  Object compilation now depends only on custom targets
  and custom commands associated with libraries on which the object's target
  depends and no longer depends on the libraries themselves.  Source files
  in dependent targets may now compile without waiting for their targets'
  dependencies to link.

* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH`
  no longer affect the ``install_name`` field.  See policy :policy:`CMP0068`.
313
314
315
316
317

* The :generator:`Visual Studio 14 2015` generator has been taught about
  a change to the ``v140`` toolset made by a VS 2015 update.  VS changed
  the set of values it understands for the ``GenerateDebugInformation``
  linker setting that produces the ``-DEBUG`` linker flag variants.
318
319
320
321
322
323
324
325
326
327
328
329
330

Updates
=======

Changes made since CMake 3.9.0 include the following.

3.9.1
-----

* The ``find_`` command ``PACKAGE_ROOT`` search path group added by
  CMake 3.9.0 has been removed for the 3.9 series due to regressions
  caused by new use of ``<PackageName>_ROOT`` variables.  The behavior
  may be re-introduced in the future in a more-compatible way.
331
332
333
334
335
336
337

3.9.2
-----

* On macOS, the default application bundle ``Info.plist`` file no longer
  enables Hi-DPI support as it did in 3.9.0 and 3.9.1.  The change had
  to be reverted because it broke iOS applications.
338
339
340
341
342

* The Xcode generator no longer adds "outputPaths" to custom script
  build phases as it did in 3.9.0 and 3.9.1.  This was added in an
  attempt to support Xcode 9's new build system, but broke incremental
  rebuilds for both the old and new Xcode build systems.