1CMake 3.2 Release Notes
2***********************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.1 include the following.
9
10New Features
11============
12
13Syntax
14------
15
16* CMake learned to support unicode characters
17  :ref:`encoded as UTF-8 <CMake Language Encoding>`
18  on Windows.  This was already supported on platforms whose
19  system APIs accept UTF-8 encoded strings.
20  Unicode characters may now be used in CMake code, paths to
21  source files, configured files such as ``.h.in`` files, and
22  other files read and written by CMake.  Note that because CMake
23  interoperates with many other tools, there may still be some
24  limitations when using certain unicode characters.
25
26Commands
27--------
28
29* The :command:`add_custom_command` and :command:`add_custom_target`
30  commands learned a new ``BYPRODUCTS`` option to specify files
31  produced as side effects of the custom commands.  These are not
32  outputs because they do not always have to be newer than inputs.
33
34* The :command:`add_custom_command` and :command:`add_custom_target`
35  commands learned a new ``USES_TERMINAL`` option to request that
36  the command be given direct access to the terminal if possible.
37  The :generator:`Ninja` generator will places such commands in the
38  ``console`` :prop_gbl:`pool <JOB_POOLS>`.  Build targets provided by CMake
39  that are meant for individual interactive use, such as ``install``, are now
40  placed in this pool.
41
42* A new :command:`continue` command was added that can be called inside loop
43  contexts to end the current iteration and start the next one at the top of
44  the loop block.
45
46* The :command:`file(LOCK)` subcommand was created to allow CMake
47  processes to synchronize through file and directory locks.
48
49* The :command:`file(STRINGS)` now supports UTF-16LE, UTF-16BE,
50  UTF-32LE, UTF-32BE as ``ENCODING`` options.
51
52* The :command:`install(EXPORT)` command now works with an absolute
53  ``DESTINATION`` even if targets in the export set are installed
54  with a destination or :ref:`usage requirements <Target Usage Requirements>`
55  specified relative to the install prefix.  The value of the
56  :variable:`CMAKE_INSTALL_PREFIX` variable is hard-coded into the installed
57  export file as the base for relative references.
58
59* The :command:`try_compile` command source file signature now honors
60  link flags (e.g. :variable:`CMAKE_EXE_LINKER_FLAGS`) in the generated
61  test project.  See policy :policy:`CMP0056`.
62
63* The :command:`try_run` command learned to honor the ``LINK_LIBRARIES``
64  option just as :command:`try_compile` already does.
65
66* The :command:`file(GENERATE)` command now generates the output file with
67  the same permissions as the input file if set.
68
69* The :command:`file(GENERATE)` command can now generate files which are
70  used as source files for buildsystem targets.  Generated files
71  automatically get their :prop_sf:`GENERATED` property set to ``TRUE``.
72
73Variables
74---------
75
76* The :variable:`CMAKE_MATCH_COUNT` variable was introduced to record the
77  number of matches made in the last regular expression matched in an
78  :command:`if` command or a :command:`string` command.
79
80Properties
81----------
82
83* An :prop_tgt:`ANDROID_API_MIN` target property was introduced to
84  specify the minimum version to be targeted by the toolchain.
85
86* A :prop_sf:`VS_SHADER_FLAGS` source file property was added to specify
87  additional shader flags to ``.hlsl`` files, for the Visual Studio
88  generators.
89
90Modules
91-------
92
93* The :module:`ExternalData` module learned to support
94  :ref:`Custom Fetch Scripts <ExternalData Custom Fetch Scripts>`.
95  This allows projects to specify custom ``.cmake`` scripts for
96  fetching data objects during the build.
97
98* The :module:`ExternalProject` module learned options to create
99  independent external project step targets that do not depend
100  on the builtin steps.
101
102* The :module:`ExternalProject` module :command:`ExternalProject_Add`
103  command learned a new ``CMAKE_CACHE_DEFAULT_ARGS`` option to
104  initialize cache values in the external project without setting
105  them on future builds.
106
107* The :module:`ExternalProject` module :command:`ExternalProject_Add`
108  command learned a new ``TEST_EXCLUDE_FROM_MAIN`` option to exclude
109  tests from the main build.
110
111* The :module:`ExternalProject` module :command:`ExternalProject_Add`
112  command learned a new ``UPDATE_DISCONNECTED`` option to avoid
113  automatically updating the source tree checkout from version control.
114
115* The :module:`FindCUDA` module learned about the ``cusolver``
116  library in CUDA 7.0.
117
118* The :module:`FindGit` module learned to find the ``git`` command-line tool
119  that comes with GitHub for Windows installed in user home directories.
120
121* A :module:`FindGSL` module was introduced to find the
122  GNU Scientific Library.
123
124* A :module:`FindIntl` module was introduced to find the
125  Gettext ``libintl`` library.
126
127* The :module:`FindLATEX` module learned to support components.
128
129* The :module:`FindMPI` module learned to find MS-MPI on Windows.
130
131* The :module:`FindOpenSSL` module now reports ``crypto`` and ``ssl``
132  libraries separately in ``OPENSSL_CRYPTO_LIBRARY`` and
133  ``OPENSSL_SSL_LIBRARY``, respectively, to allow applications to
134  link to one without the other.
135
136* The :module:`WriteCompilerDetectionHeader` module learned to
137  create a define for portability of the ``cxx_thread_local`` feature.
138  The define expands to either the C++11 ``thread_local`` keyword, or a
139  pre-standardization compiler-specific equivalent, as appropriate.
140
141* The :module:`WriteCompilerDetectionHeader` module learned to create
142  multiple output files per compiler and per language, instead of creating
143  one large file.
144
145CTest
146-----
147
148* The :command:`ctest_coverage` command learned to support Delphi coverage.
149
150* The :command:`ctest_coverage` command learned to support Javascript coverage.
151
152* The :module:`CTestCoverageCollectGCOV` module was introduced as an
153  alternative to the :command:`ctest_coverage` command for collecting
154  ``gcov`` results for submission to CDash.
155
156CPack
157-----
158
159* The :cpack_gen:`CPack RPM Generator` learned options to set per-component
160  descriptions and summaries.  See the
161  :variable:`CPACK_RPM_<component>_PACKAGE_DESCRIPTION` and
162  :variable:`CPACK_RPM_<component>_PACKAGE_SUMMARY` variables.
163
164* The :cpack_gen:`CPack RPM Generator` learned options to specify
165  requirements for pre- and post-install scripts.  See the
166  :variable:`CPACK_RPM_PACKAGE_REQUIRES_PRE` and
167  :variable:`CPACK_RPM_PACKAGE_REQUIRES_POST` variables.
168
169* The :cpack_gen:`CPack RPM Generator` learned options to specify
170  requirements for pre- and post-uninstall scripts.  See the
171  :variable:`CPACK_RPM_PACKAGE_REQUIRES_PREUN` and
172  :variable:`CPACK_RPM_PACKAGE_REQUIRES_POSTUN` variables.
173
174* The :cpack_gen:`CPack RPM Generator` learned a new
175  :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` variable to
176  specify a component-specific value to use instead of
177  :variable:`CPACK_PACKAGING_INSTALL_PREFIX`.
178
179* The :cpack_gen:`CPack RPM Generator` learned a new
180  :variable:`CPACK_RPM_RELOCATION_PATHS` variable to
181  specify multiple relocation prefixes for a single rpm package.
182
183Other
184-----
185
186* The :manual:`cmake(1)` ``-E tar`` command now supports creating
187  ``.xz``-compressed archives with the ``J`` flag.
188
189* The :manual:`cmake(1)` ``-E tar`` command learned a new
190  ``--files-from=<file>`` option to specify file names using
191  lines in a file to overcome command-line length limits.
192
193* The :manual:`cmake(1)` ``-E tar`` command learned a new
194  ``--mtime=<date>`` option to specify the modification time
195  recorded in tarball entries.
196
197* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
198  is now aware of features supported by more compilers, including:
199
200  * Apple Clang (``AppleClang``) for Xcode versions 4.4 though 6.1.
201  * GNU compiler versions 4.4 through 5.0 on UNIX and Apple (``GNU``).
202  * Microsoft Visual Studio (``MSVC``) for versions 2010 through 2015.
203  * Oracle SolarisStudio (``SunPro``) version 12.4.
204
205* The :ref:`Qt AUTORCC` feature now tracks files listed in ``.qrc`` files
206  as dependencies. If an input file to the ``rcc`` tool is changed, the tool
207  is automatically re-run.
208
209New Diagnostics
210===============
211
212* The :command:`break` command now rejects calls outside of a loop
213  context or that pass arguments to the command.
214  See policy :policy:`CMP0055`.
215
216Deprecated and Removed Features
217===============================
218
219* Files written in the :manual:`cmake-language(7)`, such as
220  ``CMakeLists.txt`` or ``*.cmake`` files, are now expected to be
221  encoded as UTF-8.  If files are already ASCII, they will be
222  compatible.  If files were in a different encoding, including
223  Latin 1, they will need to be converted.
224
225* The :module:`FindOpenGL` module no longer explicitly searches
226  for any dependency on X11 libraries with the :module:`FindX11`
227  module.  Such dependencies should not need to be explicit.
228  Applications using X11 APIs themselves should find and link
229  to X11 libraries explicitly.
230
231* The implementation of CMake now relies on some C++ compiler features which
232  are not supported by some older compilers.  As a result, those old compilers
233  can no longer be used to build CMake itself.  CMake continues to be able to
234  generate Makefiles and project files for users of those old compilers
235  however.  Compilers known to no longer be capable of building CMake are:
236
237  * Visual Studio 6 and 7.0 -- superseded by VisualStudio 7.1 and newer.
238  * GCC 2.95 -- superseded by GCC 3 and newer compilers.
239  * Borland compilers -- superseded by other Windows compilers.
240  * Compaq compilers -- superseded by other compilers.
241  * SGI compilers -- IRIX was dropped as a host platform.
242
243Other Changes
244=============
245
246* On Windows and OS X, commands supporting network communication
247  via ``https``, such as :command:`file(DOWNLOAD)`,
248  :command:`file(UPLOAD)`, and :command:`ctest_submit`, now support
249  SSL/TLS even when CMake is not built against OpenSSL.
250  The Windows or OS X native SSL/TLS implementation is used by default.
251  OS-configured certificate authorities will be trusted automatically.
252
253  On other platforms, when CMake is built with OpenSSL, these
254  commands now search for OS-configured certificate authorities
255  in a few ``/etc`` paths to be trusted automatically.
256
257* On OS X with Makefile and Ninja generators, when a compiler is found
258  in ``/usr/bin`` it is now mapped to the corresponding compiler inside
259  the Xcode application folder, if any.  This allows such build
260  trees to continue to work with their original compiler even when
261  ``xcode-select`` switches to a different Xcode installation.
262
263* The Visual Studio generators now write solution and project
264  files in UTF-8 instead of Windows-1252.  Windows-1252 supported
265  Latin 1 languages such as those found in North and South America
266  and Western Europe.  With UTF-8, additional languages are now
267  supported.
268
269* The :generator:`Xcode` generator no longer requires a value for
270  the :variable:`CMAKE_MAKE_PROGRAM` variable to be located up front.
271  It now locates ``xcodebuild`` when needed at build time.
272
273* When building CMake itself using SolarisStudio 12, the default ``libCStd``
274  standard library is not sufficient to build CMake.  The SolarisStudio
275  distribution supports compiler options to use ``STLPort4`` or ``libstdc++``.
276  An appropriate option to select the standard library is now added
277  automatically when building CMake with SolarisStudio compilers.
278