Help/release/3.4.rst

   1 CMake 3.4 Release Notes
   2 ***********************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.3 include the following.
   9
  10 New Features
  11 ============
  12
  13 Generators
  14 ----------
  15
  16 * The :generator:`Visual Studio 14 2015` generator learned to select
  17   a Windows 10 SDK based on the value of the :variable:`CMAKE_SYSTEM_VERSION`
  18   variable and the SDKs available on the host.
  19
  20 * CMake learned rudimentary support for the Apple Swift language.  When using
  21   the :generator:`Xcode` generator with Xcode 6.1 or higher, one may enable
  22   the ``Swift`` language with the :command:`enable_language` command or the
  23   :command:`project` command (this is an error with other generators or when
  24   Xcode is too old).  Then one may list ``.swift`` source files in targets
  25   for compilation.
  26
  27 Commands
  28 --------
  29
  30 * The :command:`find_program` command learned a ``NAMES_PER_DIR``
  31   option to consider all given ``NAMES`` in each directory before
  32   moving on to the next directory.
  33
  34 * The :command:`get_filename_component` command learned a new ``BASE_DIR``
  35   subcommand.  This is used to specify a base directory when calculating an
  36   absolute path from a relative path.
  37
  38 * The :command:`if` command learned a new ``TEST`` operator that evaluates
  39   to true if a given test name has been defined by the :command:`add_test`
  40   command.  See policy :policy:`CMP0064`.
  41
  42 * The :command:`install(DIRECTORY)` command ``DESTINATION`` option learned to
  43   support :manual:`generator expressions <cmake-generator-expressions(7)>`.
  44
  45 * The :command:`install(FILES)` command ``DESTINATION`` option learned to
  46   support :manual:`generator expressions <cmake-generator-expressions(7)>`.
  47
  48 * The :command:`string` command learned a new ``APPEND`` subcommand.
  49
  50 Variables
  51 ---------
  52
  53 * The :ref:`Makefile Generators` and the :generator:`Ninja` generator
  54   learned to add compiler launcher tools like distcc and ccache along
  55   with the compiler for ``C`` and ``CXX`` languages.  See the
  56   :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
  57   :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
  58
  59 * New :variable:`CMAKE_LINK_SEARCH_START_STATIC` and
  60   :variable:`CMAKE_LINK_SEARCH_END_STATIC` variables were
  61   introduced to initialize the
  62   :prop_tgt:`LINK_SEARCH_START_STATIC` and
  63   :prop_tgt:`LINK_SEARCH_END_STATIC` target properties,
  64   respectively.
  65
  66 Properties
  67 ----------
  68
  69 * :ref:`Visual Studio Generators` learned to support additional
  70   target properties to customize projects for NVIDIA Nsight
  71   Tegra Visual Studio Edition:
  72
  73   * :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS`
  74   * :prop_tgt:`ANDROID_ARCH`
  75   * :prop_tgt:`ANDROID_ASSETS_DIRECTORIES`
  76   * :prop_tgt:`ANDROID_JAR_DEPENDENCIES`
  77   * :prop_tgt:`ANDROID_JAR_DIRECTORIES`
  78   * :prop_tgt:`ANDROID_JAVA_SOURCE_DIR`
  79   * :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES`
  80   * :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES`
  81   * :prop_tgt:`ANDROID_PROCESS_MAX`
  82   * :prop_tgt:`ANDROID_PROGUARD`
  83   * :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH`
  84   * :prop_tgt:`ANDROID_SECURE_PROPS_PATH`
  85   * :prop_tgt:`ANDROID_SKIP_ANT_STEP`
  86   * :prop_tgt:`ANDROID_STL_TYPE`
  87
  88 * The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
  89   :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
  90   :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties learned to
  91   support :manual:`generator expressions <cmake-generator-expressions(7)>`.
  92
  93 * The :prop_tgt:`SOURCE_DIR` and :prop_tgt:`BINARY_DIR` target properties
  94   were introduced to allow project code to query where a target is defined.
  95
  96 * The :prop_tgt:`OUTPUT_NAME` target property and its variants learned to
  97   support :manual:`generator expressions <cmake-generator-expressions(7)>`.
  98
  99 * A :prop_gbl:`TARGET_MESSAGES` global property was added to tell the
 100   :ref:`Makefile Generators` whether to generate commands to print output
 101   after each target is completed.
 102
 103 * On Windows with MS-compatible tools, CMake learned to optionally
 104   generate a module definition (``.def``) file for ``SHARED`` libraries.
 105   See the :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property.
 106
 107 Modules
 108 -------
 109
 110 * The :module:`ExternalProject` module :command:`ExternalProject_Add`
 111   function ``GIT_SUBMODULES`` option now also limits the set of
 112   submodules that are initialized in addition to the prior behavior
 113   of limiting the set of submodules that are updated.
 114
 115 * The :module:`ExternalProject` module learned new ``USES_TERMINAL``
 116   arguments for giving steps exclusive terminal access.  This is
 117   useful with the :generator:`Ninja` generator to monitor CMake
 118   superbuild progress and prevent CPU oversubscription.
 119
 120 * The :module:`FindBISON` module ``BISON_TARGET`` macro learned a
 121   new ``DEFINES_FILE`` option to specify a custom output header
 122   to be generated.
 123
 124 * The :module:`FindHDF5` module learend a new ``HDF5_PREFER_PARALLEL``
 125   option allowing users to specify that a parallel HDF5 tool is
 126   preferred if both are available.
 127
 128 * The :module:`FindIce` module now provides imported targets.
 129
 130 * The :module:`FindJava` module learned to optionally find
 131   the ``idlj`` and ``jarsigner`` tools.
 132
 133 * The :module:`FindOpenSSL` module now provides imported targets.
 134
 135 * The :module:`FindOpenSSL` module learned a new ``OPENSSL_USE_STATIC_LIBS``
 136   option to search only for static libraries.
 137
 138 * The :module:`FindPkgConfig` learned a new :command:`pkg_get_variable`
 139   command which may be used to query for arbitrary variables from a package
 140   (such as for related tools or data and plugin install paths).
 141
 142 * The :module:`FindProtobuf` module gained a new
 143   :command:`protobuf_generate_python` function to generate python
 144   sources from ``.proto`` files.
 145
 146 * The :module:`FindTIFF` module learned to search separately for
 147   debug and release variants.
 148
 149 * The :module:`FindwxWidgets` module learned to support version requests.
 150
 151 * The :module:`FindXercesC` module learned to search separately for
 152   debug and release variants.
 153
 154 * The :module:`FindZLIB` module learned to search separately for
 155   debug and release variants.
 156
 157 * The :module:`GNUInstallDirs` module learned special default values
 158   for certain installation prefixes according to the `GNU Coding
 159   Standards`_ and the `Filesystem Hierarchy Standard`_.
 160
 161 * The :module:`UseJava` module ``add_jar`` function learned
 162   to support response files (e.g. ``@srcs.txt``) for source
 163   specification.
 164
 165 * The :module:`UseJava` module ``install_jar`` function learned
 166   new ``DESTINATION`` and ``COMPONENT`` options to specify
 167   the corresponding :command:`install` command options.
 168
 169 * The :module:`UseJava` module gained a new ``create_javah``
 170   function to create C headers from Java classes.
 171
 172 .. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
 173 .. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
 174
 175 Generator Expressions
 176 ---------------------
 177
 178 * A new ``$<SHELL_PATH:...>``
 179   :manual:`generator expression <cmake-generator-expressions(7)>`
 180   has been added.
 181
 182 CTest
 183 -----
 184
 185 * CTest learned to optionally measure the CPU load during parallel
 186   testing and avoid starting tests that may cause the load to exceed
 187   a given threshold.  See the :manual:`ctest(1)` command ``--test-load``
 188   option, the ``TestLoad`` setting of the :ref:`CTest Test Step`,
 189   the :variable:`CTEST_TEST_LOAD` variable, and the ``TEST_LOAD``
 190   option of the :command:`ctest_test` command.
 191
 192 * :manual:`ctest(1)` learned options
 193   ``--test-output-size-passed`` and ``--test-output-size-failed``
 194   to customize the limit on test output size submitted when
 195   running as a :ref:`Dashboard Client`.
 196
 197 CPack
 198 -----
 199
 200 * The :cpack_gen:`CPack DEB Generator` learned to set package dependencies
 201   per component.  See variables:
 202
 203   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`
 204   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`
 205   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`
 206   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`
 207   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`
 208   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`
 209   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`
 210   * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`
 211
 212 * The :module:`CPack` module learned to package empty directories.
 213
 214 * The :module:`CPack` module gained a new setting, ``CPACK_VERBATIM_VARIABLES``,
 215   which can be used to ensure the cpack program receives the settings' values
 216   exactly as they were set, even if they contain CMake-special characters.
 217   For compatibility, it's off by default.
 218
 219 Other
 220 -----
 221
 222 * The :manual:`Compile Features <cmake-compile-features(7)>` functionality
 223   is now aware of features supported by GNU C compilers on Windows.
 224
 225 * CMake learned to honor ``*.manifest`` source files with MSVC tools.
 226   Manifest files named as sources of ``.exe`` and ``.dll`` targets
 227   will be merged with linker-generated manifests and embedded in the
 228   binary.
 229
 230 * The `Concurrent Fortran 77 <https://ccur.com>`__ compiler is now supported.
 231   Its :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` is ``CCur``.
 232
 233 * :manual:`cmake(1)` gained a new ``--trace-expand`` command line option
 234   that is like ``--trace`` but expands variable references in the output.
 235
 236 Deprecated and Removed Features
 237 ===============================
 238
 239 * The :module:`CMakeExpandImportedTargets` module is now documented
 240   as deprecated.  See module documentation for an explanation.
 241
 242 * The :variable:`CMAKE_USE_RELATIVE_PATHS` variable no longer has any
 243   effect.  Previously it was partially implemented and unreliable.
 244
 245 Other Changes
 246 =============
 247
 248 * The :module:`CheckFunctionExists`, :module:`CheckLibraryExists`,
 249   :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to
 250   work in environments where only CXX is enabled.
 251
 252 * The :cpack_gen:`CPack DEB Generator` now correctly excludes symlinks
 253   during package checksum calculation.
 254
 255 * The :cpack_gen:`CPack DEB Generator` no longer uses fakeroot and
 256   system tar program for packaging.
 257
 258 * The :module:`CPack` module no longer mangles settings with CMake-special
 259   characters when they're used as defaults for other settings. The macro
 260   ``cpack_set_if_not_set``, which was responsible for this, is now deprecated.
 261
 262 * CMake no longer links executables with flags to export symbols
 263   unless the :prop_tgt:`ENABLE_EXPORTS` target property is set.
 264   See policy :policy:`CMP0065`.
 265
 266 * The ``SONAME`` field is no longer set for ``MODULE`` libraries
 267   created with the :command:`add_library` command.  ``MODULE``
 268   libraries are meant for explicit dynamic loading at runtime.
 269   They cannot be linked so ``SONAME`` is not useful.
 270
 271 * The internal :variable:`CMAKE_<LANG>_COMPILE_OBJECT` rule variable now
 272   substitutes compiler include flags in a separate ``<INCLUDES>`` placeholder
 273   instead of the main ``<FLAGS>`` placeholder.