diff options
| -rw-r--r-- | Help/release/3.9.rst | 381 |
1 files changed, 207 insertions, 174 deletions
diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst index 57bdbf0..5169aa4 100644 --- a/Help/release/3.9.rst +++ b/Help/release/3.9.rst @@ -7,153 +7,155 @@ CMake 3.9 Release Notes Changes made since CMake 3.8 include the following. -* The :command:`add_custom_command` command learned to evaluate the - ``TARGET_OBJECTS`` - :manual:`generator expression <cmake-generator-expressions(7)>`. +New Features +============ + +Languages +--------- + +* ``CUDA`` is now supported by the :ref:`Visual Studio Generators` + for VS 2010 and above. This complements the existing support by the + :ref:`Makefile Generators` and the :generator:`Ninja` generator. + +Generators +---------- + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to support + the ``ASM_NASM`` language when ``nasm`` is installed. + +* The :generator:`Xcode` generator learned to create Xcode schema files. + This is an experimental feature and can be activated by setting the + :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value. + +Commands +-------- * The :command:`add_library` command ``IMPORTED`` option learned to support :ref:`Object Libraries`. -* The new target property :prop_tgt:`AUTOGEN_BUILD_DIR` was introduced which - allows to set a custom output directory for - :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC`. +* All ``find_`` commands now have a ``PACKAGE_ROOT`` search path group that + is first in the search heuristics. If a ``find_`` command is called from + inside a find module, then the CMake variable and environment variable named + ``<PackageName>_ROOT`` are used as prefixes and are the first set of paths + to be searched. -* Variable :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` was introduced to - allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names - for ``moc`` from the contents of source files. +* The :command:`find_library` command learned to search ``libx32`` paths + when the build targets the ``x32`` ABI. See the + :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property. -* The new target property :prop_tgt:`AUTOMOC_DEPEND_FILTERS` was introduced to - allow :prop_tgt:`AUTOMOC` to extract additional dependency file names - for ``moc`` from the contents of source files. +* The :command:`include_external_msproject` command learned to use + the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property + to map current configurations to the external configurations. -* When using :prop_tgt:`AUTOMOC`, CMake scans for the presence of the - ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the - macro's ``FILE`` argument changes. +* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to + specify where to install :ref:`Object Libraries`. -* When :prop_tgt:`AUTOMOC` detects an include statement of the form - ``#include "moc_<basename>.cpp"`` the respective header file is searched - for in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well. +* The :command:`install(EXPORT)` command learned how to export + :ref:`Object Libraries`. -* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`, - :prop_gbl:`AUTOMOC_SOURCE_GROUP` and - :prop_gbl:`AUTORCC_SOURCE_GROUP` were - introduced to allow files generated by :prop_tgt:`AUTOMOC` or - :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`. +* The :command:`project` command learned an optional ``DESCRIPTION`` + parameter to set the :variable:`PROJECT_DESCRIPTION` variable. -* Variable :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` was introduced to - allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more - places than the vicinity of the ``ui_foo.h`` including file. +* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode + that performs argument separation depending on the host operating system. -* The new target property :prop_tgt:`AUTOUIC_SEARCH_PATHS` was introduced to - allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more - places than the vicinity of the ``ui_foo.h`` including file. +Variables +--------- -* Two new informational generator expressions to retrieve Apple Bundle - directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>`` - outputs the full path to the Bundle directory, the other one - ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the - ``Contents`` directory of macOS Bundles and App Bundles. For all other - bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``. +* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to + allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. - Those new expressions are helpful to query Bundle locations independent of - the different Bundle types and layouts on macOS and iOS. +* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to + allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the file including ``ui_foo.h``. -* A :module:`CheckIPOSupported` module was added to help projects - check whether interprocedural optimization (IPO) is supported by - the current toolchain and CMake version. +* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to + tell the :command:`find_library` command to search in a ``lib<suffix>`` + directory before each ``lib`` directory that would normally be searched. * A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all targets. -* The :generator:`Xcode` generator got the ability to create schema files. - This is still an experimental feature and can be activated by setting the - :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value. - * A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold the path to the GCC/Clang wrapper of ``ar``. * A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold the path to the GCC/Clang wrapper of ``ranlib``. -* The :module:`CPackArchive` module learned to modify filename per component. - See :variable:`CPACK_ARCHIVE_FILE_NAME` variable and its per component - version. +* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK` + variables were added to use separate sysroots for compiling and linking. -* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and - :command:`cpack_ifw_configure_component_group` commands gained a - internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION`` options - to more specific configuration. +Properties +---------- -* The :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT` - variable for finding the QtIFW tool suite installed in a non-standard place. -* The :module:`CPackIFW` module tries to find and use QtIFW tools of the `3.0` - and `3.1` versions. +* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set + a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`, + and :prop_tgt:`AUTORCC`. -* The :module:`CPackRPM` module learned to modify debuginfo package name. - See :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. +* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to + allow :prop_tgt:`AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. -* A :prop_test:`DISABLED` test property was added to mark tests that - are configured but explicitly disabled so they do not run. +* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to + allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the file including ``ui_foo.h``. -* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option - to specify custom headers to send during submission. +* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`, + :prop_gbl:`AUTOMOC_SOURCE_GROUP` and + :prop_gbl:`AUTORCC_SOURCE_GROUP` were + introduced to allow files generated by :prop_tgt:`AUTOMOC` or + :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`. -* When running tests, CTest learned to treat skipped tests (using the - :prop_test:`SKIP_RETURN_CODE` property) the same as tests with the - :prop_test:`DISABLED` property. Due to this change, CTest will not indicate - failure when all tests are either skipped or pass. +* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding + :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to + control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property + value for binaries in the build tree. This is for macOS ``install_name`` + as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``. -* ``CUDA`` is now supported by the :ref:`Visual Studio Generators` - for VS 2010 and above. +* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to + :ref:`Object Libraries` to support compiling to ``.ptx`` files + instead of host object files. -* An explicit deprecation diagnostic was added for policies ``CMP0036`` - and below. The :manual:`cmake-policies(7)` manual explains that the - OLD behaviors of all policies are deprecated and that projects should - port to the NEW behaviors. +* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was + added to determine whether the current generator is a multi-configuration + generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`). -* The :module:`FindDoxygen` module learned to control Doxygen behavior using - CMake variables and generate documentation via the newly added - :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``) - is automatically generated and doxygen is run as part of a custom target. - A number of doxygen-related variables have been deprecated. Additional - components can be specified to find optional tools: ``dot``, ``mscgen`` - and ``dia``. +* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced + when enabled. CMake will add IPO flags unconditionally or produce an error + if it does not know the flags for the current compiler. The project is now + responsible to use the :module:`CheckIPOSupported` module to check for IPO + support before enabling the target property. See policy :policy:`CMP0069`. -* The :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to - :ref:`Object Libraries` to support compiling to ``.ptx`` files - instead of host object files. +* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now + be used in combination with explicit ``.def`` files in order to + export all symbols from the object files within a target plus + an explicit list of symbols that the linker finds in dependencies + (e.g. ``msvcrt.lib``). -* The :manual:`ctest(1)` executable gained new options which allow the - developer to disable automatically adding tests to the test set to satisfy - fixture dependencies. ``-FS`` prevents adding setup tests for fixtures - matching the provided regular expression, ``-FC`` prevents adding cleanup - tests for matching fixtures and ``-FA`` prevents adding any test for matching - fixtures. +Modules +------- -* A new :module:`GoogleTest` module was added to provide the - :command:`gtest_add_tests` function independently of the :module:`FindGTest` - module. The function was also updated to support keyword arguments, with - functionality expanded to allow a test name prefix and suffix to be - specified, the dependency on the source files to be optional and the list of - discovered test cases to be returned to the caller. +* A :module:`CheckIPOSupported` module was added to help projects + check whether interprocedural optimization (IPO) is supported by + the current toolchain and CMake version. -* The :command:`feature_summary` command in the :module:`FeatureSummary` module +* The :module:`FeatureSummary` module :command:`feature_summary` command now accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default title for the selected package type. -* The global property :variable:`FeatureSummary_<TYPE>_DESCRIPTION` can be - defined for each ``<TYPE>`` to replace the type name with the specified string - whenever the package type is used in an output string by the - :module:`FeatureSummary` module. +* The :module:`FeatureSummary` module gained a new + :variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that can be defined + for each ``<TYPE>`` to replace the type name with the specified string + whenever the package type is used in an output string by the module. -* The :command:`file(GENERATE)` subcommand learned to evaluate the - ``TARGET_OBJECTS`` - :manual:`generator expression <cmake-generator-expressions(7)>`. - -* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to - tell the :command:`find_library` command to search in a ``lib<suffix>`` - directory before each ``lib`` directory that would normally be searched. +* The :module:`FindDoxygen` module learned to control Doxygen behavior using + CMake variables and generate documentation via the newly added + :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``) + is automatically generated and doxygen is run as part of a custom target. + Additional components can be specified to find optional tools: ``dot``, + ``mscgen`` and ``dia``. * The :module:`FindMPI` module now provides imported targets. @@ -167,105 +169,136 @@ Changes made since CMake 3.8 include the following. * The :module:`FindProtobuf` module now provides imported targets when the libraries are found. -* Interprocedural optimization (IPO) is now supported for GNU - compilers using link time optimization (LTO) flags. See the - :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and - :module:`CheckIPOSupported` module. - -* The :command:`include_external_msproject` command learned to use - the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property - to map current configurations to the external configurations. - -* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding - :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to - control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property - value for binaries in the build tree. This is for macOS ``install_name`` - as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``. - -* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` - no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. - -* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to - specify where to install :ref:`Object Libraries`. +* A new :module:`GoogleTest` module was added to provide the + :command:`gtest_add_tests` function independently of the :module:`FindGTest` + module. The function was also updated to support keyword arguments, with + functionality expanded to allow a test name prefix and suffix to be + specified, the dependency on the source files to be optional and the list of + discovered test cases to be returned to the caller. -* The :command:`install(EXPORT)` command learned how to export - :ref:`Object Libraries`. +CTest +----- -* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced - when enabled. CMake will add IPO flags unconditionally or produce an error - if it does not know the flags for the current compiler. The project is now - responsible to use the :module:`CheckIPOSupported` module to check for IPO - support before enabling the target property. See policy :policy:`CMP0069`. +* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option + to specify custom headers to send during submission. -* On macOS the default application bundle ``Info.plist`` file now enables - Hi-DPI support. +* The :manual:`ctest(1)` executable gained new options which allow the + developer to disable automatically adding tests to the test set to satisfy + fixture dependencies. ``-FS`` prevents adding setup tests for fixtures + matching the provided regular expression, ``-FC`` prevents adding cleanup + tests for matching fixtures and ``-FA`` prevents adding any test for matching + fixtures. -* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now - be used in combination with explicit ``.def`` files in order to - export all symbols from the object files within a target plus - an explicit list of symbols that the linker finds in dependencies - (e.g. ``msvcrt.lib``). +* A :prop_test:`DISABLED` test property was added to mark tests that + are configured but explicitly disabled so they do not run. -* The :generator:`Ninja` generator has loosened dependencies on object - compilation to depend on the custom targets and commands of dependent - libraries instead of the libraries themselves. This helps projects with deep - dependency graphs to be blocked only on their link steps at the deeper - levels rather than also blocking object compilation on dependent link steps. +CPack +----- -* All ``find_`` commands now have a `PACKAGE_ROOT` search path group that is - first in the search heuristics. If the ``find_`` command is called from - inside a find module, then the CMake and environment variables - ``<PackageName>_ROOT`` are used as prefixes and are the first set of paths - that are searched. +* The :module:`CPackArchive` module learned to modify the filename + per-component. See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and + its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`. * The :module:`CPackComponent` module :command:`cpack_add_component` command gained a new ``PLIST <filename>`` option to specify the ``pkgbuild`` ``--component-plist`` argument when using the :module:`productbuild <CPackProductBuild>` generator. +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands gained + internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION`` + options. + +* The :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT` + variable for finding the QtIFW tool suite installed in a non-standard place. + * The :module:`CPackProductBuild` module gained a new :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to specify resources to be copied into the ``Resources`` directory. -* The :command:`project` command learned an optional ``DESCRIPTION`` parameter. - See :command:`project` command and :variable:`PROJECT_DESCRIPTION` variable. +* The :module:`CPackRPM` module learned to modify the ``debuginfo`` package + name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. -* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was - added to determine whether the current generator is a multi-configuration - generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`). +* The :module:`CPackWIX` module patching system now has the ability to set + additional attributes. This can be done by specifying attributes with + the ``CPackWiXFragment`` XML tag after the ``Id`` attribute. + See the :variable:`CPACK_WIX_PATCH_FILE` variable. + +* The CPack WIX generator implemented a new + :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows + using a custom root folder ID instead of the default + ``ProgramFilesFolder`` / ``ProgramFiles64Folder``. + +Other +----- + +* Interprocedural optimization (IPO) is now supported for GNU and Clang + compilers using link time optimization (LTO) flags. See the + :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and + :module:`CheckIPOSupported` module. + +* The ``TARGET_OBJECTS`` + :manual:`generator expression <cmake-generator-expressions(7)>` + is now supported by the :command:`add_custom_command` and + :command:`file(GENERATE)` commands. + +* Two new informational generator expressions to retrieve Apple Bundle + directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>`` + outputs the full path to the Bundle directory, the other one + ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the + ``Contents`` directory of macOS Bundles and App Bundles. For all other + bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``. + The new expressions are helpful to query Bundle locations independent of + the different Bundle types and layouts on macOS and iOS. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0036`` + and below. The :manual:`cmake-policies(7)` manual explains that the + OLD behaviors of all policies are deprecated and that projects should + always port to the NEW behaviors as soon as possible. + +* The :generator:`Visual Studio 8 2005` generator is now deprecated + and will be removed in a future version of CMake. * The :generator:`Visual Studio 7 .NET 2003` generator has been removed. * The :generator:`Xcode` generator dropped support for Xcode versions older than 3. -* A ``NATIVE_COMMAND`` mode was added to :command:`separate_arguments` - performing argument separation depening on the host operating system. - -* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK` - variables were added to use separate sysroots for compiling and linking. +* The :module:`FindDoxygen` module has deprecated several variables. * The version of curl bundled with CMake no longer accepts URLs of the form ``file://c:/...`` on Windows due to a change in upstream curl 7.52. Use the form ``file:///c:/...`` instead to work on all versions. -* The :generator:`Visual Studio 8 2005` generator is now deprecated - and will be removed in a future version of CMake. +Other Changes +============= -* :ref:`Visual Studio Generators` for VS 2010 and above learned to support - the ``ASM_NASM`` language when ``nasm`` is installed. +* When using :prop_tgt:`AUTOMOC`, CMake now scans for the presence of the + ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the + macro's ``FILE`` argument changes. -* The patching system within the :module:`CPackWIX` module now allows the - ability to set additional attributes. This can be done by specifying - addional attributes with the ``CPackWiXFragment`` XML tag after the - ``Id`` attribute. See the :variable:`CPACK_WIX_PATCH_FILE` variable. +* When :prop_tgt:`AUTOMOC` detects an include statement of the form + ``#include "moc_<basename>.cpp"`` the search for the respective header file + now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well. -* The CPack WIX generator implemented a new - :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows - using a custom root folder ID instead of the default - ``ProgramFilesFolder`` / ``ProgramFiles64Folder``. +* When running tests, CTest learned to treat skipped tests (using the + :prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new + :prop_test:`DISABLED` property. Due to this change, CTest will not indicate + failure when all tests are either skipped or pass. -* The :command:`find_library` command learned to search ``libx32`` paths - when the build targets the ``x32`` ABI. See the - :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property. +* The :generator:`Ninja` generator has loosened the dependencies of object + compilation. Object compilation now depends only on custom targets + and custom commands associated with libraries on which the object's target + depends and no longer depends on the libraries themselves. Source files + in dependent targets may now compile without waiting for their targets' + dependencies to link. + +* On macOS, the default application bundle ``Info.plist`` file now enables + Hi-DPI support. + +* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` + no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. |