Help: Organize and revise 3.13 release notes
Add section headers similar to the 3.12 release notes and move each
individual bullet into an appropriate section. Revise a few bullets.
diff --git a/Help/release/3.13.rst b/Help/release/3.13.rst
index b8aaf2a..b08f21d 100644
--- a/Help/release/3.13.rst
+++ b/Help/release/3.13.rst
@@ -7,85 +7,20 @@
Changes made since CMake 3.12 include the following.
-* The :module:`BundleUtilities` module may no longer be included at configure
- time. This was always a bug anyway. See policy :policy:`CMP0080`.
+New Features
+============
-* The :ref:`Makefile Generators` learned to remove custom command and
- custom target byproducts during ``make clean``.
+Generators
+----------
-* The new variable :variable:`CMAKE_AUTOGEN_VERBOSE` allows
- to increase the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and
- :prop_tgt:`AUTORCC` from within CMakeLists.txt.
+* The :ref:`Visual Studio Generators` for VS 2010 and above learned to
+ support the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property
+ and supporting :module:`CheckIPOSupported` module.
-* The :manual:`cmake <cmake(1)>` command gained the ``-S <source_dir>``
- command line option to specify the location of the source directory.
- This option can be used independently of ``-B``.
+* The :generator:`Xcode` generator learned to configure more Xcode Scheme
+ fields. See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable.
-* The :manual:`cmake <cmake(1)>` command gained the ``-B <build_dir>``
- command line option to specify the location of the build directory.
- This option can be used independently of ``-S``.
-
-* The :cpack_gen:`CPack Deb Generator` learned to split debug symbols into
- a corresponding .ddeb package when ``CPACK_DEBIAN_DEBUGINFO_PACKAGE`` is
- set.
-
-* The :cpack_gen:`CPack Deb Generator` learned to honor the ``SOURCE_DATE_EPOCH``
- environment variable when packaging files. This is useful for generating
- reproducible packages.
-
-* CPack gained a new :cpack_gen:`CPack External Generator` which is used to
- export the CPack metadata in a format that other software can understand. The
- intention of this generator is to allow external packaging software to take
- advantage of CPack's features when it may not be possible to use CPack for
- the entire packaging process.
-
-* The CPack generators have been moved into their own separate section in the
- documentation, rather than having the documentation in their internal
- implementation modules.
-* These internal implementation modules are also no longer available to scripts
- that may have been incorrectly including them, because they should never have
- been available in the first place.
-
-* The :manual:`cmake(1)` ``-E create_symlink`` command can now be used
- on Windows.
-
-* :manual:`ctest(1)` gained a ``--progress`` option to enable a live
- test progress summary when output goes to a terminal.
-
-* The :command:`add_custom_command` and :command:`add_custom_target` commands
- learned to support generator expressions in ``WORKING_DIRECTORY`` options.
-
-* An explicit deprecation diagnostic was added for policies ``CMP0055``
- through ``CMP0063`` (``CMP0054`` and below were already deprecated).
- 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.
-
-* The :module:`FindCURL` module learned to find debug and release variants
- separately.
-
-* The :module:`FindMatlab` module gained new components ``ENGINE_LIBRARY`` and
- ``DATAARRAY_LIBRARY`` to request finding the Matlab C++ Engine and DataArray
- libraries respectively.
-
-* The :module:`FindMatlab` module now explicitly exports mexFunction in Visual
- Studio.
-
-* The :module:`FindMatlab` module gained the ability to discover Matlab R2018a
- and R2018b.
-
-* The :module:`FindMatlab` module gained a new ``MCC_COMPILER``
- component to request finding the Matlab Compiler add-on.
-
-* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
- gain capability to control order of resource lookup on macOS (Framework) and
- Windows (Registry).
-
-* The :module:`FindSubversion` module ``Subversion_WC_INFO`` command
- gained an ``IGNORE_SVN_FAILURE`` option to suppress failures,
- e.g. when the source tree is not under Subversion control.
-
-* The :generator:`Green Hills MULTI` generator is updated:
+* The :generator:`Green Hills MULTI` generator has been udpated:
- Added support for architecture selection through
:variable:`CMAKE_GENERATOR_PLATFORM`:
@@ -103,55 +38,176 @@
- No longer hard-codes ARM files, BSP, toolset, or OS locations.
+Command-Line
+------------
+
+* The :manual:`cmake(1)` command gained the ``-S <source_dir>``
+ command line option to specify the location of the source directory.
+ This option can be used independently of ``-B``.
+
+* The :manual:`cmake(1)` command gained the ``-B <build_dir>``
+ command line option to specify the location of the build directory.
+ This option can be used independently of ``-S``.
+
+* The :manual:`cmake(1)` ``-E create_symlink`` command can now be used
+ on Windows.
+
+Commands
+--------
+
+* The :command:`add_custom_command` and :command:`add_custom_target` commands
+ learned to support generator expressions in ``WORKING_DIRECTORY`` options.
+
+* The :command:`add_link_options` command was created to add link
+ options in the current directory.
+
* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
learned to support generator expressions.
-* Binary targets gained new :prop_tgt:`INTERFACE_LINK_DEPENDS` property.
+* The :command:`install(TARGETS)` command learned to install targets
+ created outside the current directory.
-* The :prop_tgt:`LINK_DEPENDS` target property learned to support
- :manual:`generator expressions <cmake-generator-expressions(7)>`.
-
-* :command:`link_directories` command gains capability to control directories
+* The :command:`link_directories` command gained options to control
insertion position.
-* The :prop_tgt:`LINK_DIRECTORIES` target property expects absolute paths.
- See policy :policy:`CMP0081`.
-
-* CMake gained new capabilities to manage link directories:
-
- * :prop_tgt:`LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
- target properties.
- * :command:`target_link_directories` command to add link directories to
- targets.
-
-* CMake gained new capabilities to manage link step:
-
- * :prop_dir:`LINK_OPTIONS` directory property.
- * :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
- properties.
- * :command:`add_link_options` command to add link options in the current
- directory.
- * :command:`target_link_options` command to add link options to targets.
-
* The :command:`list(SORT)` command gained options to control the
comparison operation used to order the entries.
* The :command:`math` command gained options for hexadecimal.
-* The :command:`option` command now honors existing normal variables instead
- of replacing them with a cache entry. See policy :policy:`CMP0077`.
+* The :command:`target_link_directories` command was created to
+ specify link directories for targets and their dependents.
+
+* The :command:`target_link_options` command was created to
+ specify link options for targets and their dependents.
* The :command:`target_link_libraries` command may now be called
to modify targets created outside the current directory.
See policy :policy:`CMP0079`.
-* Module ``FindPkgConfig`` gains capability to create imported targets in
- global scope.
+Variables
+---------
-* static library targets gained new :prop_tgt:`STATIC_LIBRARY_OPTIONS` property.
+* A :variable:`CMAKE_AUTOGEN_VERBOSE` variable was added to optionally
+ increase the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`
+ and :prop_tgt:`AUTORCC` from within CMake project code.
-* The :command:`install(TARGETS)` command may now be used
- to install targets created outside the current directory.
+* A :variable:`CMAKE_VS_GLOBALS` variable was added to initialize
+ :prop_tgt:`VS_GLOBAL_<variable>` target properties on targets as
+ they are created.
+
+Properties
+----------
+
+* The :prop_tgt:`DEPLOYMENT_ADDITIONAL_FILES` target property was
+ added to tell the :generator:`Visual Studio 9 2008` generator
+ to specify additional files for deployment to WinCE devices
+ for remote debugging.
+
+* The :prop_tgt:`INTERFACE_LINK_DEPENDS` target property was created
+ to specify transitive link dependencies on files.
+
+* The :prop_tgt:`LINK_DEPENDS` target property learned to support
+ :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+* :prop_tgt:`LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
+ target properties were added to collect link directories for a target
+ and its dependents. Use the :command:`target_link_directories` command
+ to set them.
+
+* :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
+ properties were added to collect link options for a target and its
+ dependents. Use the :command:`target_link_options` command to set them.
+
+* A :prop_dir:`LINK_OPTIONS` directory property was added to collect
+ link options for targets created under the current directory.
+ Use the :command:`add_link_options` command to set it.
+
+* A :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property was created
+ to specify archiver options to use when creating static libraries.
+
+* A :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS` target property was created to
+ set the debugging command line arguments with
+ :ref:`Visual Studio Generators` for VS 2010 and above.
+
+* A :prop_tgt:`VS_DEBUGGER_ENVIRONMENT` target property was created to
+ set the debugging environment with
+ :ref:`Visual Studio Generators` for VS 2010 and above.
+
+* The :prop_tgt:`VS_DEBUGGER_COMMAND` and
+ :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target properties
+ now support generator expressions.
+
+Modules
+-------
+
+* The :module:`FindCURL` module learned to find debug and release variants
+ separately.
+
+* The :module:`FindMatlab` module gained new components ``ENGINE_LIBRARY`` and
+ ``DATAARRAY_LIBRARY`` to request finding the Matlab C++ Engine and DataArray
+ libraries respectively.
+
+* The :module:`FindMatlab` module now explicitly exports mexFunction in Visual
+ Studio.
+
+* The :module:`FindMatlab` module gained a new ``MCC_COMPILER``
+ component to request finding the Matlab Compiler add-on.
+
+* The :module:`FindPkgConfig` module gained an option to create imported
+ targets in global scope.
+
+* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+ gain capability to control order of resource lookup on macOS (Framework) and
+ Windows (Registry).
+
+* The :module:`FindSubversion` module ``Subversion_WC_INFO`` command
+ gained an ``IGNORE_SVN_FAILURE`` option to suppress failures,
+ e.g. when the source tree is not under Subversion control.
+
+* The :module:`UseSWIG` module learned to manage target property
+ :prop_tgt:`INCLUDE_DIRECTORIES` for ``SWIG`` compilation.
+
+CTest
+-----
+
+* :manual:`ctest(1)` gained a ``--progress`` option to enable a live
+ test progress summary when output goes to a terminal.
+
+CPack
+-----
+
+* The :cpack_gen:`CPack Deb Generator` learned to split debug symbols into
+ a corresponding .ddeb package when ``CPACK_DEBIAN_DEBUGINFO_PACKAGE`` is
+ set.
+
+* The :cpack_gen:`CPack Deb Generator` learned to honor the ``SOURCE_DATE_EPOCH``
+ environment variable when packaging files. This is useful for generating
+ reproducible packages.
+
+* CPack gained a new :cpack_gen:`CPack External Generator` which is used to
+ export the CPack metadata in a format that other software can understand. The
+ intention of this generator is to allow external packaging software to take
+ advantage of CPack's features when it may not be possible to use CPack for
+ the entire packaging process.
+
+Deprecated and Removed Features
+===============================
+
+* An explicit deprecation diagnostic was added for policies ``CMP0055``
+ through ``CMP0063`` (``CMP0054`` and below were already deprecated).
+ 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.
+
+Other Changes
+=============
+
+* The :command:`option` command now honors existing normal variables instead
+ of replacing them with a cache entry. See policy :policy:`CMP0077`.
+
+* The :ref:`Makefile Generators` learned to remove custom command and
+ custom target byproducts during ``make clean``.
* The :command:`target_sources` command now interprets relative source file
paths as relative to the current source directory. This simplifies
@@ -159,36 +215,18 @@
:policy:`CMP0076` policy was added to provide backward compatibility with
the old behavior where required.
+* The :module:`BundleUtilities` module may no longer be included at configure
+ time. This was always a bug anyway. See policy :policy:`CMP0080`.
+
* The :module:`UseSWIG` module has changed strategy for target naming.
See policy :policy:`CMP0078`.
-* Module ``UseSWIG`` gains capability to manage target property
- :prop_tgt:`INCLUDE_DIRECTORIES` for ``SWIG`` compilation.
+* The :prop_tgt:`LINK_DIRECTORIES` target property now expects absolute paths.
+ See policy :policy:`CMP0081`.
-* A :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS` target property was created to
- set the debugging command line arguments with
- :ref:`Visual Studio Generators` for VS 2010 and above.
-* A :prop_tgt:`VS_DEBUGGER_ENVIRONMENT` target property was created to
- set the debugging environment with
- :ref:`Visual Studio Generators` for VS 2010 and above.
-* :prop_tgt:`VS_DEBUGGER_COMMAND`
- :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS`
- :prop_tgt:`VS_DEBUGGER_ENVIRONMENT`
- :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY`
- target properties can use generator expressions.
-
-* The :prop_tgt:`DEPLOYMENT_ADDITIONAL_FILES` target property was
- added to tell the :generator:`Visual Studio 9 2008` generator
- to specify additional files for deployment to WinCE devices
- for remote debugging.
-
-* A :variable:`CMAKE_VS_GLOBALS` variable was added to initialize
- :prop_tgt:`VS_GLOBAL_<variable>` target properties on targets as
- they are created.
-
-* The :ref:`Visual Studio Generators` for VS 2010 and above learned to
- support the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property
- and supporting :module:`CheckIPOSupported` module.
-
-* The :generator:`Xcode` generator learned to configure more Xcode Scheme
- fields. See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable.
+* The CPack generators have been moved into their own separate section
+ in the documentation, rather than having the documentation in their
+ internal implementation modules.
+ These internal implementation modules are also no longer available
+ to scripts that may have been incorrectly including them, because
+ they should never have been available in the first place.
