1CMake 3.13 Release Notes
2************************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.12 include the following.
9
10New Features
11============
12
13Generators
14----------
15
16* The :ref:`Visual Studio Generators` for VS 2010 and above learned to
17  support the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property
18  and supporting :module:`CheckIPOSupported` module.
19
20* The :generator:`Xcode` generator learned to configure more Xcode Scheme
21  fields.  See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable.
22
23* The :generator:`Green Hills MULTI` generator has been updated:
24
25  - Added support for architecture selection through
26    :variable:`CMAKE_GENERATOR_PLATFORM`:
27    e.g. ``arm``, ``ppc``, and ``86``.
28
29  - Added support for toolset selection through
30    :variable:`CMAKE_GENERATOR_TOOLSET`,
31    e.g. ``comp_201205``, ``comp_201510``, ``comp_201722_beta``.
32
33  - Added support for platform selection through ``GHS_TARGET_PLATFORM``,
34    e.g. ``integrity``, ``linux``, ``standalone``, etc.
35
36  - No longer checks that ``arm`` based compilers are installed but ensures
37    that the correct ``gbuild.exe`` exists.
38
39  - No longer hard-codes ARM files, BSP, toolset, or OS locations.
40
41Command-Line
42------------
43
44* The :manual:`cmake(1)` command gained the ``-S <source_dir>``
45  command line option to specify the location of the source directory.
46  This option can be used independently of ``-B``.
47
48* The :manual:`cmake(1)` command gained the ``-B <build_dir>``
49  command line option to specify the location of the build directory.
50  This option can be used independently of ``-S``.
51
52* The :manual:`cmake(1)` ``-E create_symlink`` command can now be used
53  on Windows.
54
55Commands
56--------
57
58* The :command:`add_custom_command` and :command:`add_custom_target` commands
59  learned to support generator expressions in ``WORKING_DIRECTORY`` options.
60
61* The :command:`add_link_options` command was created to add link
62  options in the current directory.
63
64* The :command:`install(TARGETS)` command learned to install targets
65  created outside the current directory.
66
67* The :command:`link_directories` command gained options to control
68  insertion position.
69
70* The :command:`list(SORT)` command gained options to control the
71  comparison operation used to order the entries.
72
73* The :command:`math` command gained options for hexadecimal.
74
75* The :command:`target_link_directories` command was created to
76  specify link directories for targets and their dependents.
77
78* The :command:`target_link_options` command was created to
79  specify link options for targets and their dependents.
80
81* The :command:`target_link_libraries` command may now be called
82  to modify targets created outside the current directory.
83  See policy :policy:`CMP0079`.
84
85Variables
86---------
87
88* A :variable:`CMAKE_AUTOGEN_VERBOSE` variable was added to optionally
89  increase the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`
90  and :prop_tgt:`AUTORCC` from within CMake project code.
91
92* A :variable:`CMAKE_VS_GLOBALS` variable was added to initialize
93  :prop_tgt:`VS_GLOBAL_<variable>` target properties on targets as
94  they are created.
95
96Properties
97----------
98
99* The :prop_tgt:`DEPLOYMENT_ADDITIONAL_FILES` target property was
100  added to tell the :generator:`Visual Studio 9 2008` generator
101  to specify additional files for deployment to WinCE devices
102  for remote debugging.
103
104* The :prop_tgt:`INTERFACE_LINK_DEPENDS` target property was created
105  to specify transitive link dependencies on files.
106
107* The :prop_tgt:`LINK_DEPENDS` target property learned to support
108  :manual:`generator expressions <cmake-generator-expressions(7)>`.
109
110* :prop_tgt:`LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
111  target properties were added to collect link directories for a target
112  and its dependents.  Use the :command:`target_link_directories` command
113  to set them.
114
115* :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
116  properties were added to collect link options for a target and its
117  dependents.  Use the :command:`target_link_options` command to set them.
118
119* A :prop_dir:`LINK_OPTIONS` directory property was added to collect
120  link options for targets created under the current directory.
121  Use the :command:`add_link_options` command to set it.
122
123* A :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property was created
124  to specify archiver options to use when creating static libraries.
125
126* A :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS` target property was created to
127  set the debugging command line arguments with
128  :ref:`Visual Studio Generators` for VS 2010 and above.
129
130* A :prop_tgt:`VS_DEBUGGER_ENVIRONMENT` target property was created to
131  set the debugging environment with
132  :ref:`Visual Studio Generators` for VS 2010 and above.
133
134* The :prop_tgt:`VS_DEBUGGER_COMMAND` and
135  :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target properties
136  now support generator expressions.
137
138Modules
139-------
140
141* The :module:`FindBoost` module gained a ``Boost_ARCHITECTURE`` option
142  to specify a Boost architecture-specific library filename fragment.
143
144* The :module:`FindCURL` module learned to find debug and release variants
145  separately.
146
147* The :module:`FindMatlab` module gained new components ``ENGINE_LIBRARY`` and
148  ``DATAARRAY_LIBRARY`` to request finding the Matlab C++ Engine and DataArray
149  libraries respectively.
150
151* The :module:`FindMatlab` module now explicitly exports mexFunction in Visual
152  Studio.
153
154* The :module:`FindMatlab` module gained a new ``MCC_COMPILER``
155  component to request finding the Matlab Compiler add-on.
156
157* The :module:`FindPkgConfig` module gained an option to create imported
158  targets in global scope.
159
160* The :module:`FindPkgConfig` module gained support for ``<`` and ``>``
161  operators for version checks in addition to the already supported
162  operators ``>=``, ``<=``, and ``=``.
163
164* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
165  gain capability to control order of resource lookup on macOS (Framework) and
166  Windows (Registry).
167
168* The :module:`FindSubversion` module ``Subversion_WC_INFO`` command
169  gained an ``IGNORE_SVN_FAILURE`` option to suppress failures,
170  e.g. when the source tree is not under Subversion control.
171
172* The :module:`UseSWIG` module learned to manage target property
173  :prop_tgt:`INCLUDE_DIRECTORIES` for ``SWIG`` compilation.
174
175CTest
176-----
177
178* :manual:`ctest(1)` gained a ``--progress`` option to enable a live
179  test progress summary when output goes to a terminal.
180
181CPack
182-----
183
184* The :cpack_gen:`CPack DEB Generator` learned to split debug symbols into
185  a corresponding .ddeb package when ``CPACK_DEBIAN_DEBUGINFO_PACKAGE`` is
186  set.
187
188* The :cpack_gen:`CPack DEB Generator` learned to honor the ``SOURCE_DATE_EPOCH``
189  environment variable when packaging files.  This is useful for generating
190  reproducible packages.
191
192* CPack gained a new :cpack_gen:`CPack External Generator` which is used to
193  export the CPack metadata in a format that other software can understand. The
194  intention of this generator is to allow external packaging software to take
195  advantage of CPack's features when it may not be possible to use CPack for
196  the entire packaging process.
197
198Deprecated and Removed Features
199===============================
200
201* An explicit deprecation diagnostic was added for policies ``CMP0055``
202  through ``CMP0063`` (``CMP0054`` and below were already deprecated).
203  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
204  of all policies are deprecated and that projects should port to the
205  NEW behaviors.
206
207Other Changes
208=============
209
210* The precompiled binaries provided on ``cmake.org`` now include
211  qthelp-format documentation.
212
213* The :command:`option` command now honors an existing normal variable
214  of the same name and does nothing instead of possibly creating a cache
215  entry (or setting its type) and removing the normal variable.
216  See policy :policy:`CMP0077`.
217
218* The :ref:`Makefile Generators` learned to remove custom command and
219  custom target byproducts during ``make clean``.
220
221* The :command:`target_sources` command now interprets relative source file
222  paths as relative to the current source directory.  This simplifies
223  incrementally building up a target's sources from subdirectories.  The
224  :policy:`CMP0076` policy was added to provide backward compatibility with
225  the old behavior where required.
226
227* The :module:`BundleUtilities` module may no longer be included at configure
228  time. This was always a bug anyway. See policy :policy:`CMP0080`.
229
230* The :module:`UseSWIG` module has changed strategy for target naming.
231  See policy :policy:`CMP0078`.
232
233* The :prop_tgt:`LINK_DIRECTORIES` target property now expects absolute paths.
234  See policy :policy:`CMP0081`.
235
236* The CPack generators have been moved into their own separate section
237  in the documentation, rather than having the documentation in their
238  internal implementation modules.
239  These internal implementation modules are also no longer available
240  to scripts that may have been incorrectly including them, because
241  they should never have been available in the first place.
242
243Updates
244=======
245
246Changes made since CMake 3.13.0 include the following.
247
2483.13.2
249------
250
251* CMake 3.13.0 included a change to pass compiler implicit include
252  directories to the ``moc`` tool for :prop_tgt:`AUTOMOC`.  This has
253  been reverted due to regressing existing builds and will need
254  further investigation before being re-introduced in a later release.
255
2563.13.3
257------
258
259* The :generator:`Visual Studio 15 2017` generator has been fixed to work
260  when VS 2019 is installed.
261
262* CMake now checks that at least one of the source or binary directory
263  is specified when running CMake and issues an error if both are missing.
264  This has always been a documented requirement, but the implementation
265  previously accidentally accepted cases in which neither are specified
266  so long as some other argument is given, and silently used the current
267  working directory as the source and build tree.
268
2693.13.4
270------
271
272* The error added by 3.13.3 in cases that neither a source or binary
273  directory is specified has been downgraded to a warning.  While this
274  was never intended, documented, nor supported behavior, some projects
275  relied on it.  The error has been downgraded to a warning for the
276  remainder of the 3.13.x release series to allow a transition period,
277  but it may become a fatal error again in a later release.  Scripts
278  relying on the old behavior can be trivially fixed by specifying
279  the path to the source tree (even if just ``.``) explicitly and
280  continue to work with all versions of CMake.
281
2823.13.5
283------
284
285* In CMake 3.13.0 through 3.13.4, calling :command:`target_link_libraries`
286  to add ``PRIVATE`` dependencies to a static library created in another
287  directory (under policy :policy:`CMP0079` ``NEW`` behavior) would
288  incorrectly propagate usage requirements of those dependencies to
289  dependents that link the static library.  This has been fixed.
290