1CMake 3.9 Release Notes 2*********************** 3 4.. only:: html 5 6 .. contents:: 7 8Changes made since CMake 3.8 include the following. 9 10New Features 11============ 12 13Languages 14--------- 15 16* ``CUDA`` is now supported by the :ref:`Visual Studio Generators` 17 for VS 2010 and above. This complements the existing support by the 18 :ref:`Makefile Generators` and the :generator:`Ninja` generator. 19 CUDA 8.0.61 or higher is recommended due to known bugs in the VS 20 integration by earlier versions. 21 22* CMake is now aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and 23 :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features for 24 the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>`: ``Cray``, 25 ``PGI``, and ``XL``. 26 27Generators 28---------- 29 30* :ref:`Visual Studio Generators` for VS 2010 and above learned to support 31 the ``ASM_NASM`` language when ``nasm`` is installed. 32 33* The :generator:`Xcode` generator learned to create Xcode schema files. 34 This is an experimental feature and can be activated by setting the 35 :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value. 36 37Commands 38-------- 39 40* The :command:`add_library` command ``IMPORTED`` option learned to support 41 :ref:`Object Libraries`. 42 43* The :command:`find_library` command learned to search ``libx32`` paths 44 when the build targets the ``x32`` ABI. See the 45 :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property. 46 47* The :command:`include_external_msproject` command learned to use 48 the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property 49 to map current configurations to the external configurations. 50 51* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to 52 specify where to install :ref:`Object Libraries`. 53 54* The :command:`install(EXPORT)` command learned how to export 55 :ref:`Object Libraries`. 56 57* The :command:`project` command learned an optional ``DESCRIPTION`` 58 parameter to set the :variable:`PROJECT_DESCRIPTION` variable. 59 60* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode 61 that performs argument separation depending on the host operating system. 62 63Variables 64--------- 65 66* A :variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` variable was added 67 for use when :ref:`Cross Compiling for Android with the NDK` to request 68 use of the deprecated headers even when unified headers are available. 69 The default is now to use unified headers if available. 70 71* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to 72 allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names 73 for ``moc`` from the contents of source files. 74 75* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to 76 allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more 77 places than the vicinity of the file including ``ui_foo.h``. 78 79* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to 80 tell the :command:`find_library` command to search in a ``lib<suffix>`` 81 directory before each ``lib`` directory that would normally be searched. 82 83* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to 84 initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all 85 targets. 86 87* A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold 88 the path to the GCC/Clang wrapper of ``ar``. 89 90* A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold 91 the path to the GCC/Clang wrapper of ``ranlib``. 92 93* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK` 94 variables were added to use separate sysroots for compiling and linking. 95 96Properties 97---------- 98 99* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set 100 a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`, 101 and :prop_tgt:`AUTORCC`. 102 103* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to 104 allow :prop_tgt:`AUTOMOC` to extract additional dependency file names 105 for ``moc`` from the contents of source files. 106 107* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to 108 allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more 109 places than the vicinity of the file including ``ui_foo.h``. 110 111* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`, 112 :prop_gbl:`AUTOMOC_SOURCE_GROUP` and 113 :prop_gbl:`AUTORCC_SOURCE_GROUP` were 114 introduced to allow files generated by :prop_tgt:`AUTOMOC` or 115 :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`. 116 117* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding 118 :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to 119 control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property 120 value for binaries in the build tree. This is for macOS ``install_name`` 121 as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``. 122 123* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to 124 :ref:`Object Libraries` to support compiling to ``.ptx`` files 125 instead of host object files. 126 127* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was 128 added to determine whether the current generator is a multi-configuration 129 generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`). 130 131* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced 132 when enabled. CMake will add IPO flags unconditionally or produce an error 133 if it does not know the flags for the current compiler. The project is now 134 responsible to use the :module:`CheckIPOSupported` module to check for IPO 135 support before enabling the target property. See policy :policy:`CMP0069`. 136 137* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now 138 be used in combination with explicit ``.def`` files in order to 139 export all symbols from the object files within a target plus 140 an explicit list of symbols that the linker finds in dependencies 141 (e.g. ``msvcrt.lib``). 142 143Modules 144------- 145 146* A :module:`CheckIPOSupported` module was added to help projects 147 check whether interprocedural optimization (IPO) is supported by 148 the current toolchain and CMake version. 149 150* The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro 151 now forwards all arguments to the underlying :command:`find_package` 152 call. Existing uses will continue to function as before, but callers can 153 now access the full suite of arguments that :command:`find_package` accepts. 154 155* The :module:`FeatureSummary` module :command:`feature_summary` command now 156 accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default 157 title for the selected package type. 158 159* The :module:`FeatureSummary` module gained a new 160 :variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that can be defined 161 for each ``<TYPE>`` to replace the type name with the specified string 162 whenever the package type is used in an output string by the module. 163 164* The :module:`FindDoxygen` module learned to control Doxygen behavior using 165 CMake variables and generate documentation via the newly added 166 :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``) 167 is automatically generated and doxygen is run as part of a custom target. 168 Additional components can be specified to find optional tools: ``dot``, 169 ``mscgen`` and ``dia``. 170 171* The :module:`FindMPI` module now provides imported targets. 172 173* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp` 174 command gained an ``EXPORT_MACRO`` option to specify the name of 175 a DLL export markup macro. 176 177* The :module:`FindProtobuf` module now supports usage of static libraries 178 for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable. 179 180* The :module:`FindProtobuf` module now provides imported targets 181 when the libraries are found. 182 183* A new :module:`GoogleTest` module was added to provide the 184 :command:`gtest_add_tests` function independently of the :module:`FindGTest` 185 module. The function was also updated to support keyword arguments, with 186 functionality expanded to allow a test name prefix and suffix to be 187 specified, the dependency on the source files to be optional and the list of 188 discovered test cases to be returned to the caller. 189 190CTest 191----- 192 193* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option 194 to specify custom headers to send during submission. 195 196* The :manual:`ctest(1)` executable gained new options which allow the 197 developer to disable automatically adding tests to the test set to satisfy 198 fixture dependencies. ``-FS`` prevents adding setup tests for fixtures 199 matching the provided regular expression, ``-FC`` prevents adding cleanup 200 tests for matching fixtures and ``-FA`` prevents adding any test for matching 201 fixtures. 202 203* A :prop_test:`DISABLED` test property was added to mark tests that 204 are configured but explicitly disabled so they do not run. 205 206CPack 207----- 208 209* The :cpack_gen:`CPack Archive Generator` learned to modify the filename 210 per-component. See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and 211 its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`. 212 213* The :module:`CPackComponent` module :command:`cpack_add_component` command 214 gained a new ``PLIST <filename>`` option to specify the ``pkgbuild`` 215 ``--component-plist`` argument when using the 216 :module:`productbuild <CPackProductBuild>` generator. 217 218* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and 219 :command:`cpack_ifw_configure_component_group` commands gained 220 internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION`` 221 options. 222 223* The :cpack_gen:`CPack IFW Generator` learned the new hint 224 :variable:`CPACK_IFW_ROOT` variable for finding the QtIFW tool suite 225 installed in a non-standard place. 226 227* The :cpack_gen:`CPack productbuild Generator` gained a new 228 :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to 229 specify resources to be copied into the ``Resources`` 230 directory. 231 232* The :cpack_gen:`CPack RPM Generator` learned to modify the ``debuginfo`` 233 package name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. 234 235* The :cpack_gen:`CPack WIX Generator` patching system now has the 236 ability to set additional attributes. This can be done by specifying 237 attributes with the ``CPackWiXFragment`` XML tag after the ``Id`` attribute. 238 See the :variable:`CPACK_WIX_PATCH_FILE` variable. 239 240* The :cpack_gen:`CPack WIX Generator` implemented a new 241 :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows 242 using a custom root folder ID instead of the default 243 ``ProgramFilesFolder`` / ``ProgramFiles64Folder``. 244 245Other 246----- 247 248* Interprocedural optimization (IPO) is now supported for GNU and Clang 249 compilers using link time optimization (LTO) flags. See the 250 :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and 251 :module:`CheckIPOSupported` module. 252 253* The ``TARGET_OBJECTS`` 254 :manual:`generator expression <cmake-generator-expressions(7)>` 255 is now supported by the :command:`add_custom_command` and 256 :command:`file(GENERATE)` commands. 257 258* Two new informational generator expressions to retrieve Apple Bundle 259 directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>`` 260 outputs the full path to the Bundle directory, the other one 261 ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the 262 ``Contents`` directory of macOS Bundles and App Bundles. For all other 263 bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``. 264 The new expressions are helpful to query Bundle locations independent of 265 the different Bundle types and layouts on macOS and iOS. 266 267Deprecated and Removed Features 268=============================== 269 270* An explicit deprecation diagnostic was added for policies ``CMP0036`` 271 and below. The :manual:`cmake-policies(7)` manual explains that the 272 OLD behaviors of all policies are deprecated and that projects should 273 always port to the NEW behaviors as soon as possible. 274 275* The :generator:`Visual Studio 8 2005` generator is now deprecated 276 and will be removed in a future version of CMake. 277 278* The :generator:`Visual Studio 7 .NET 2003` generator has been removed. 279 280* The :generator:`Xcode` generator dropped support for Xcode versions 281 older than 3. 282 283* The :module:`FindDoxygen` module has deprecated several variables. 284 285* The version of curl bundled with CMake no longer accepts URLs of the form 286 ``file://c:/...`` on Windows due to a change in upstream curl 7.52. Use 287 the form ``file:///c:/...`` instead to work on all versions. 288 289Other Changes 290============= 291 292* When using :prop_tgt:`AUTOMOC`, CMake now scans for the presence of the 293 ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the 294 macro's ``FILE`` argument changes. 295 296* When :prop_tgt:`AUTOMOC` detects an include statement of the form 297 ``#include "moc_<basename>.cpp"`` the search for the respective header file 298 now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well. 299 300* When running tests, CTest learned to treat skipped tests (using the 301 :prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new 302 :prop_test:`DISABLED` property. Due to this change, CTest will not indicate 303 failure when all tests are either skipped or pass. 304 305* The :generator:`Ninja` generator has loosened the dependencies of object 306 compilation. Object compilation now depends only on custom targets 307 and custom commands associated with libraries on which the object's target 308 depends and no longer depends on the libraries themselves. Source files 309 in dependent targets may now compile without waiting for their targets' 310 dependencies to link. 311 312* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` 313 no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. 314 315* The :generator:`Visual Studio 14 2015` generator has been taught about 316 a change to the ``v140`` toolset made by a VS 2015 update. VS changed 317 the set of values it understands for the ``GenerateDebugInformation`` 318 linker setting that produces the ``-DEBUG`` linker flag variants. 319 320Updates 321======= 322 323Changes made since CMake 3.9.0 include the following. 324 3253.9.1 326----- 327 328* The ``find_`` command ``PACKAGE_ROOT`` search path group added by 329 CMake 3.9.0 has been removed for the 3.9 series due to regressions 330 caused by new use of ``<PackageName>_ROOT`` variables. The behavior 331 may be re-introduced in the future in a more-compatible way. 332 3333.9.2 334----- 335 336* On macOS, the default application bundle ``Info.plist`` file no longer 337 enables Hi-DPI support as it did in 3.9.0 and 3.9.1. The change had 338 to be reverted because it broke iOS applications. 339 340* The Xcode generator no longer adds "outputPaths" to custom script 341 build phases as it did in 3.9.0 and 3.9.1. This was added in an 342 attempt to support Xcode 9's new build system, but broke incremental 343 rebuilds for both the old and new Xcode build systems. 344