Help/release/3.3.rst

   1 CMake 3.3 Release Notes
   2 ***********************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.2 include the following.
   9
  10 New Features
  11 ============
  12
  13 Generators
  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
  31 Commands
  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
  60 Variables
  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
  72 Properties
  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
  94 Modules
  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
 149 Generator 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
 159 CTest
 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
 169 CPack
 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
 202 Other
 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
 217 Deprecated 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
 265 Other 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`.