Help/release/3.11.rst

   1 CMake 3.11 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.10 include the following.
   9
  10 New Features
  11 ============
  12
  13 Platforms
  14 ---------
  15
  16 * TI C/C++ compilers are now supported by the :generator:`Ninja` generator.
  17
  18 Generators
  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
  45 Commands
  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
  76 Variables
  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
 104 Properties
 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
 127 Modules
 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
 179 Autogen
 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
 189 CTest
 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
 198 CPack
 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
 216 Other
 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
 231 Deprecated 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
 242 Other 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
 271 Updates
 272 =======
 273
 274 Changes made since CMake 3.11.0 include the following.
 275
 276 3.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
 287 3.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
 302 3.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.