summaryrefslogtreecommitdiffstats
path: root/Help/release/3.8.rst
blob: 1efafac84c1b735b7492c36a6c158646777aa722 (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
CMake 3.8 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.7 include the following.

* A :variable:`CMAKE_BUILD_RPATH` variable and corresponding
  :prop_tgt:`BUILD_RPATH` target property were added to support custom
  ``RPATH`` locations to be added to binaries in the build tree.

* A :prop_tgt:`<LANG>_CPPLINT` target property and supporting
  :variable:`CMAKE_<LANG>_CPPLINT` variable were introduced to tell
  the :ref:`Makefile Generators` and the :generator:`Ninja` generator to
  run the ``cpplint`` style checker along with the compiler for ``C`` and
  ``CXX`` languages.

* CMake functionality using cryptographic hashes now supports SHA-3 algorithms.

* The :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property learned
  to interpret empty list elements as referring to the configuration-less
  imported location specified by :prop_tgt:`IMPORTED_LOCATION`.

* If a command specified by the :prop_tgt:`<LANG>_CLANG_TIDY` target property
  returns non-zero at build time this is now treated as an error instead of
  silently ignored.

* The ``CDASH_UPLOAD`` signature of :command:`ctest_submit` was taught to honor
  the ``RETRY_COUNT``, ``RETRY_DELAY``, and ``QUIET`` options.

* The :generator:`CodeBlocks` now can generate with
  :generator:`NMake Makefiles JOM`.

* The :generator:`CodeLite` extra generator gained a new option
  set by the :variable:`CMAKE_CODELITE_USE_TARGETS` variable to
  change the generated project to have target-centric organization.
  The "build", "rebuild", and "clean" operations within CodeLite
  then work on a selected target rather than the whole workspace.
  (Note that the :generator:`Ninja` clean operation on a target
  includes its dependencies, though.)

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  now offers meta-features that request compiler modes for specific language
  standard levels.  See :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and
  :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES`.

* The :command:`cpack_ifw_configure_file` command was added
  (in :module:`CPackIFWConfigureFile`) to configure file templates prepared
  in QtIFW/SDK/Creator style.

* The :module:`CPackIFWConfigureFile` module was added to define
  :command:`cpack_ifw_configure_file` command.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained a new
  ``DEFAULT``, ``VIRTUAL``, ``FORCED_INSTALLATION``, ``REQUIRES_ADMIN_RIGHTS``,
  ``DISPLAY_NAME``, ``UPDATE_TEXT``, ``DESCRIPTION``, ``RELEASE_DATE``,
  ``AUTO_DEPEND_ON`` and ``TRANSLATIONS`` options to more specific
  configuration.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component`
  command gained a new ``DEPENDENCIES`` alias for ``DEPENDS`` option.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component_group`
  command gained a new ``DEPENDS`` option. The ``DEPENDENCIES`` alias also
  added.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands ``PRIORITY``
  option now is deprecated and will be removed in a future version of CMake.
  Please use new ``SORTING_PRIORITY`` option instead.

* The :module:`CPackIFW` module gained new :variable:`CPACK_IFW_PACKAGE_WATERMARK`, :variable:`CPACK_IFW_PACKAGE_BANNER`,
  :variable:`CPACK_IFW_PACKAGE_BACKGROUND`, :variable:`CPACK_IFW_PACKAGE_WIZARD_STYLE`, :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH`,
  :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT` and :variable:`CPACK_IFW_PACKAGE_TITLE_COLOR`
  variables to customize a QtIFW installer look.

* The :module:`CPackProductBuild` module gained options to sign packages.
  See the variables :variable:`CPACK_PRODUCTBUILD_IDENTITY_NAME`,
  :variable:`CPACK_PRODUCTBUILD_KEYCHAIN_PATH`,
  :variable:`CPACK_PKGBUILD_IDENTITY_NAME`, and
  :variable:`CPACK_PKGBUILD_KEYCHAIN_PATH`.

* The :module:`CPackRPM` module learned to omit
  tags that are not supported by provided
  rpmbuild tool. If unsupported tags are set
  they are ignored and a developer warning is
  printed out.

* The :module:`CPackRPM` module learned to generate main component package
  which forces generation of a rpm for defined component without component
  suffix in filename and package name.
  See :variable:`CPACK_RPM_MAIN_COMPONENT` variable.

* The :module:`CPackRPM` module learned to generate a single debuginfo package
  on demand even if components packagin is used.
  See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable.

* The :module:`CPackRPM` module learned to support
  multiple directives per file when using
  :variable:`CPACK_RPM_USER_FILELIST` variable.

* The :command:`ctest_memcheck` command gained a ``DEFECT_COUNT <var>``
  option to capture the number of memory defects detected.

* The :command:`ctest_memcheck` command learned to support ``LeakSanitizer``
  independently from ``AddressSanitizer``.

* The :command:`ctest_memcheck` command no longer automatically adds
  ``leak_check=1`` to the options used by ``AddressSanitizer``. The default
  behavior of ``AddressSanitizer`` is to run `LeakSanitizer` to check leaks
  unless ``leak_check=0``.

* The :command:`ctest_memcheck` command learned to read the location of
  suppressions files for sanitizers from the
  :variable:`CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` variable.

* The :command:`ctest_memcheck` command was fixed to correctly append extra
  sanitizer options read from the
  :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable to the environment
  variables used internally by the sanitizers.

* CMake learned to support CUDA as a first-class language.
  It is supported by the :ref:`Makefile Generators` and the
  :generator:`Ninja` generator.

* The :command:`execute_process` command gained an ``ENCODING`` option to
  specify on Windows which encoding is used for output from child process.

* The commands :command:`add_custom_command` and :command:`add_custom_target`
  learned the option ``COMMAND_EXPAND_LISTS`` which causes lists in the
  ``COMMAND`` argument to be expanded, including lists created by generator
  expressions.

* The :module:`ExternalData` module learned to support multiple
  content links for one data file using different hashes, e.g.
  ``img.png.sha256`` and ``img.png.sha1``.  This allows objects
  to be fetched from sources indexed by different hash algorithms.

* The :module:`ExternalProject` module gained the ``GIT_PROGRESS`` option to
  force Git to show progress when cloning repositories.

* The :module:`ExternalProject` module gained a ``GIT_CONFIG`` option
  to pass ``--config`` options to Git when cloning repositories.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of C++ 17.  No specific features are yet enumerated besides
  the ``cxx_std_17`` meta-feature.

* The :command:`set_package_info`, :command:`set_feature_info`,
  :command:`print_enabled_features` and :command:`print_disabled_features`
  commands from the the :module:`FeatureSummary` module are now deprecated.

* The :command:`set_package_properties` command no longer forces the package
  type to ``OPTIONAL`` when the type is not explicitly set.

* The :command:`feature_summary` command in the :module:`FeatureSummary` module
  accepts the new ``QUIET_ON_EMPTY`` option that will suppresses the output when
  the list of packages that belong to the selected category is empty.

* The :command:`add_feature_info` in the :module:`FeatureSummary` module learned
  to accept lists of dependencies for deciding whether a feature is enabled or
  not.

* The package types accepted by the the :module:`FeatureSummary` module can now
  be tweaked by changing the :variable:`FeatureSummary_PKG_TYPES`,
  :variable:`FeatureSummary_REQUIRED_PKG_TYPES` and
  :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global properties.

* The :module:`FindOpenGL` module now provides imported targets
  ``OpenGL::GL`` and ``OpenGL::GLU`` when the libraries are found.

* A new minimal platform file for Fuchsia was added.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of the availability of C99 in gcc since version 3.4.

* A new logical generator expression for immediate-if was added:
  ``$<IF:cond,true-value,false-value>``. It takes three arguments: One
  condition, a true-value, and a false-value. Resolves to the true-value if the
  condition is ``1``, and resolves to the false-value if the condition is ``0``.

* :ref:`Imported <Imported Targets>` :ref:`Interface Libraries` learned new
  :prop_tgt:`IMPORTED_LIBNAME` and :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>`
  target properties to specify a link library name since interface libraries
  do not build their own library files.

* The :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property is now supported
  on :ref:`Imported <Imported Targets>` :ref:`Interface Libraries`.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by Intel C++ compilers versions 12.1
  through 17.0 on UNIX and Windows platforms.

* The target property :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES` has
  been added.  It is read-only and could be used to retrieve
  dependencies that have been added with :command:`add_dependencies`.

* The :command:`math(EXPR)` command gained support for unary
  ``+`` and ``-`` expressions.

* Calls to the :module:`FindPkgConfig` module :command:`pkg_check_modules`
  command following a successful call learned to re-evaluate the cached values
  for a given prefix after changes to the parameters to the command for that
  prefix.

* When using AUTOMOC or AUTOUIC, generated
  ``moc_*``, ``*.moc`` and ``ui_*`` are placed in the
  ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which
  is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
  It is therefore not necessary anymore to have
  :variable:`CMAKE_CURRENT_BINARY_DIR` in the target's
  :prop_tgt:`INCLUDE_DIRECTORIES`.

* The source file properties
  :prop_sf:`SKIP_AUTOMOC`,
  :prop_sf:`SKIP_AUTOUIC`,
  :prop_sf:`SKIP_AUTORCC` and
  :prop_sf:`SKIP_AUTOGEN`
  allow to exclude files from
  :prop_tgt:`AUTOMOC`,
  :prop_tgt:`AUTOUIC` and
  :prop_tgt:`AUTORCC` processing.

* The :command:`string(TIMESTAMP)` will now honor the ``SOURCE_DATE_EPOCH``
  environment variable and use its value instead of the current time.

* The :command:`source_group` command gained ``TREE`` and ``PREFIX``
  options to add groups following source tree directory structure.

* The :prop_sf:`COMPILE_FLAGS` source file property learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :generator:`Sublime Text 2` extra generator learned to place
  environment variables in the generated ``.sublime-project``.
  See the :variable:`CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS` variable.

* The :generator:`Sublime Text 2` extra generator no longer excludes the
  build tree from the ``.sublime-project`` when it is inside the source tree.
  The :variable:`CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable
  was added to control the behavior explicitly.

* The :prop_tgt:`FRAMEWORK` property could now also be applied to
  static libraries on Apple targets.  It will result in a proper
  Framework but with a static library inside.

* The :generator:`Sublime Text 2` generator no longer runs the native
  build command (e.g. ``ninja`` or ``make``) with verbose build output
  enabled.

* The :module:`UseSWIG` module gained a ``swig_add_library`` command
  to give more flexibility over the old ``swig_add_module`` command.

* The :module:`UseSWIG` module ``swig_add_module`` command is now
  deprecated in favor of ``swig_add_library``.

* The :command:`string(TIMESTAMP)` command learned to treat ``%%``
  as a way to encode plain ``%``.

* The :command:`try_compile` command source file signature now
  honors the :variable:`CMAKE_WARN_DEPRECATED` variable value
  in the generated test project.

* The :command:`try_compile` command source file signature gained new options
  to specify the language standard to use in the generated test project.

* The :command:`try_compile` command source file signature now honors
  language standard variables like :variable:`CMAKE_CXX_STANDARD`.
  See policy :policy:`CMP0067`.

* The :module:`UseSWIG` module ``swig_add_source_to_module`` command
  learned a new ``SWIG_OUTFILE_DIR`` option to control the output
  file location (``swig -o``).

* The :ref:`Visual Studio Generators` for VS 2010 and above
  learned some more source file properties:

  - :prop_sf:`VS_RESOURCE_GENERATOR` (C# only): allows setting the resource
    generator
  - :prop_sf:`VS_COPY_TO_OUT_DIR`: parameter to set if file should be copied
    to output directory (values: ``Never``, ``Always``, ``PreserveNewest``)
  - :prop_sf:`VS_INCLUDE_IN_VSIX`: boolean property to include file include
    Visual Studio extension package

* The :ref:`Visual Studio Generators` for VS 2010 and above
  learned to support the C# language. C# assemblies and
  programs can be added just like common C++ targets using
  the :command:`add_library` and :command:`add_executable`
  commands. Referencing between several C# targets in the same
  source tree is done by :command:`target_link_libraries` like
  for C++. Referencing to system or 3rd party assemblies is
  done by the target properties :prop_tgt:`VS_DOTNET_REFERENCE_<refname>`
  and :prop_tgt:`VS_DOTNET_REFERENCES`.

* C# as a language can be enabled using :command:`enable_language`
  or :command:`project` with ``CSharp``. It is not enabled by
  default.

* Flag variables, target properties and other configuration
  that specifically targets C# contains ``CSharp`` as a part of
  their names.

* More finetuning of C# targets can be done using target and source
  file properties. Specifically the Visual Studio related target
  properties (``VS_*``) are worth a look (for setting toolset
  versions, root namespaces, assembly icons, ...).

* **Auto-"linking"** in .csproj files: In C#/.NET development with
  Visual Studio there is a number of visual editors used which
  generate code. Both the generated files and the ones edited
  with the UI are connected in the ``.csproj`` file using
  ``<DependentUpon>`` tags. If CMake finds within a C# project
  any source file with extension ``.Designer.cs`` or ``.xaml.cs``,
  it checks sibling files with extension ``.xaml``, ``.settings``,
  ``.resx`` or ``.cs`` and establishes the dependency connection.

* The :ref:`Visual Studio Generators` for VS 2010 and above can
  now be fine tuned using custom msbuild .props files.
  :prop_tgt:`VS_USER_PROPS` can be
  used to change the default path of the user .props file from
  ``$(UserRootDir)\\Microsoft.Cpp.$(Platform).user.props`` to
  an arbitrary filename.

* For the :ref:`Visual Studio Generators` for VS 2010 and above
  the working directory for debugging can be set using a new
  :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target property.

* The :ref:`Visual Studio Generators` for VS 2010 and above now support
  adding the PACKAGE target to the targets which are built by default.
  The behavior is similar to :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD`
  and can be toggled using :variable:`CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD`.

* The :ref:`Visual Studio Generators` for VS 2010 and above can
  now handle .NET references with hintpaths. For this the new
  target property group :prop_tgt:`VS_DOTNET_REFERENCE_<refname>`
  was introduced. The ``<refname>`` part of the property name will
  be the name of the reference, the value will be the actual
  path to the assembly.

* Copying of referenced assemblies to the output directory can
  now be disabled using the target property
  :prop_tgt:`VS_DOTNET_REFERENCES_COPY_LOCAL`.

* The :ref:`Visual Studio Generators` for VS 2010 and above now place
  per-source file flags after target-wide flags when they are classified
  as raw flags with no project file setting (``AdditionalOptions``).
  This behavior is more consistent with the ordering of flags produced
  by other generators, and allows flags on more-specific properties
  (per-source) to override those on more general ones (per-target).

* The :ref:`Visual Studio Generators` for VS 2013 and above learned to
  support a ``host=x64`` option in the :variable:`CMAKE_GENERATOR_TOOLSET`
  value (e.g.  via the :manual:`cmake(1)` ``-T`` option) to request use
  of a VS 64-bit toolchain on 64-bit hosts.

* :ref:`Visual Studio Generators` learned to treat files passed to
  :command:`target_link_libraries` whose names end in ``.targets``
  as MSBuild targets files to be imported into generated project files.

* The :module:`WriteCompilerDetectionHeader` module gained the
  ``ALLOW_UNKNOWN_COMPILERS`` and ``ALLOW_UNKNOWN_COMPILER_VERSIONS`` options
  that allow creation of headers that will work also with unknown or old
  compilers by simply assuming they do not support any of the requested
  features.

* The precompiled Windows binary MSI package provided on ``cmake.org`` now
  records the installation directory in the Windows Registry under the key
  ``HKLM\Software\Kitware\CMake`` with a value named ``InstallDir``.

* The Xcode generator can now control emission of the
  ``EFFECTIVE_PLATFORM_NAME`` variable through the
  :prop_gbl:`XCODE_EMIT_EFFECTIVE_PLATFORM_NAME` global property.
  This is useful when building with multiple SDKs like macosx and
  iphoneos in parallel.

* New :prop_tgt:`XCODE_PRODUCT_TYPE` and :prop_tgt:`XCODE_EXPLICIT_FILE_TYPE`
  target properties were created to tell the :generator:`Xcode` generator
  to use custom values of the corresponding attributes for a target in the
  generated Xcode project.