1CMake 3.9 Release Notes
2***********************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.8 include the following.
9
10New Features
11============
12
13Languages
14---------
15
16* ``CUDA`` is now supported by the :ref:`Visual Studio Generators`
17  for VS 2010 and above.  This complements the existing support by the
18  :ref:`Makefile Generators` and the :generator:`Ninja` generator.
19  CUDA 8.0.61 or higher is recommended due to known bugs in the VS
20  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  the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>`: ``Cray``,
25  ``PGI``, and ``XL``.
26
27Generators
28----------
29
30* :ref:`Visual Studio Generators` for VS 2010 and above learned to support
31  the ``ASM_NASM`` language when ``nasm`` is installed.
32
33* The :generator:`Xcode` generator learned to create Xcode schema files.
34  This is an experimental feature and can be activated by setting the
35  :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value.
36
37Commands
38--------
39
40* The :command:`add_library` command ``IMPORTED`` option learned to support
41  :ref:`Object Libraries`.
42
43* The :command:`find_library` command learned to search ``libx32`` paths
44  when the build targets the ``x32`` ABI.  See the
45  :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property.
46
47* The :command:`include_external_msproject` command learned to use
48  the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property
49  to map current configurations to the external configurations.
50
51* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to
52  specify where to install :ref:`Object Libraries`.
53
54* The :command:`install(EXPORT)` command learned how to export
55  :ref:`Object Libraries`.
56
57* The :command:`project` command learned an optional ``DESCRIPTION``
58  parameter to set the :variable:`PROJECT_DESCRIPTION` variable.
59
60* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode
61  that performs argument separation depending on the host operating system.
62
63Variables
64---------
65
66* A :variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` variable was added
67  for use when :ref:`Cross Compiling for Android with the NDK` to request
68  use of the deprecated headers even when unified headers are available.
69  The default is now to use unified headers if available.
70
71* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to
72  allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names
73  for ``moc`` from the contents of source files.
74
75* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to
76  allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more
77  places than the vicinity of the file including ``ui_foo.h``.
78
79* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to
80  tell the :command:`find_library` command to search in a ``lib<suffix>``
81  directory before each ``lib`` directory that would normally be searched.
82
83* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to
84  initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all
85  targets.
86
87* A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold
88  the path to the GCC/Clang wrapper of ``ar``.
89
90* A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold
91  the path to the GCC/Clang wrapper of ``ranlib``.
92
93* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK`
94  variables were added to use separate sysroots for compiling and linking.
95
96Properties
97----------
98
99* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set
100  a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`,
101  and :prop_tgt:`AUTORCC`.
102
103* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to
104  allow :prop_tgt:`AUTOMOC` to extract additional dependency file names
105  for ``moc`` from the contents of source files.
106
107* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to
108  allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more
109  places than the vicinity of the file including ``ui_foo.h``.
110
111* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`,
112  :prop_gbl:`AUTOMOC_SOURCE_GROUP` and
113  :prop_gbl:`AUTORCC_SOURCE_GROUP` were
114  introduced to allow files generated by :prop_tgt:`AUTOMOC` or
115  :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`.
116
117* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding
118  :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to
119  control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property
120  value for binaries in the build tree.  This is for macOS ``install_name``
121  as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``.
122
123* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to
124  :ref:`Object Libraries` to support compiling to ``.ptx`` files
125  instead of host object files.
126
127* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was
128  added to determine whether the current generator is a multi-configuration
129  generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`).
130
131* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced
132  when enabled.  CMake will add IPO flags unconditionally or produce an error
133  if it does not know the flags for the current compiler.  The project is now
134  responsible to use the :module:`CheckIPOSupported` module to check for IPO
135  support before enabling the target property.  See policy :policy:`CMP0069`.
136
137* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now
138  be used in combination with explicit ``.def`` files in order to
139  export all symbols from the object files within a target plus
140  an explicit list of symbols that the linker finds in dependencies
141  (e.g. ``msvcrt.lib``).
142
143Modules
144-------
145
146* A :module:`CheckIPOSupported` module was added to help projects
147  check whether interprocedural optimization (IPO) is supported by
148  the current toolchain and CMake version.
149
150* The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro
151  now forwards all arguments to the underlying :command:`find_package`
152  call.  Existing uses will continue to function as before, but callers can
153  now access the full suite of arguments that :command:`find_package` accepts.
154
155* The :module:`FeatureSummary` module :command:`feature_summary` command now
156  accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default
157  title for the selected package type.
158
159* The :module:`FeatureSummary` module gained a new
160  :variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that can be defined
161  for each ``<TYPE>`` to replace the type name with the specified string
162  whenever the package type is used in an output string by the module.
163
164* The :module:`FindDoxygen` module learned to control Doxygen behavior using
165  CMake variables and generate documentation via the newly added
166  :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``)
167  is automatically generated and doxygen is run as part of a custom target.
168  Additional components can be specified to find optional tools: ``dot``,
169  ``mscgen`` and ``dia``.
170
171* The :module:`FindMPI` module now provides imported targets.
172
173* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp`
174  command gained an ``EXPORT_MACRO`` option to specify the name of
175  a DLL export markup macro.
176
177* The :module:`FindProtobuf` module now supports usage of static libraries
178  for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable.
179
180* The :module:`FindProtobuf` module now provides imported targets
181  when the libraries are found.
182
183* A new :module:`GoogleTest` module was added to provide the
184  :command:`gtest_add_tests` function independently of the :module:`FindGTest`
185  module. The function was also updated to support keyword arguments, with
186  functionality expanded to allow a test name prefix and suffix to be
187  specified, the dependency on the source files to be optional and the list of
188  discovered test cases to be returned to the caller.
189
190CTest
191-----
192
193* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option
194  to specify custom headers to send during submission.
195
196* The :manual:`ctest(1)` executable gained new options which allow the
197  developer to disable automatically adding tests to the test set to satisfy
198  fixture dependencies. ``-FS`` prevents adding setup tests for fixtures
199  matching the provided regular expression, ``-FC`` prevents adding cleanup
200  tests for matching fixtures and ``-FA`` prevents adding any test for matching
201  fixtures.
202
203* A :prop_test:`DISABLED` test property was added to mark tests that
204  are configured but explicitly disabled so they do not run.
205
206CPack
207-----
208
209* The :cpack_gen:`CPack Archive Generator` learned to modify the filename
210  per-component.  See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and
211  its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`.
212
213* The :module:`CPackComponent` module :command:`cpack_add_component` command
214  gained a new ``PLIST <filename>`` option to specify the ``pkgbuild``
215  ``--component-plist`` argument when using the
216  :module:`productbuild <CPackProductBuild>` generator.
217
218* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
219  :command:`cpack_ifw_configure_component_group` commands gained
220  internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION``
221  options.
222
223* The :cpack_gen:`CPack IFW Generator` learned the new hint
224  :variable:`CPACK_IFW_ROOT` variable for finding the QtIFW tool suite
225  installed in a non-standard place.
226
227* The :cpack_gen:`CPack productbuild Generator` gained a new
228  :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to
229  specify resources to be copied into the ``Resources``
230  directory.
231
232* The :cpack_gen:`CPack RPM Generator` learned to modify the ``debuginfo``
233  package name.  See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable.
234
235* The :cpack_gen:`CPack WIX Generator` patching system now has the
236  ability to set additional attributes.  This can be done by specifying
237  attributes with the ``CPackWiXFragment`` XML tag after the ``Id`` attribute.
238  See the :variable:`CPACK_WIX_PATCH_FILE` variable.
239
240* The :cpack_gen:`CPack WIX Generator` implemented a new
241  :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows
242  using a custom root folder ID instead of the default
243  ``ProgramFilesFolder`` / ``ProgramFiles64Folder``.
244
245Other
246-----
247
248* Interprocedural optimization (IPO) is now supported for GNU and Clang
249  compilers using link time optimization (LTO) flags.  See the
250  :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and
251  :module:`CheckIPOSupported` module.
252
253* The ``TARGET_OBJECTS``
254  :manual:`generator expression <cmake-generator-expressions(7)>`
255  is now supported by the :command:`add_custom_command` and
256  :command:`file(GENERATE)` commands.
257
258* Two new informational generator expressions to retrieve Apple Bundle
259  directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>``
260  outputs the full path to the Bundle directory, the other one
261  ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the
262  ``Contents`` directory of macOS Bundles and App Bundles. For all other
263  bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``.
264  The new expressions are helpful to query Bundle locations independent of
265  the different Bundle types and layouts on macOS and iOS.
266
267Deprecated and Removed Features
268===============================
269
270* An explicit deprecation diagnostic was added for policies ``CMP0036``
271  and below.  The :manual:`cmake-policies(7)` manual explains that the
272  OLD behaviors of all policies are deprecated and that projects should
273  always port to the NEW behaviors as soon as possible.
274
275* The :generator:`Visual Studio 8 2005` generator is now deprecated
276  and will be removed in a future version of CMake.
277
278* The :generator:`Visual Studio 7 .NET 2003` generator has been removed.
279
280* The :generator:`Xcode` generator dropped support for Xcode versions
281  older than 3.
282
283* The :module:`FindDoxygen` module has deprecated several variables.
284
285* The version of curl bundled with CMake no longer accepts URLs of the form
286  ``file://c:/...`` on Windows due to a change in upstream curl 7.52.  Use
287  the form ``file:///c:/...`` instead to work on all versions.
288
289Other Changes
290=============
291
292* When using :prop_tgt:`AUTOMOC`, CMake now scans for the presence of the
293  ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the
294  macro's ``FILE`` argument changes.
295
296* When :prop_tgt:`AUTOMOC` detects an include statement of the form
297  ``#include "moc_<basename>.cpp"`` the search for the respective header file
298  now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well.
299
300* When running tests, CTest learned to treat skipped tests (using the
301  :prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new
302  :prop_test:`DISABLED` property. Due to this change, CTest will not indicate
303  failure when all tests are either skipped or pass.
304
305* The :generator:`Ninja` generator has loosened the dependencies of object
306  compilation.  Object compilation now depends only on custom targets
307  and custom commands associated with libraries on which the object's target
308  depends and no longer depends on the libraries themselves.  Source files
309  in dependent targets may now compile without waiting for their targets'
310  dependencies to link.
311
312* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH`
313  no longer affect the ``install_name`` field.  See policy :policy:`CMP0068`.
314
315* The :generator:`Visual Studio 14 2015` generator has been taught about
316  a change to the ``v140`` toolset made by a VS 2015 update.  VS changed
317  the set of values it understands for the ``GenerateDebugInformation``
318  linker setting that produces the ``-DEBUG`` linker flag variants.
319
320Updates
321=======
322
323Changes made since CMake 3.9.0 include the following.
324
3253.9.1
326-----
327
328* The ``find_`` command ``PACKAGE_ROOT`` search path group added by
329  CMake 3.9.0 has been removed for the 3.9 series due to regressions
330  caused by new use of ``<PackageName>_ROOT`` variables.  The behavior
331  may be re-introduced in the future in a more-compatible way.
332
3333.9.2
334-----
335
336* On macOS, the default application bundle ``Info.plist`` file no longer
337  enables Hi-DPI support as it did in 3.9.0 and 3.9.1.  The change had
338  to be reverted because it broke iOS applications.
339
340* The Xcode generator no longer adds "outputPaths" to custom script
341  build phases as it did in 3.9.0 and 3.9.1.  This was added in an
342  attempt to support Xcode 9's new build system, but broke incremental
343  rebuilds for both the old and new Xcode build systems.
344