1CMake 3.11 Release Notes
2************************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.10 include the following.
9
10New Features
11============
12
13Platforms
14---------
15
16* TI C/C++ compilers are now supported by the :generator:`Ninja` generator.
17
18Generators
19----------
20
21* The :generator:`CodeBlocks` extra generator learned to check a
22  :variable:`CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom
23  compiler identification value to place in the project file.
24
25* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
26  to add compiler launcher tools along with the compiler for the ``Fortran``
27  language (``C``, ``CXX``, and ``CUDA`` were supported previously).
28  See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
29  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
30
31* :ref:`Visual Studio Generators` learned to support the ``COMPILE_LANGUAGE``
32  :manual:`generator expression <cmake-generator-expressions(7)>` in
33  target-wide :prop_tgt:`COMPILE_DEFINITIONS`,
34  :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_OPTIONS`, and
35  :command:`file(GENERATE)`.  See generator expression documentation
36  for caveats.
37
38* The :generator:`Xcode` generator learned to support the ``COMPILE_LANGUAGE``
39  :manual:`generator expression <cmake-generator-expressions(7)>` in
40  target-wide :prop_tgt:`COMPILE_DEFINITIONS` and
41  :prop_tgt:`INCLUDE_DIRECTORIES`.  It previously supported only
42  :prop_tgt:`COMPILE_OPTIONS` and :command:`file(GENERATE)`.
43  See generator expression documentation for caveats.
44
45Commands
46--------
47
48* :command:`add_library` and :command:`add_executable` commands can now be
49  called without any sources and will not complain as long as sources are
50  added later via the :command:`target_sources` command.
51
52* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands
53  gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a
54  ``.netrc`` file.
55
56* The :command:`target_compile_definitions` command learned to set the
57  :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on
58  :ref:`Imported Targets`.
59
60* The :command:`target_compile_features` command learned to set the
61  :prop_tgt:`INTERFACE_COMPILE_FEATURES` property on :ref:`Imported Targets`.
62
63* The :command:`target_compile_options` command learned to set the
64  :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property on :ref:`Imported Targets`.
65
66* The :command:`target_include_directories` command learned to set the
67  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property on
68  :ref:`Imported Targets`.
69
70* The :command:`target_sources` command learned to set the
71  :prop_tgt:`INTERFACE_SOURCES` property on :ref:`Imported Targets`.
72
73* The :command:`target_link_libraries` command learned to set the
74  :prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`.
75
76Variables
77---------
78
79* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced
80  to hold the selected instance of the generator's corresponding
81  native tools if multiple are available.  This is used by the
82  :generator:`Visual Studio 15 2017` generator to hold the
83  selected instance of Visual Studio persistently.
84
85* A :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
86  to enable setting of default permissions for directories created implicitly
87  during installation of files by :command:`install` and
88  :command:`file(INSTALL)`, e.g. during ``make install``.
89
90* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for
91  the :prop_gbl:`JOB_POOLS` property. This enables control over build
92  parallelism with command line configuration parameters when using the Ninja
93  generator.
94
95* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables
96  were added to specify use of a ``.netrc`` file by the
97  :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and
98  the :module:`ExternalProject` module.
99
100* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to
101  initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property
102  on targets when they are created.
103
104Properties
105----------
106
107* The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support
108  :manual:`generator expressions <cmake-generator-expressions(7)>`.
109
110* A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list
111  of options to pass to the compiler.
112
113* An :prop_tgt:`IMPORTED_GLOBAL` target property was added to indicate
114  whether an :ref:`IMPORTED target <Imported Targets>` is globally visible.
115  It is automatically set to a true value for targets created with the
116  ``GLOBAL`` option to :command:`add_library` or :command:`add_executable`.
117  Additionally, project code may now *promote* a local imported target
118  to be globally visible by setting this property to ``TRUE``.
119
120* An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify
121  list of preprocessor include file search directories.
122
123* Source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` and
124  :prop_sf:`VS_SHADER_ENABLE_DEBUG` have been added to specify more
125  details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.
126
127Modules
128-------
129
130* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES`
131  command gained a ``LANGUAGE`` option to specify whether to check using the
132  ``C`` or ``CXX`` compiler.
133
134* The :module:`CMakePackageConfigHelpers` module
135  :command:`write_basic_package_version_file` command learned a new
136  ``SameMinorVersion`` mode for the ``COMPATIBILITY`` argument.
137
138* The :module:`ExternalProject` module learned to substitute ``<DOWNLOAD_DIR>``
139  in comments, commands, working directory and byproducts.
140
141* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE``
142  options to specify use of a ``.netrc`` file.
143
144* A new :module:`FetchContent` module was added which supports populating
145  content at configure time using any of the download/update methods
146  supported by :command:`ExternalProject_Add`.  This allows the content
147  to be used immediately during the configure stage, such as with
148  :command:`add_subdirectory`, etc.  Hierarchical project structures are
149  well supported, allowing parent projects to override the content details
150  of child projects and ensuring content is not populated multiple times
151  throughout the whole project tree.
152
153* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
154  `FLAME`_ ``blis`` and ``libflame``.
155
156* The :module:`FindDoxygen` module :command:`doxygen_add_docs` function
157  now supports a new ``DOXYGEN_VERBATIM_VARS`` list variable.  Any
158  ``DOXYGEN_...`` variable contained in that list will bypass the automatic
159  quoting logic, leaving its contents untouched when transferring them to the
160  output ``Doxyfile``.
161
162* A :module:`FindIconv` module was added to locate iconv support.
163
164* The :module:`GenerateExportHeader` module ``GENERATE_EXPORT_HEADER`` command
165  gained an ``INCLUDE_GUARD_NAME`` option to change the name of the include
166  guard symbol written to the generated export header.
167  Additionally, it now adds a comment after the closing ``#endif`` on the
168  generated export header's include guard.
169
170* The :module:`UseJava` module ``add_jar`` command gained a
171  ``GENERATE_NATIVE_HEADERS`` option to generate native header files
172  using ``javac -h`` for ``javac`` 1.8 or above.  This supersedes
173  ``create_javah``, which no longer works with JDK 1.10 and above due
174  to removal of the ``javah`` tool by `JEP 313`_.
175
176.. _`FLAME`: https://github.com/flame
177.. _`JEP 313`: http://openjdk.java.net/jeps/313
178
179Autogen
180-------
181
182* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, CMake now starts
183  multiple parallel ``moc`` or ``uic`` processes to reduce the build time.
184  A new :variable:`CMAKE_AUTOGEN_PARALLEL` variable and
185  :prop_tgt:`AUTOGEN_PARALLEL` target property may be set to specify the
186  number of parallel ``moc`` or ``uic`` processes to start.  The default
187  is derived from the number of CPUs on the host.
188
189CTest
190-----
191
192* The :command:`ctest_start` command no longer sets
193  :variable:`CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is
194  called from inside a function. Instead, it sets an internal variable in
195  CTest. However, setting :variable:`CTEST_RUN_CURRENT_SCRIPT` to 0 at the
196  global scope still prevents the script from being re-run at the end.
197
198CPack
199-----
200
201* :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options.
202
203* The :cpack_gen:`CPack IFW Generator` gained new
204  :variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control
205  if the target directory should not be deleted when uninstalling.
206
207* The :cpack_gen:`CPack RPM Generator` learned to enable enforcing of execute
208  privileges on programs and shared libraries.
209  See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable.
210
211* A :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
212  which serves the same purpose during packaging (e.g. ``make package``) as the
213  :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during
214  installation (e.g. ``make install``).
215
216Other
217-----
218
219* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are
220  created with the ``GLOBAL`` option to :command:`add_library`.
221
222* :ref:`Interface Libraries` may now have custom properties set on them if
223  they start with either an underscore (``_``) or a lowercase ASCII character.
224  The original intention was to only allow properties which made sense for
225  ``INTERFACE`` libraries, but it also blocked usage of custom properties.
226
227* The :manual:`cmake(1)` ``--open <dir>`` command-line option was added
228  to open generated IDE projects like Visual Studio solutions or Xcode
229  projects.
230
231Deprecated and Removed Features
232===============================
233
234* An explicit deprecation diagnostic was added for policies ``CMP0037``
235  through ``CMP0054`` (``CMP0036`` and below were already deprecated).
236  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
237  of all policies are deprecated and that projects should port to the
238  NEW behaviors.
239
240* The ``KDevelop3`` generator has been removed.
241
242Other Changes
243=============
244
245* Policy :policy:`CMP0037` no longer reserves target names associated
246  with optional features, such as ``test`` and ``package``, unless
247  the corresponding feature is enabled.
248
249* The :module:`FindOpenGL` module now prefers GLVND libraries if available.
250  See policy :policy:`CMP0072`.
251
252* The minimum deployment target set in the
253  :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only
254  applied for macOS regardless of the selected SDK.  It is now properly
255  set for the target platform selected by :variable:`CMAKE_OSX_SYSROOT`.
256  For example, if the sysroot variable specifies an iOS SDK then the
257  value in ``CMAKE_OSX_DEPLOYMENT_TARGET`` is interpreted as minimum
258  iOS version.
259
260* The :generator:`Xcode` generator behavior of generating one project
261  file per :command:`project()` command may now be controlled with the
262  :variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable.
263  This could be useful to speed up the CMake generation step for
264  large projects and to work-around a bug in the ``ZERO_CHECK`` logic.
265
266* Since the ``CMakeCache.txt`` format does not support newlines in values,
267  values containing newlines are now truncated before writing to the file.
268  In addition, a warning comment is written to the cache file, and a warning
269  message is displayed to the user on the console.
270
271Updates
272=======
273
274Changes made since CMake 3.11.0 include the following.
275
2763.11.1
277------
278
279* The :module:`CheckIncludeFile` module ``check_include_file`` macro,
280  :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro,
281  and :module:`CheckIncludeFiles` module ``check_include_files`` macro
282  were taught to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable in
283  CMake 3.11.0.  This has been reverted due to changing behavior of
284  checks for existing projects.  It may be restored in the future
285  with a policy for compatibility.
286
2873.11.2
288------
289
290* Calling :command:`add_library` to create an alias of an imported
291  target that is not globally visible now causes an error again as
292  it did prior to 3.11.0.  This diagnostic was accidentally dropped
293  from CMake 3.11.0 and 3.11.1 by the change to allow globally visible
294  imported targets to be aliased.
295
296* The :module:`FindQt4` module ``qt4_wrap_cpp``, ``qt4_wrap_ui`` and
297  ``qt4_add_resources`` macros now set :prop_sf:`SKIP_AUTOMOC` and
298  :prop_sf:`SKIP_AUTOUIC` on their generated files.  These files never
299  need to be processed by moc or uic, and we must say so explicitly to
300  account for policy :policy:`CMP0071`.
301
3023.11.3
303------
304
305* CMake 3.11.0 introduced support for resolving symbolic links on
306  Windows in code paths that typically do so on UNIX.  This has been
307  reverted due to breakage on ``subst`` drives.
308