1 CMake 3.11 Release Notes
2 ************************
8 Changes made since CMake 3.10 include the following.
16 * TI C/C++ compilers are now supported by the :generator:`Ninja` generator.
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.
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.
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
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.
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.
52 * The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands
53 gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a
56 * The :command:`target_compile_definitions` command learned to set the
57 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on
58 :ref:`Imported Targets`.
60 * The :command:`target_compile_features` command learned to set the
61 :prop_tgt:`INTERFACE_COMPILE_FEATURES` property on :ref:`Imported Targets`.
63 * The :command:`target_compile_options` command learned to set the
64 :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property on :ref:`Imported Targets`.
66 * The :command:`target_include_directories` command learned to set the
67 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property on
68 :ref:`Imported Targets`.
70 * The :command:`target_sources` command learned to set the
71 :prop_tgt:`INTERFACE_SOURCES` property on :ref:`Imported Targets`.
73 * The :command:`target_link_libraries` command learned to set the
74 :prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`.
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.
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``.
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
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.
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.
107 * The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support
108 :manual:`generator expressions <cmake-generator-expressions(7)>`.
110 * A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list
111 of options to pass to the compiler.
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``.
120 * An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify
121 list of preprocessor include file search directories.
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`.
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.
134 * The :module:`CMakePackageConfigHelpers` module
135 :command:`write_basic_package_version_file` command learned a new
136 ``SameMinorVersion`` mode for the ``COMPATIBILITY`` argument.
138 * The :module:`ExternalProject` module learned to substitute ``<DOWNLOAD_DIR>``
139 in comments, commands, working directory and byproducts.
141 * The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE``
142 options to specify use of a ``.netrc`` file.
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.
153 * The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
154 `FLAME`_ ``blis`` and ``libflame``.
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
162 * A :module:`FindIconv` module was added to locate iconv support.
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.
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`_.
176 .. _`FLAME`: https://github.com/flame
177 .. _`JEP 313`: http://openjdk.java.net/jeps/313
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.
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.
201 * :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options.
203 * The :module:`CPackIFW` module gained new
204 :variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control
205 if the target directory should not be deleted when uninstalling.
207 * The :module:`CPackRPM` module learned to enable enforcing of execute
208 privileges on programs and shared libraries.
209 See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable.
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``).
219 * :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are
220 created with the ``GLOBAL`` option to :command:`add_library`.
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.
227 * The :manual:`cmake(1)` ``--open <dir>`` command-line option was added
228 to open generated IDE projects like Visual Studio solutions or Xcode
231 Deprecated and Removed Features
232 ===============================
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
240 * The ``KDevelop3`` generator has been removed.
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.
249 * The :module:`FindOpenGL` module now prefers GLVND libraries if available.
250 See policy :policy:`CMP0072`.
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
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.
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.
274 Changes made since CMake 3.11.0 include the following.
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.
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.
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`.