From 049cc31d840dd0019d5fdd5e29877cff73b3424e Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 4 Jun 2018 11:43:15 -0400 Subject: Help: Organize and revise 3.12 release notes Add section headers similar to the 3.11 release notes and move each individual bullet into an appropriate section. Revise a few bullets. --- Help/release/3.12.rst | 371 ++++++++++++++++++++++++++++---------------------- 1 file changed, 208 insertions(+), 163 deletions(-) diff --git a/Help/release/3.12.rst b/Help/release/3.12.rst index 053fb21..e460d81 100644 --- a/Help/release/3.12.rst +++ b/Help/release/3.12.rst @@ -7,119 +7,202 @@ CMake 3.12 Release Notes Changes made since CMake 3.11 include the following. -* The :module:`FindALSA` module now provides imported targets. +New Features +============ -* CMake no longer produces ``_LIB_DEPENDS`` cache entries - for library targets. See policy :policy:`CMP0073`. +Generators +---------- -* The :module:`CheckIncludeFile` module ``check_include_file`` macro - learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. - See policy :policy:`CMP0075`. +* The :ref:`Visual Studio Generators` for VS 2017 learned to support a + ``version=14.##`` option in the :variable:`CMAKE_GENERATOR_TOOLSET` + value (e.g. via the :manual:`cmake(1)` ``-T`` option) to specify a + toolset version number. -* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro - learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. - See policy :policy:`CMP0075`. +Command-Line +------------ -* The :module:`CheckIncludeFiles` module ``check_include_files`` macro - learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. - See policy :policy:`CMP0075`. +* The :manual:`cmake(1)` :ref:`Build Tool Mode` (``cmake --build``) gained + ``--parallel []`` and ``-j []`` options to specify a parallel + build level. They map to corresponding options of the native build tool. -* The existence and functionality of the file - ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the - :command:`install` documentation so that external packaging software can take - advantage of CPack-style component installs. +Commands +-------- * The :command:`add_compile_definitions` command was added to set preprocessor definitions at directory level. This supersedes :command:`add_definitions`. +* The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)` + commands now accept a version range using the form ``[...]``. + The ```` version is required but policies are set based on the + ```` version. This allows projects to specify a range of versions + for which they have been updated and avoid explicit policy settings. + +* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands + learned a new flag ``CONFIGURE_DEPENDS`` which enables expression of + build system dependency on globbed directory's contents. + +* The :command:`file(TOUCH)` and :command:`file(TOUCH_NOCREATE)` commands + were added to expose ``TOUCH`` functionality without having to use + CMake's command-line tool mode with :command:`execute_process`. + +* The :command:`find_package` command now searches a prefix specified by + a ``PackageName_ROOT`` CMake or environment variable. Package roots are + maintained as a stack so nested calls to all ``find_*`` commands inside + find modules also search the roots as prefixes. + See policy :policy:`CMP0074`. + +* The :command:`install` command learned an optional ``NAMELINK_COMPONENT`` + parameter, which allows you to change the component for a shared library's + namelink. If none is specified, the value of ``COMPONENT`` is used by + default. + +* The :command:`list` command learned a ``JOIN`` sub-command + to concatenate list's elements separated by a glue string. + +* The :command:`list` command learned a ``SUBLIST`` sub-command + to get a sublist of the list. + +* The :command:`list` command learned a ``TRANSFORM`` sub-command + to apply various string transformation to list's elements. + +* The :command:`project` command learned an optional ``HOMEPAGE_URL`` + parameter which has the effect of setting variables like + :variable:`PROJECT_HOMEPAGE_URL`, :variable:`_HOMEPAGE_URL` + and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. + +* The :command:`string` command learned a ``JOIN`` sub-command + to concatenate input strings separated by a glue string. + * :command:`target_compile_options` and :command:`add_compile_options` commands gained a ``SHELL:`` prefix to specify a group of related options using shell-like quoting. -* The :manual:`cmake(1)` ``-E copy_directory`` tool now fails when the - source directory does not exist. Previously it succeeded by creating - an empty destination directory. +* The :command:`target_link_libraries` command now supports + :ref:`Object Libraries`. Linking to an object library uses its object + files in direct dependents and also propagates usage requirements. -* :manual:`cpack(1)` gained basic support for `NuGet`_. - See the :module:`CPackNuGet` module. +* The :command:`target_link_libraries` command may now be called + to modify targets created outside the current directory. -.. _NuGet: https://docs.microsoft.com/en-us/nuget/what-is-nuget +Variables +--------- -* Introduce :variable:`CMAKE_PROJECT_VERSION` and the corresponding components: - :variable:`CMAKE_PROJECT_VERSION_MAJOR`, :variable:`CMAKE_PROJECT_VERSION_MINOR`, - :variable:`CMAKE_PROJECT_VERSION_PATCH` and :variable:`CMAKE_PROJECT_VERSION_TWEAK`. +* The :variable:`CMAKE_FOLDER` variable was added to initialize the + :prop_tgt:`FOLDER` property on all targets. -* :module:`CPack` module use :variable:`CMAKE_PROJECT_VERSION_MAJOR`, - :variable:`CMAKE_PROJECT_VERSION_MINOR` and :variable:`CMAKE_PROJECT_VERSION_PATCH` - to initialize corresponding CPack variables. +* The :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable + was defined to initialize all + :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target properties. -* A :prop_test:`PROCESSOR_AFFINITY` test property was added to request - that CTest run a test with CPU affinity for a set of processors - disjoint from other concurrently running tests with the property set. +* ``CMAKE_PROJECT_VERSION*`` variables have been introduced: -* The :command:`ctest_start` command has been reworked so that you can simply - call ``ctest_start(APPEND)`` and it will read all the needed information from - the TAG file. The argument parsing has also been relaxed so that the order of - the arguments is less significant. + - :variable:`CMAKE_PROJECT_VERSION` + - :variable:`CMAKE_PROJECT_VERSION_MAJOR` + - :variable:`CMAKE_PROJECT_VERSION_MINOR` + - :variable:`CMAKE_PROJECT_VERSION_PATCH` + - :variable:`CMAKE_PROJECT_VERSION_TWEAK` -* The :module:`FindCURL` module now provides imported targets. +* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to + support the :generator:`Ninja` and :ref:`Makefile Generators`. + It is also now documented. -* The :prop_dir:`TESTS` directory property was added to hold the list of tests defined by - command :command:`add_test`. +* ``CMAKE_VS_SDK_*_DIRECTORIES`` variables were defined to tell + :ref:`Visual Studio Generators` for VS 2010 and above how to populate + fields in ``.vcxproj`` files that specify SDK directories. The + variables are: + + - :variable:`CMAKE_VS_SDK_EXCLUDE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_INCLUDE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_LIBRARY_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_REFERENCE_DIRECTORIES` + - :variable:`CMAKE_VS_SDK_SOURCE_DIRECTORIES` + +* A :variable:`MSVC_TOOLSET_VERSION` variable was added to provide the + MSVC toolset version associated with the current MSVC compiler version + in :variable:`MSVC_VERSION`. + +Properties +---------- + +* The :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property was introduced + to configure the use of managed C++ for :ref:`Visual Studio Generators` + for VS 2010 and above. + A corresponding :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` target + property was added to support ``C++/CLI`` for imported targets. * The :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property was introduced as replacement for :prop_tgt:`VS_DOTNET_TARGET_FRAMEWORK_VERSION`, which is considered deprecated now. -* The :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable - was defined to initialize all - :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target properties. - * An :prop_tgt:`EXPORT_PROPERTIES` target property was added to specify a custom list of target properties to include in targets exported by the :command:`install(EXPORT)` and :command:`export` commands. -* The :manual:`Compile Features ` functionality - is now aware of C++ 20. No specific features are yet enumerated besides - the ``cxx_std_20`` meta-feature. +* The :prop_tgt:`PDB_OUTPUT_DIRECTORY` property learned to support + :manual:`generator expressions `. -* The :manual:`Compile Features ` functionality - is now aware of the availability of C features in MSVC since VS 2010. +* A :prop_dir:`TESTS` directory property was added to hold the list of + tests defined by the :command:`add_test` command. -* The :command:`file(TOUCH)` and :command:`file(TOUCH_NOCREATE)` commands - were added to expose TOUCH functionality without having to use CMake's - command-line tool mode with :command:`execute_process`. +* A :prop_tgt:`VS_DEBUGGER_COMMAND` target property was created to set the + debugging command line with :ref:`Visual Studio Generators` for VS 2010 + and above. + +* HLSL source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` + and :prop_sf:`VS_SHADER_ENABLE_DEBUG` gained support for generator + expressions. + +* HLSL source file property :prop_sf:`VS_SHADER_OBJECT_FILE_NAME` has been + added to the :ref:`Visual Studio Generators` for VS 2010 and above. + The property specifies the file name of the compiled shader object. + +Modules +------- + +* The :module:`FindALSA` module now provides imported targets. + +* The :module:`FindCURL` module now provides imported targets. * The :module:`FindJPEG` module now provides imported targets. +* The :module:`FindLibXml2` module now provides imported targets. + * A :module:`FindODBC` module was added to find an Open Database Connectivity (ODBC) library. -* The :command:`find_package` command now searches a prefix specified by - a ``PackageName_ROOT`` CMake or environment variable. Package roots are - maintained as a stack so nested calls to all ``find_*`` commands inside - find modules also search the roots as prefixes. - See policy :policy:`CMP0074`. +* The :module:`FindPkgConfig` module has learned to export the found + libraries with full path for direct consumption with the + :command:`target_link_libraries` command. -* The :module:`FindPkgConfig` module has learned to export the found libraries - with full path for direct consumption with the :command:`target_link_libraries` - command. +* New :module:`FindPython3` and :module:`FindPython2` modules, as well as + a new :module:`FindPython` module, have been added to provide a new way + to locate python environments. -* The new :module:`FindPython3` and :module:`FindPython2` modules, as well as - :module:`FindPython`, provide a new way to locate python environments. +* The :module:`UseSWIG` module gained a whole refresh and is now more + consistent with standard CMake commands to generate libraries and is + fully configurable through properties. -* Fortran dependency scanning now supports dependencies implied by - `Fortran Submodules`_. +* The :module:`UseSWIG` module learned to manage multiple behaviors through + ``UseSWIG_MODULE_VERSION`` variable to ensure legacy support as well as more + robust handling of ``SWIG`` advanced features (like ``%template``). -.. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules +* The :module:`WriteCompilerDetectionHeader` module gained a ``BARE_FEATURES`` + option to add a compatibility define for the exact keyword of a new language + feature. -* New ``$`` and ``$`` +Generator Expressions +--------------------- + +* A new ``$`` and ``$`` :manual:`generator expression ` - had been added to enable consumption of generator expressions whose + has been added to enable consumption of generator expressions whose evaluation results itself in generator expressions. -* A new ``$`` :manual:`generator expression ` +* A new ``$`` + :manual:`generator expression ` has been added. * A new ``$`` @@ -130,126 +213,88 @@ Changes made since CMake 3.11 include the following. :manual:`generator expression ` has been added. -* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands - learned a new flag ``CONFIGURE_DEPENDS`` which enables expression of - build system dependency on globbed directory's contents. - -* The :module:`FindLibXml2` module now provides imported targets. - -* The :command:`list` command learned a ``JOIN`` sub-command - to concatenate list's elements separated by a glue string. - -* The :command:`list` command learned a ``SUBLIST`` sub-command - to get a sublist of the list. - -* The :command:`list` command learned a ``TRANSFORM`` sub-command - to apply various string transformation to list's elements. - -* The :prop_tgt:`COMMON_LANGUAGE_RUNTIME` target property was introduced - to configure the use of managed C++ for :ref:`Visual Studio Generators` - for VS 2010 and above. -* To support ``C++/CLI`` for imported targets, the - :prop_tgt:`IMPORTED_COMMON_LANGUAGE_RUNTIME` was added. - -* A :variable:`MSVC_TOOLSET_VERSION` variable was added to provide the - MSVC toolset version associated with the current MSVC compiler version - in :variable:`MSVC_VERSION`. - -* The :command:`install` command learned an optional ``NAMELINK_COMPONENT`` - parameter, which allows you to change the component for a shared library's - namelink. If none is specified, the value of ``COMPONENT`` is used by - default. +CTest +----- -* The :command:`target_link_libraries` command now supports - :ref:`Object Libraries`. Linking to an object library uses its object - files in direct dependents and also propagates usage requirements. +* The :command:`ctest_start` command has been reworked so that you can simply + call ``ctest_start(APPEND)`` and it will read all the needed information from + the TAG file. The argument parsing has also been relaxed so that the order of + the arguments is less significant. -* The :manual:`cmake(1)` :ref:`Build Tool Mode` (``cmake --build``) gained - ``--parallel []`` and ``-j []`` options to specify a parallel - build level. They map to corresponding options of the native build tool. +* A :prop_test:`PROCESSOR_AFFINITY` test property was added to request + that CTest run a test with CPU affinity for a set of processors + disjoint from other concurrently running tests with the property set. -* The :prop_tgt:`PDB_OUTPUT_DIRECTORY` property learned to support - :manual:`generator expressions `. +CPack +----- -* The :command:`cmake_minimum_required` and :command:`cmake_policy(VERSION)` - commands now accept a version range using the form ``[...]``. - The ```` version is required but policies are set based on the - ```` version. This allows projects to specify a range of versions - for which they have been updated and avoid explicit policy settings. +* The :module:`CPack` module now uses variables + :variable:`CMAKE_PROJECT_VERSION_MAJOR`, + :variable:`CMAKE_PROJECT_VERSION_MINOR` and + :variable:`CMAKE_PROJECT_VERSION_PATCH` + to initialize corresponding CPack variables. -* The :command:`project` command learned an optional ``HOMEPAGE_URL`` - parameter which has the effect of setting variables like - :variable:`PROJECT_HOMEPAGE_URL`, :variable:`_HOMEPAGE_URL` - and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. +* :manual:`cpack(1)` gained basic support for `NuGet`_. + See the :module:`CPackNuGet` module. -* The :generator:`Visual Studio 8 2005` generator has been removed. +.. _NuGet: https://docs.microsoft.com/en-us/nuget/what-is-nuget -* Include directories marked as ``SYSTEM`` are now moved after non-system - directories. The ``-isystem`` flag does this automatically, so moving - them explicitly to the end makes the behavior consistent on compilers - that do not have any ``-isystem`` flag. +Other +----- -* The :command:`string` command learned a ``JOIN`` sub-command - to concatenate input strings separated by a glue string. +* The :manual:`Compile Features ` functionality + is now aware of C++ 20. No specific features are yet enumerated besides + the ``cxx_std_20`` meta-feature. -* The :command:`target_link_libraries` command may now be called - to modify targets created outside the current directory. +* The :manual:`Compile Features ` functionality + is now aware of the availability of C features in MSVC since VS 2010. * The :manual:`Compile Features ` functionality is now aware of C language standards supported by Texas Instruments C compilers. -* The :module:`UseSWIG` module :command:`swig_add_library` command - (and legacy ``swig_add_module`` command) now set the prefix of - Java modules to ``""`` for MINGW, MSYS, and CYGWIN environments. +Deprecated and Removed Features +=============================== -* The :module:`UseSWIG` gained a whole refresh and is now more consistent with - standard CMake commands to generate libraries and is fully configurable through - properties. +* The :generator:`Visual Studio 8 2005` generator has been removed. -* The :module:`UseSWIG` module learned to manage multiple behaviors through - ``UseSWIG_MODULE_VERSION`` variable to ensure legacy support as well as more - robust handling of ``SWIG`` advanced features (like ``%template``). +* CMake no longer produces ``_LIB_DEPENDS`` cache entries + for library targets. See policy :policy:`CMP0073`. -* The :variable:`CMAKE_FOLDER` variable was added to initialize the - :prop_tgt:`FOLDER` property on all targets. +Other Changes +============= -* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable was extended to support the - :generator:`Ninja` and :ref:`Makefile Generators`. -* The :variable:`CMAKE_SUPPRESS_REGENERATION` variable is now documented. +* Include flags for directories marked as ``SYSTEM`` are now moved after + non-system directories. The ``-isystem`` flag does this automatically, + so moving them explicitly to the end makes the behavior consistent on + compilers that do not have any ``-isystem`` flag. -* For the :ref:`Visual Studio Generators` for VS 2010 and above - the debugging command line can be set using a new - :prop_tgt:`VS_DEBUGGER_COMMAND` target property. +* Fortran dependency scanning now supports dependencies implied by + `Fortran Submodules`_. -* HLSL source file property :prop_sf:`VS_SHADER_OBJECT_FILE_NAME` has been - added to the :ref:`Visual Studio Generators` for VS 2010 and above. - The property specifies the file name of the compiled shader object. +* The existence and functionality of the file + ``${CMAKE_BINARY_DIR}/cmake_install.cmake`` has now been documented in the + :command:`install` documentation so that external packaging software can take + advantage of CPack-style component installs. -* ``CMAKE_VS_SDK_*_DIRECTORIES`` variables were defined to tell - :ref:`Visual Studio Generators` for VS 2010 and above how to populate - fields in ``.vcxproj`` files that specify SDK directories. The - variables are: +* The :module:`CheckIncludeFile` module ``check_include_file`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. - - :variable:`CMAKE_VS_SDK_EXCLUDE_DIRECTORIES` - - :variable:`CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES` - - :variable:`CMAKE_VS_SDK_INCLUDE_DIRECTORIES` - - :variable:`CMAKE_VS_SDK_LIBRARY_DIRECTORIES` - - :variable:`CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES` - - :variable:`CMAKE_VS_SDK_REFERENCE_DIRECTORIES` - - :variable:`CMAKE_VS_SDK_SOURCE_DIRECTORIES` +* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. -* Added support for generator expressions for the following source file - properties: +* The :module:`CheckIncludeFiles` module ``check_include_files`` macro + learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable. + See policy :policy:`CMP0075`. - - :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` - - :prop_sf:`VS_SHADER_ENABLE_DEBUG` +* The :manual:`cmake(1)` ``-E copy_directory`` tool now fails when the + source directory does not exist. Previously it succeeded by creating + an empty destination directory. -* The :ref:`Visual Studio Generators` for VS 2017 learned to support a - ``version=14.##`` option in the :variable:`CMAKE_GENERATOR_TOOLSET` - value (e.g. via the :manual:`cmake(1)` ``-T`` option) to specify a - toolset version number. +* The :module:`UseSWIG` module :command:`swig_add_library` command + (and legacy ``swig_add_module`` command) now set the prefix of + Java modules to ``""`` for MINGW, MSYS, and CYGWIN environments. -* The :module:`WriteCompilerDetectionHeader` module now supports the - ``BARE_FEATURES`` argument which allows to add a compatibility define for - the exact keyword of a new language feature. +.. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules -- cgit v0.12