3.9.rst 12.6 KB
Newer Older
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
CMake 3.9 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.8 include the following.

* The :command:`add_custom_command` command learned to evaluate the
  ``TARGET_OBJECTS``
  :manual:`generator expression <cmake-generator-expressions(7)>`.

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

* The new target property :prop_tgt:`AUTOGEN_BUILD_DIR` was introduced which
  allows to set a custom output directory for
  :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC`.

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

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

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

* When :prop_tgt:`AUTOMOC` detects an include statement of the form
  ``#include "moc_<basename>.cpp"`` the respective header file is searched
  for in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well.

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

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

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

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

  Those new expressions are helpful to query Bundle locations independent of
  the different Bundle types and layouts on macOS and iOS.

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

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

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

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

* The :module:`CPackArchive` module learned to modify filename per component.
  See :variable:`CPACK_ARCHIVE_FILE_NAME` variable and its per component
  version.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained a
  internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION`` options
  to more specific configuration.

* 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.
* The :module:`CPackIFW` module tries to find and use QtIFW tools of the `3.0`
  and `3.1` versions.

* The :module:`CPackRPM` module learned to modify debuginfo package name.
  See :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable.

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

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

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

* ``CUDA`` is now supported by the :ref:`Visual Studio Generators`
  for VS 2010 and above.

* 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
  port to the NEW behaviors.

* 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.
  A number of doxygen-related variables have been deprecated. Additional
  components can be specified to find optional tools: ``dot``, ``mscgen``
  and ``dia``.

* The :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.ptx`` files
  instead of host object files.

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

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

* The :command:`feature_summary` command in the :module:`FeatureSummary` module
  accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default
  title for the selected package type.

* The global property :variable:`FeatureSummary_<TYPE>_DESCRIPTION` 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:`FeatureSummary` module.

* The :command:`file(GENERATE)` subcommand learned to evaluate the
  ``TARGET_OBJECTS``
  :manual:`generator expression <cmake-generator-expressions(7)>`.

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

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

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

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

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

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

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

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

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

* On macOS the default application bundle ``Info.plist`` file now enables
  Hi-DPI support.

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

* The :generator:`Ninja` generator has loosened dependencies on object
  compilation to depend on the custom targets and commands of dependent
  libraries instead of the libraries themselves. This helps projects with deep
  dependency graphs to be blocked only on their link steps at the deeper
  levels rather than also blocking object compilation on dependent link steps.

* All ``find_`` commands now have a `PACKAGE_ROOT` search path group that is
  first in the search heuristics.  If the ``find_`` command is called from
  inside a find module, then the CMake and environment variables
  ``<PackageName>_ROOT`` are used as prefixes and are the first set of paths
  that are searched.

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

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

* The :command:`project` command learned an optional ``DESCRIPTION`` parameter.
  See :command:`project` command and :variable:`PROJECT_DESCRIPTION` variable.

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

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

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

* A ``NATIVE_COMMAND`` mode was added to :command:`separate_arguments`
  performing argument separation depening on the host operating system.

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

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

* The :generator:`Visual Studio 8 2005` generator is now deprecated
  and will be removed in a future version of CMake.

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

* The patching system within the :module:`CPackWIX` module now allows the
  ability to set additional attributes.  This can be done by specifying
  addional 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``.

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