1CMake 3.3 Release Notes
2***********************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.2 include the following.
9
10New Features
11============
12
13Generators
14----------
15
16* The :ref:`Makefile Generators` now add ``.DELETE_ON_ERROR`` to the
17  makefiles that contain the actual build rules for files on disk.
18  This tells GNU make to remove rule outputs when their recipe
19  modifies an output but fails.
20
21* The :ref:`Visual Studio Generators` learned to support ``.xaml``
22  source files and automatically associate them with corresponding
23  ``.h`` and ``.cpp`` sources.
24
25* A new experimental :generator:`Green Hills MULTI` generator was
26  added on Windows.  `Green Hills MULTI`_ is an IDE for embedded
27  real-time systems.
28
29.. _`Green Hills MULTI`: http://www.ghs.com/products/MULTI_IDE.html
30
31Commands
32--------
33
34* The :command:`add_dependencies` command learned to allow dependencies
35  to be added to :ref:`interface libraries <Interface Libraries>`.
36  Dependencies added to an interface library are followed transitively
37  in its place since the target itself does not build.
38
39* The :command:`execute_process` command learned to support specifying
40  the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``.
41
42* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands
43  learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether
44  the glob result should include directories.
45
46* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
47  commands now search in installation prefixes derived from the ``PATH``
48  environment variable.
49
50* The :command:`if` command learned a new ``IN_LIST`` operator that
51  evaluates to true if a given element is contained in a named list.
52
53* The :command:`install(EXPORT)` and :command:`export()` commands
54  learned to export targets that populate the :prop_tgt:`INTERFACE_SOURCES`
55  target property.
56
57* The :command:`install(TARGETS)` command learned to support
58  generator expressions in the ``DESTINATION`` value.
59
60Variables
61---------
62
63* The version of some Fortran compilers is now detected and stored in the
64  :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>`
65  variable.
66
67* The :ref:`Visual Studio Generators` learned a new
68  :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` option
69  to put the ``INSTALL`` target in the default build of a
70  solution (``.sln``) file.
71
72Properties
73----------
74
75* A :prop_tgt:`CROSSCOMPILING_EMULATOR` target property and supporting
76  :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable were introduced
77  to allow target platform binaries to run on the host during cross
78  compiling.
79
80* A :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property and supporting
81  :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable were introduced
82  to tell the :ref:`Makefile Generators` and the :generator:`Ninja` generator
83  to run ``include-what-you-use`` along with the compiler for ``C`` and
84  ``CXX`` languages.
85
86* The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and
87  :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties now
88  affect compilation in sources of all target types.  See
89  policy :policy:`CMP0063`.
90
91* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned
92  to support generator expressions.
93
94Modules
95-------
96
97* The :module:`CheckFortranCompilerFlag` module was introduced
98  to check ``Fortran`` compiler flags, much like the
99  :module:`CheckCCompilerFlag` module already does for ``C``.
100
101* The :module:`ExternalData` module learned a new
102  :variable:`ExternalData_NO_SYMLINKS` option to disable use of
103  symbolic links to populate the real data files and use copies
104  instead.
105
106* The :module:`ExternalData` module learned a new ``RECURSE:``
107  option in ``DATA{}`` references specifying directories.
108  This allows an entire directory tree of associated files
109  to be matched.
110
111* The :module:`ExternalData` module learned a new URL template
112  placeholder ``%(algo:<key>)`` to allow custom mapping from
113  algorithm name to URL component through configuration of new
114  :variable:`ExternalData_URL_ALGO_<algo>_<key>` variables.
115  This allows more flexibility in remote URLs.
116
117* The :module:`ExternalProject` module learned to replace tokens
118  like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step.
119
120* The :module:`ExternalProject` module APIs learned to support
121  :manual:`generator expressions <cmake-generator-expressions(7)>`
122  when using ``LOG_*`` options and in CMake initial cache options.
123
124* The :module:`FindBoost` module now tracks the directories containing
125  libraries separately for RELEASE and DEBUG configurations.
126
127* The :module:`FindCUDA` module now defaults to using the static
128  CUDA runtime library if it is available.  A new
129  ``CUDA_USE_STATIC_CUDA_RUNTIME`` option is offered to control
130  this behavior.
131
132* The :module:`FindMatlab` module was completely rewritten.  It learned
133  about versions and components and to find Matlab in a more precise and
134  multiplatform way.  The module now offers APIs to create mex extensions,
135  documentation, and unit tests.
136
137* The :module:`FindPackageHandleStandardArgs` module
138  ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now
139  always populates both the ``<PackageName>_FOUND``
140  and ``<UPPERCASE_NAME>_FOUND`` variables (the latter
141  for backwards compatibility).  The ``FOUND_VAR``
142  option is now ignored except to enforce its allowed
143  values.
144
145* The :module:`InstallRequiredSystemLibraries` module learned a new
146  ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the
147  installation component.
148
149Generator Expressions
150---------------------
151
152* A new ``COMPILE_LANGUAGE`` generator expression was introduced to
153  allow specification of compile options for target files based on the
154  :prop_sf:`LANGUAGE` of each source file.  Due to limitations of the
155  underlying native build tools, this feature has varying support across
156  generators.  See the :manual:`cmake-generator-expressions(7)` manual
157  for details.
158
159CTest
160-----
161
162* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>``
163  option to help find sporadic test failures.
164
165* The :module:`CTestCoverageCollectGCOV` module learned to support
166  the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the
167  :command:`ctest_coverage` command.
168
169CPack
170-----
171
172* The :cpack_gen:`CPack IFW Generator` learned to support
173  Qt Framework Installer 2.0 tools.
174
175* The :cpack_gen:`CPack DEB Generator` learned a new
176  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
177  variable to specify per-component use of ``dpkg-shlibdeps``.
178
179* The :cpack_gen:`CPack DEB Generator` learned a new
180  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`
181  option to specify per-component dependencies.
182
183* The :cpack_gen:`CPack RPM Generator` learned to package symbolic links
184  more cleanly and now supports directory symlinks with recent
185  ``rpmbuild`` versions.
186
187* The :cpack_gen:`CPack RPM Generator` learned a new
188  :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify
189  directories containing man pages for the brp-compress RPM macro.
190
191* The :cpack_gen:`CPack RPM Generator` learned a new
192  :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable
193  to specify a component-specific package architecture.
194
195* The CPack WIX generator learned the new
196  :prop_inst:`CPACK_START_MENU_SHORTCUTS`,
197  :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and
198  :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can
199  be used to install shortcuts in the Start Menu, on the Desktop and
200  in the Startup Folder respectively.
201
202Other
203-----
204
205* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
206  is now aware of features supported by GNU compilers on Windows, versions
207  4.4 through 5.0.
208
209* The :manual:`cmake(1)` ``-E tar`` command learned a new
210  ``--format<format>`` option to specify the archive format to
211  be written.
212
213* On OS X, CMake learned to create XCTest bundles to test Frameworks
214  and App Bundles within Xcode.  The :module:`FindXCTest` module
215  provides convenience functions to handle :prop_tgt:`XCTEST` bundles.
216
217Deprecated and Removed Features
218===============================
219
220* On OS X the :manual:`cmake-gui(1)` no longer has the
221  ``Install For Command Line Use`` menu item.  Instead there
222  is a ``How to Install For Command Line Use`` menu item
223  that shows an informational dialog box explaining how to
224  make the command line tools available.  For example::
225
226    /Applications/CMake.app/Contents/bin/cmake-gui --install
227
228* The :command:`ctest_build` and :command:`build_command` commands
229  no longer tell ``make`` tools to ignore errors with the ``-i`` option.
230  Previously this was done for :ref:`Makefile Generators` but not others.
231  See policy :policy:`CMP0061`.
232
233* The :generator:`Visual Studio 10 2010` generator no longer checks
234  for running VS IDEs with the project open or asks them to reload.
235  This was originally done for VS 10 because it had been done for
236  VS 7 through 9 to avoid prompting for every project in a solution.
237  Since VS >= 10 allow the whole solution to reload at once they
238  do not need CMake to help them.
239
240* The :generator:`Visual Studio 7` generator (.NET 2002) is now
241  deprecated and will be removed in a future version of CMake.
242
243* The :generator:`Visual Studio 6` generator is now deprecated
244  and will be removed in a future version of CMake.
245
246* The :command:`find_package` command no longer considers project
247  build trees recently configured in a :manual:`cmake-gui(1)`.
248  This was previously done only on Windows and is now never done.
249  The ``NO_CMAKE_BUILDS_PATH`` option is now ignored if given
250  and effectively always on.
251  Projects may populate the :ref:`User Package Registry` to aid
252  users building multiple dependent projects one after another.
253
254* The :command:`add_definitions()` command no longer causes a
255  :prop_dir:`DEFINITIONS` directory property to be populated. See policy
256  :policy:`CMP0059`.
257
258* With Visual Studio 7, 8, and 9 generators the value of the ``$(OutDir)``
259  placeholder no longer evaluates to the configuration name.  Projects
260  should use ``$(ConfigurationName)`` for that instead.
261
262* Using the output of :command:`export()` with the :command:`install(FILES)`
263  command is no longer allowed.  See policy :policy:`CMP0062` for details.
264
265Other Changes
266=============
267
268* The :generator:`Ninja` generator now requires that calls to the
269  :command:`add_custom_command` and :command:`add_custom_target`
270  commands use the ``BYPRODUCTS`` option to explicitly specify any
271  files generated by the custom commands that are not listed as
272  outputs (perhaps because their timestamps are allowed to be older
273  than the inputs).  See policy :policy:`CMP0058`.
274
275* Build-time progress output of :ref:`Makefile Generators` has been improved.
276  It no longer mixes progress and build rule messages during parallel builds.
277  The link rule messages now have progress and are displayed as bold green
278  instead of bold red (since red is often associated with an error message).
279
280* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio
281  7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``.
282  This should have no effect on the intended use cases of the variable.
283
284* Linking to library files by a full path in an implicit linker search
285  directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to
286  search for the library (e.g. ``-lfoo``) and now links by full path.
287  See policy :policy:`CMP0060`.
288