Help/release/3.12.rst

   1 CMake 3.12 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.11 include the following.
   9
  10 New Features
  11 ============
  12
  13 Generators
  14 ----------
  15
  16 * The :ref:`Visual Studio Generators` for VS 2017 learned to support a
  17   ``version=14.##`` option in the :variable:`CMAKE_GENERATOR_TOOLSET`
  18   value (e.g. via the :manual:`cmake(1)` ``-T`` option) to specify a
  19   toolset version number.
  20
  21 Command-Line
  22 ------------
  23
  24 * The :manual:`cmake(1)` :ref:`Build Tool Mode` (``cmake --build``) gained
  25   ``--parallel [<jobs>]`` and ``-j [<jobs>]`` options to specify a parallel
  26   build level.  They map to corresponding options of the native build tool.
  27
  28 Commands
  29 --------
  30
  31 * The :command:`add_compile_definitions` command was added to set preprocessor
  32   definitions at directory level.  This supersedes :command:`add_definitions`.
  33
  34 * The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)`
  35   commands now accept a version range using the form ``<min>[...<max>]``.
  36   The ``<min>`` version is required but policies are set based on the
  37   older of the running CMake version and the version specified by
  38   ``<max>``.  This allows projects to specify a range of versions
  39   for which they have been updated and avoid explicit policy settings.
  40
  41 * The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands
  42   learned a new flag ``CONFIGURE_DEPENDS`` which enables expression of
  43   build system dependency on globbed directory's contents.
  44
  45 * The :command:`file(TOUCH)` and :command:`file(TOUCH_NOCREATE)` commands
  46   were added to expose ``TOUCH`` functionality without having to use
  47   CMake's command-line tool mode with :command:`execute_process`.
  48
  49 * The :command:`find_package` command now searches prefixes specified by
  50   the :variable:`<PackageName>_ROOT` CMake variable and the
  51   :envvar:`<PackageName>_ROOT` environment variable.  Package roots are
  52   maintained as a stack so nested calls to all ``find_*`` commands inside
  53   find modules also search the roots as prefixes.
  54   See policy :policy:`CMP0074`.
  55
  56 * The :command:`install` command learned an optional ``NAMELINK_COMPONENT``
  57   parameter, which allows you to change the component for a shared library's
  58   namelink. If none is specified, the value of ``COMPONENT`` is used by
  59   default.
  60
  61 * The :command:`list` command learned a ``JOIN`` sub-command
  62   to concatenate list's elements separated by a glue string.
  63
  64 * The :command:`list` command learned a ``SUBLIST`` sub-command
  65   to get a sublist of the list.
  66
  67 * The :command:`list` command learned a ``TRANSFORM`` sub-command
  68   to apply various string transformation to list's elements.
  69
  70 * The :command:`project` command learned an optional ``HOMEPAGE_URL``
  71   parameter which has the effect of setting variables like
  72   :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`
  73   and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.
  74
  75 * The :command:`string` command learned a ``JOIN`` sub-command
  76   to concatenate input strings separated by a glue string.
  77
  78 * :command:`target_compile_options` and :command:`add_compile_options`
  79   commands gained a ``SHELL:`` prefix to specify a group of related
  80   options using shell-like quoting.
  81
  82 * The :command:`target_link_libraries` command now supports
  83   :ref:`Object Libraries`.  Linking to an object library uses its object
  84   files in direct dependents and also propagates usage requirements.
  85
  86 Variables
  87 ---------
  88
  89 * The :variable:`CMAKE_FOLDER` variable was added to initialize the
  90   :prop_tgt:`FOLDER` property on all targets.
  91
  92 * The :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable
  93   was defined to initialize all
  94   :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target properties.
  95
  96 * ``CMAKE_PROJECT_VERSION*`` variables have been introduced:
  97
  98   - :variable:`CMAKE_PROJECT_VERSION`
  99   - :variable:`CMAKE_PROJECT_VERSION_MAJOR`
 100   - :variable:`CMAKE_PROJECT_VERSION_MINOR`
 101   - :variable:`CMAKE_PROJECT_VERSION_PATCH`
 102   - :variable:`CMAKE_PROJECT_VERSION_TWEAK`
 103
 104 * The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to
 105   support the :generator:`Ninja` and :ref:`Makefile Generators`.
 106   It is also now documented.
 107
 108 * ``CMAKE_VS_SDK_*_DIRECTORIES`` variables were defined to tell
 109   :ref:`Visual Studio Generators` for VS 2010 and above how to populate
 110   fields in ``.vcxproj`` files that specify SDK directories.  The
 111   variables are:
 112
 113   - :variable:`CMAKE_VS_SDK_EXCLUDE_DIRECTORIES`
 114   - :variable:`CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES`
 115   - :variable:`CMAKE_VS_SDK_INCLUDE_DIRECTORIES`
 116   - :variable:`CMAKE_VS_SDK_LIBRARY_DIRECTORIES`
 117   - :variable:`CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES`
 118   - :variable:`CMAKE_VS_SDK_REFERENCE_DIRECTORIES`
 119   - :variable:`CMAKE_VS_SDK_SOURCE_DIRECTORIES`
 120
 121 * A :variable:`MSVC_TOOLSET_VERSION` variable was added to provide the
 122   MSVC toolset version associated with the current MSVC compiler version
 123   in :variable:`MSVC_VERSION`.
 124
 125 Properties
 126 ----------
 127
 128 * The :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property was introduced
 129   to configure the use of managed C++ for :ref:`Visual Studio Generators`
 130   for VS 2010 and above.
 131   A corresponding :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` target
 132   property was added to support ``C++/CLI`` for imported targets.
 133
 134 * The :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property
 135   was introduced as replacement for
 136   :prop_tgt:`VS_DOTNET_TARGET_FRAMEWORK_VERSION`, which is considered
 137   deprecated now.
 138
 139 * An :prop_tgt:`EXPORT_PROPERTIES` target property was added to specify a
 140   custom list of target properties to include in targets exported by the
 141   :command:`install(EXPORT)` and :command:`export` commands.
 142
 143 * The :prop_tgt:`PDB_OUTPUT_DIRECTORY` property learned to support
 144   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 145
 146 * A :prop_dir:`TESTS` directory property was added to hold the list of
 147   tests defined by the :command:`add_test` command.
 148
 149 * A :prop_tgt:`VS_DEBUGGER_COMMAND` target property was created to set the
 150   debugging command line with :ref:`Visual Studio Generators` for VS 2010
 151   and above.
 152
 153 * HLSL source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS`
 154   and :prop_sf:`VS_SHADER_ENABLE_DEBUG` gained support for generator
 155   expressions.
 156
 157 * HLSL source file property :prop_sf:`VS_SHADER_OBJECT_FILE_NAME` has been
 158   added to the :ref:`Visual Studio Generators` for VS 2010 and above.
 159   The property specifies the file name of the compiled shader object.
 160
 161 Modules
 162 -------
 163
 164 * The :module:`FindALSA` module now provides imported targets.
 165
 166 * The :module:`FindCURL` module now provides imported targets.
 167
 168 * The :module:`FindJPEG` module now provides imported targets.
 169
 170 * The :module:`FindLibXml2` module now provides imported targets.
 171
 172 * The :module:`FindMatlab` module now supports the Matlab Runtime
 173   Compiler (MCR) for compiling and linking matlab extensions.
 174
 175 * A :module:`FindODBC` module was added to find an Open Database Connectivity
 176   (ODBC) library.
 177
 178 * The :module:`FindPkgConfig` module has learned to export the found
 179   libraries with full path for direct consumption with the
 180   :command:`target_link_libraries` command.
 181
 182 * New :module:`FindPython3` and :module:`FindPython2` modules, as well as
 183   a new :module:`FindPython` module, have been added to provide a new way
 184   to locate python environments.
 185
 186 * The :module:`UseSWIG` module gained a whole refresh and is now more
 187   consistent with standard CMake commands to generate libraries and is
 188   fully configurable through properties.
 189
 190 * The :module:`UseSWIG` module learned to manage multiple behaviors through
 191   ``UseSWIG_MODULE_VERSION`` variable to ensure legacy support as well as more
 192   robust handling of ``SWIG`` advanced features (like ``%template``).
 193
 194 * The :module:`UseSWIG` module learned to support CSHARP variant
 195   wrapper files.
 196
 197 * The :module:`WriteCompilerDetectionHeader` module gained a ``BARE_FEATURES``
 198   option to add a compatibility define for the exact keyword of a new language
 199   feature.
 200
 201 Generator Expressions
 202 ---------------------
 203
 204 * A new ``$<GENEX_EVAL:...>`` and ``$<TARGET_GENEX_EVAL:target,...>``
 205   :manual:`generator expression <cmake-generator-expressions(7)>`
 206   has been added to enable consumption of generator expressions whose
 207   evaluation results itself in generator expressions.
 208
 209 * A new ``$<IN_LIST:...>``
 210   :manual:`generator expression <cmake-generator-expressions(7)>`
 211   has been added.
 212
 213 * A new ``$<TARGET_EXISTS:...>``
 214   :manual:`generator expression <cmake-generator-expressions(7)>`
 215   has been added.
 216
 217 * A new ``$<TARGET_NAME_IF_EXISTS:...>``
 218   :manual:`generator expression <cmake-generator-expressions(7)>`
 219   has been added.
 220
 221 CTest
 222 -----
 223
 224 * The :command:`ctest_start` command has been reworked so that you can simply
 225   call ``ctest_start(APPEND)`` and it will read all the needed information from
 226   the TAG file. The argument parsing has also been relaxed so that the order of
 227   the arguments is less significant.
 228
 229 * A :prop_test:`PROCESSOR_AFFINITY` test property was added to request
 230   that CTest run a test with CPU affinity for a set of processors
 231   disjoint from other concurrently running tests with the property set.
 232
 233 CPack
 234 -----
 235
 236 * The :module:`CPack` module now uses variables
 237   :variable:`CMAKE_PROJECT_VERSION_MAJOR`,
 238   :variable:`CMAKE_PROJECT_VERSION_MINOR` and
 239   :variable:`CMAKE_PROJECT_VERSION_PATCH`
 240   to initialize corresponding CPack variables.
 241
 242 * A :cpack_gen:`CPack NuGet Generator` was was added with basic
 243   support for `NuGet`_.
 244
 245 .. _NuGet: https://docs.microsoft.com/en-us/nuget/what-is-nuget
 246
 247 Other
 248 -----
 249
 250 * The :manual:`Compile Features <cmake-compile-features(7)>` functionality
 251   is now aware of C++ 20.  No specific features are yet enumerated besides
 252   the ``cxx_std_20`` meta-feature.
 253
 254 * The :manual:`Compile Features <cmake-compile-features(7)>` functionality
 255   is now aware of the availability of C features in MSVC since VS 2010.
 256
 257 * The :manual:`Compile Features <cmake-compile-features(7)>` functionality
 258   is now aware of C language standards supported by Texas Instruments C
 259   compilers.
 260
 261 Deprecated and Removed Features
 262 ===============================
 263
 264 * The :generator:`Visual Studio 8 2005` generator has been removed.
 265
 266 * CMake no longer produces ``<tgt>_LIB_DEPENDS`` cache entries
 267   for library targets.  See policy :policy:`CMP0073`.
 268
 269 Other Changes
 270 =============
 271
 272 * Include flags for directories marked as ``SYSTEM`` are now moved after
 273   non-system directories.  The ``-isystem`` flag does this automatically,
 274   so moving them explicitly to the end makes the behavior consistent on
 275   compilers that do not have any ``-isystem`` flag.
 276
 277 * Fortran dependency scanning now supports dependencies implied by
 278   `Fortran Submodules`_.
 279
 280 * The existence and functionality of the file
 281   ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the
 282   :command:`install` documentation so that external packaging software can take
 283   advantage of CPack-style component installs.
 284
 285 * The :module:`CheckIncludeFile` module ``check_include_file`` macro
 286   learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
 287   See policy :policy:`CMP0075`.
 288
 289 * The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro
 290   learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
 291   See policy :policy:`CMP0075`.
 292
 293 * The :module:`CheckIncludeFiles` module ``check_include_files`` macro
 294   learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
 295   See policy :policy:`CMP0075`.
 296
 297 * The :manual:`cmake(1)` ``-E copy_directory`` tool now fails when the
 298   source directory does not exist.  Previously it succeeded by creating
 299   an empty destination directory.
 300
 301 * The :module:`UseSWIG` module :command:`swig_add_library` command
 302   (and legacy ``swig_add_module`` command) now set the prefix of
 303   Java modules to ``""`` for MINGW, MSYS, and CYGWIN environments.
 304
 305 .. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules