1CMake 3.10 Release Notes
2************************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.9 include the following.
9
10New Features
11============
12
13Platforms
14---------
15
16* The `flang`_ Fortran compiler is now supported, with compiler id ``Flang``.
17
18* A new minimal platform file for ``Midipix`` was added.
19
20* Support for the MSVC ARM64 architecture was added.
21  Visual Studio 2017 Update 4 and above offer an ARM64 toolchain.
22
23* Support for the IAR ARM Compiler was improved.
24
25.. _`flang`: https://github.com/flang-compiler/flang
26
27Generators
28----------
29
30* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
31  to add compiler launcher tools like ccache along with the compiler for the
32  ``CUDA`` language (``C`` and ``CXX`` were supported previously).  See the
33  :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
34  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
35
36* The :generator:`CodeBlocks` extra generator learned to optionally exclude
37  files from outside the project root directory from the generated project.
38  See the :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable.
39
40Commands
41--------
42
43* The :command:`cmake_host_system_information` command learned more keys
44  to get information about the processor capabilities and the host OS
45  version.
46
47* The :command:`configure_file` command learned to support indented
48  ``#  cmakedefine`` and ``#  cmakedefine01``. Spaces and/or tabs between
49  the ``#`` character and the ``cmakedefine``/``cmakedefine01`` words
50  are now understood and preserved in the output.
51
52* The :command:`execute_process` command gained a ``RESULTS_VARIABLE``
53  option to collect a list of results from all children in a pipeline
54  of processes when multiple ``COMMAND`` arguments are given.
55
56* The :command:`include_guard` command was introduced to allow guarding
57  CMake scripts from being included more than once. The command supports
58  ``DIRECTORY`` and ``GLOBAL`` options to adjust the corresponding include guard
59  scope. If no options given, include guard is similar to basic variable-based
60  check.
61
62* The :command:`string` command learned a new ``PREPEND`` subcommand.
63
64* The :command:`string(TIMESTAMP)` command now supports ``%A``
65  for full weekday name and ``%B`` for full month name.
66
67Variables
68---------
69
70* A :variable:`CMAKE_DIRECTORY_LABELS` variable was added to specify
71  labels for all tests in a directory.
72
73Properties
74----------
75
76* A :prop_tgt:`<LANG>_CPPCHECK` target property and supporting
77  :variable:`CMAKE_<LANG>_CPPCHECK` variable were introduced to tell
78  the :ref:`Makefile Generators` and the :generator:`Ninja` generator to
79  run ``cppcheck`` with the compiler for ``C`` and ``CXX`` languages.
80
81* A :prop_dir:`LABELS` directory property was added to specify labels
82  for all targets and tests in a directory.
83
84* A :prop_dir:`TEST_INCLUDE_FILES` directory property was added to
85  list any number of files to be included when running tests with
86  :manual:`ctest(1)`.  This generalizes the :prop_dir:`TEST_INCLUDE_FILE`
87  property.
88
89* The :prop_tgt:`VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>`
90  target property was added to support custom XML tags for reference
91  assemblies in C# targets.
92
93* Source file properties :prop_sf:`VS_SHADER_OUTPUT_HEADER_FILE` and
94  :prop_sf:`VS_SHADER_VARIABLE_NAME` have been added to specify more
95  details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.
96
97Modules
98-------
99
100* The :module:`FindCurses` module gained a ``CURSES_NEED_WIDE`` option
101  to request the wide-character variant.
102
103* The :module:`FindEXPAT` module now provides imported targets.
104
105* The :module:`FindFreetype` module now provides imported targets.
106
107* :module:`FindMPI` gained a number of new features, including:
108
109  * Language-specific components have been added to the module.
110  * Many more MPI environments are now supported.
111  * The environmental support for Fortran has been improved.
112  * A user now has fine-grained control over the MPI selection process,
113    including passing custom parameters to the MPI compiler.
114  * The version of the implemented MPI standard is now being exposed.
115  * MPI-2 C++ bindings can now be detected and also suppressed if so desired.
116  * The available Fortran bindings are now being detected and verified.
117  * Various MPI-3 information can be requested, including the library version
118    and Fortran capabilities of the individual bindings.
119  * Statically linked MPI implementations are supported.
120
121* A :module:`FindOpenACC` module was added to detect compiler support
122  for OpenACC.  Currently only supports PGI, GNU and Cray compilers.
123
124* The :module:`FindOpenGL` module gained support for GLVND on Linux.
125
126* The :module:`FindOpenMP` module gained support for
127  language-specific components.
128
129* A :module:`FindPatch` module was added to find the ``patch``
130  command-line executable.
131
132* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp` command
133  gained a ``DESCRIPTORS`` option to generate descriptor files.
134
135* The :module:`GoogleTest` module gained a new command
136  :command:`gtest_discover_tests` implementing dynamic (build-time) test
137  discovery.  Unlike the source parsing approach, dynamic discovery executes
138  the test (in 'list available tests' mode) at build time to discover tests.
139  This is robust against unusual ways of labeling tests, provides much better
140  support for advanced features such as parameterized tests, and does not
141  require re-running CMake to discover added or removed tests within a test
142  executable.  Note that a breaking change was made in CMake 3.10.3 to address
143  an ambiguity of the ``TIMEOUT`` keyword (see :ref:`Release Notes 3.10.3`).
144
145* The :module:`InstallRequiredSystemLibraries` module gained support
146  for installing Intel compiler runtimes.
147
148Autogen
149-------
150
151* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` with a
152  multi configuration generator (e.g. :generator:`Xcode`),
153  included ``*.moc``,  ``moc_*.cpp`` and ``ui_*.h`` files are generated in
154  ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` instead of
155  ``<AUTOGEN_BUILD_DIR>/include``.
156
157* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`,
158  source files that are :prop_sf:`GENERATED` will be processed as well.
159  They were ignored by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`
160  in earlier releases.
161  See policy :policy:`CMP0071`.
162
163* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``,
164  ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs
165  to be ``moc`` processed.  The new :variable:`CMAKE_AUTOMOC_MACRO_NAMES`
166  variable and :prop_tgt:`AUTOMOC_MACRO_NAMES` target property may be set
167  to register additional strings (macro names) to search for.
168
169* When using :prop_tgt:`AUTOMOC`, the new
170  :variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES` variable and
171  :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` target property specify whether
172  to enable or disable the generation of the compiler pre definitions file
173  ``moc_predefs.h``.
174
175CTest
176-----
177
178* A :variable:`CTEST_LABELS_FOR_SUBPROJECTS` CTest module variable and CTest
179  script variable were added to specify a list of labels that should be
180  treated as subprojects by CDash. To use this value in both the CTest module
181  and the ctest command line :ref:`Dashboard Client` mode (e.g. ``ctest -S``)
182  set it in the ``CTestConfig.cmake`` config file.
183
184CPack
185-----
186
187* A :cpack_gen:`CPack FreeBSD Generator` was added for FreeBSD ``pkg(8)``.
188
189* The :cpack_gen:`CPack DEB Generator` was enabled on Windows.  While not
190  fully featured (due to the lack of external UNIX tools) this will allow
191  building basic cross-platform Debian packages.
192
193* The :cpack_gen:`CPack DEB Generator` learned to set package release
194  version in ``Version`` info property.
195  See the :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` variable.
196
197* The :cpack_gen:`CPack DEB Generator` learned more strict package
198  version checking that complies with Debian rules.
199
200* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
201  :command:`cpack_ifw_configure_component_group` commands gained a new
202  ``REPLACES`` and ``CHECKABLE`` options.
203
204* The :cpack_gen:`CPack IFW Generator` gained new
205  :variable:`CPACK_IFW_PACKAGE_FILE_EXTENSION` variable to customize
206  target binary format.
207
208* The :cpack_gen:`CPack IFW Generator` gained new
209  :variable:`CPACK_IFW_REPOSITORIES_DIRECTORIES` variable to specify
210  additional repositories dirs that will be used to resolve and
211  repack dependent components. This feature is only available when
212  using QtIFW 3.1 or later.
213
214* The :cpack_gen:`CPack RPM Generator` and :cpack_gen:`CPack DEB Generator`
215  learned to set the package epoch version.
216  See :variable:`CPACK_RPM_PACKAGE_EPOCH` and
217  :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables.
218
219Other
220-----
221
222* The :manual:`cmake(1)` ``-E`` mode gained support for ``sha1sum``,
223  ``sha224sum``, ``sha256sum``, ``sha384sum``, and ``sha512sum``.
224
225* The graphviz output now distinguishes among the different dependency types
226  ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` and represents them in the output
227  graph as solid, dashed and dotted edges.
228
229Deprecated and Removed Features
230===============================
231
232* Support for building CMake itself with C++98 compilers was dropped.
233  CMake is now implemented using C++11.
234
235* Support for building CMake on HP-UX has been dropped pending better
236  support for C++11 and a port of libuv.  See `CMake Issue 17137`_.
237  Use CMake 3.9 or lower instead for HP-UX support.
238
239.. _`CMake Issue 17137`: https://gitlab.kitware.com/cmake/cmake/-/issues/17137
240
241Other Changes
242=============
243
244* On FreeBSD the C++ compiler named ``c++`` is now the preferred default.
245
246* The :command:`file(GENERATE)` command now interprets relative paths
247  given to its ``OUTPUT`` and ``INPUT`` arguments with respect to the
248  caller's current binary and source directories, respectively.
249  See policy :policy:`CMP0070`.
250
251* The :command:`get_filename_component` ``PROGRAM`` mode semantics
252  have been revised to not tolerate unquoted spaces in the path
253  to the program while also accepting arguments.  While technically
254  incompatible with the old behavior, it is expected that behavior
255  under typical use cases with properly-quoted command-lines has
256  not changed.
257
258Updates
259=======
260
261Changes made since CMake 3.10.0 include the following.
262
2633.10.1
264------
265
266* The :manual:`cmake-server(7)` ``codemodel`` response ``crossReferences``
267  field added by 3.10.0 has been dropped due to excessive memory usage.
268  Another approach will be needed to provide backtrace information.
269
270.. _`Release Notes 3.10.3`:
271
2723.10.3
273------
274
275* CMake 3.10.1 added a ``TIMEOUT`` option to :command:`gtest_discover_tests`
276  from the :module:`GoogleTest` module.  That keyword clashed with the
277  ``TIMEOUT`` test property, which is one of the common properties that
278  would be set with the command's ``PROPERTIES`` keyword, usually leading
279  to legal but unintended behavior.  The keyword was changed to
280  ``DISCOVERY_TIMEOUT`` in CMake 3.10.3 to address this problem.  The
281  ambiguous behavior of the :command:`gtest_discover_tests` command's
282  ``TIMEOUT`` keyword in 3.10.1 and 3.10.2 has not been preserved.
283