Merge topic 'doc-3.10-relnotes'

0565192a Help: Organize and revise 3.10 release notes
dd5835c0 Help: Consolidate 3.10 release notes

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !1353

Help/release/3.10.rst

+CMake 3.10 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.9 include the following.
+
+New Features
+============
+
+Platforms
+---------
+
+* The `flang`_ Fortran compiler is now supported, with compiler id ``Flang``.
+
+* A new minimal platform file for ``Midipix`` was added.
+
+* Support for the MSVC ARM64 architecture was added.
+  Visual Studio 2017 Update 4 and above offer an ARM64 toolchain.
+
+* Support for the IAR ARM Compiler was improved.
+
+.. _`flang`: https://github.com/flang-compiler/flang
+
+Generators
+----------
+
+* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
+  to add compiler launcher tools like ccache along with the compiler for the
+  ``CUDA`` language (``C`` and ``CXX`` were supported previously).  See the
+  :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
+  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
+
+* The :generator:`CodeBlocks` extra generator learned to optionally exclude
+  files from outside the project root directory from the generated project.
+  See the :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable.
+
+Commands
+--------
+
+* The :command:`cmake_host_system_information` command learned more keys
+  to get information about the processor capabilities and the host OS
+  version.
+
+* The :command:`configure_file` command learned to support indented
+  ``#  cmakedefine`` and ``#  cmakedefine01``. Spaces and/or tabs between
+  the ``#`` character and the ``cmakedefine``/``cmakedefine01`` words
+  are now understood and preserved in the output.
+
+* The :command:`execute_process` command gained a ``RESULTS_VARIABLE``
+  option to collect a list of results from all children in a pipeline
+  of processes when multiple ``COMMAND`` arguments are given.
+
+* The :command:`include_guard` command was introduced to allow guarding
+  CMake scripts from being included more than once. The command supports
+  ``DIRECTORY`` and ``GLOBAL`` options to adjust the corresponding include guard
+  scope. If no options given, include guard is similar to basic variable-based
+  check.
+
+* The :command:`string` command learned a new ``PREPEND`` subcommand.
+
+* The :command:`string(TIMESTAMP)` command now supports ``%A``
+  for full weekday name and ``%B`` for full month name.
+
+Variables
+---------
+
+* A :variable:`CMAKE_DIRECTORY_LABELS` variable was added to specify
+  labels for all tests in a directory.
+
+Properties
+----------
+
+* A :prop_tgt:`<LANG>_CPPCHECK` target property and supporting
+  :variable:`CMAKE_<LANG>_CPPCHECK` variable were introduced to tell
+  the :ref:`Makefile Generators` and the :generator:`Ninja` generator to
+  run ``cppcheck`` with the compiler for ``C`` and ``CXX`` languages.
+
+* A :prop_dir:`LABELS` directory property was added to specify labels
+  for all targets and tests in a directory.
+
+* A :prop_dir:`TEST_INCLUDE_FILES` directory property was added to
+  list any number of files to be included when running tests with
+  :manual:`ctest(1)`.  This generalizes the :prop_dir:`TEST_INCLUDE_FILE`
+  property.
+
+* The :prop_tgt:`VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>`
+  target property was added to support custom XML tags for reference
+  assemblies in C# targets.
+
+* Source file properties :prop_sf:`VS_SHADER_OUTPUT_HEADER_FILE` and
+  :prop_sf:`VS_SHADER_VARIABLE_NAME` have been added to specify more
+  details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.
+
+Modules
+-------
+
+* The :module:`FindCurses` module gained a ``CURSES_NEED_WIDE`` option
+  to request the wide-character variant.
+
+* The :module:`FindEXPAT` module now provides imported targets.
+
+* The :module:`FindFreetype` module now provides imported targets.
+
+* :module:`FindMPI` gained a number of new features, including:
+
+  * Language-specific components have been added to the module.
+  * Many more MPI environments are now supported.
+  * The environmental support for Fortran has been improved.
+  * A user now has fine-grained control over the MPI selection process,
+    including passing custom parameters to the MPI compiler.
+  * The version of the implemented MPI standard is now being exposed.
+  * MPI-2 C++ bindings can now be detected and also suppressed if so desired.
+  * The available Fortran bindings are now being detected and verified.
+  * Various MPI-3 information can be requested, including the library version
+    and Fortran capabilities of the individual bindings.
+  * Statically linked MPI implementations are supported.
+
+* A :module:`FindOpenACC` module was added to detect compiler support
+  for OpenACC.  Currently only supports PGI, GNU and Cray compilers.
+
+* The :module:`FindOpenGL` module gained support for GLVND on Linux.
+
+* The :module:`FindOpenMP` module gained support for
+  language-specific components.
+
+* A :module:`FindPatch` module was added to find the ``patch``
+  command-line executable.
+
+* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp` command
+  gained a ``DESCRIPTORS`` option to generate descriptor files.
+
+* The :module:`GoogleTest` module gained a new command
+  :command:`gtest_discover_tests` implementing dynamic (build-time) test
+  discovery.  Unlike the source parsing approach, dynamic discovery executes
+  the test (in 'list available tests' mode) at build time to discover tests.
+  This is robust against unusual ways of labeling tests, provides much better
+  support for advanced features such as parameterized tests, and does not
+  require re-running CMake to discover added or removed tests within a test
+  executable.
+
+* The :module:`InstallRequiredSystemLibraries` module gained support
+  for installing Intel compiler runtimes.
+
+Autogen
+-------
+
+* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` with a
+  multi configuration generator (e.g. :generator:`Xcode`),
+  included ``*.moc``,  ``moc_*.cpp`` and ``ui_*.h`` files are generated in
+  ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` instead of
+  ``<AUTOGEN_BUILD_DIR>/include``.
+
+* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`,
+  source files that are :prop_sf:`GENERATED` will be processed as well.
+  They were ignored by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`
+  in earlier releases.
+  See policy :policy:`CMP0071`.
+
+* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``,
+  ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs
+  to be ``moc`` processed. The new variable
+  :variable:`CMAKE_AUTOMOC_MACRO_NAMES` allows to register additional
+  strings (macro names) so search for.
+
+* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``,
+  ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs
+  to be ``moc`` processed. The new target property
+  :prop_tgt:`AUTOMOC_MACRO_NAMES` allows to register additional strings
+  (macro names) so search for.
+
+* When using :prop_tgt:`AUTOMOC`, the new variable
+  :variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES` allows to default
+  enable or disable the generation of the compiler pre definitions file
+  ``moc_predefs.h``.
+
+* When using :prop_tgt:`AUTOMOC`, the new boolean target property
+  :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` allows to enable or disable the
+  generation of the compiler pre definitions file ``moc_predefs.h``.
+
+CTest
+-----
+
+* A :variable:`CTEST_LABELS_FOR_SUBPROJECTS` CTest module variable and CTest
+  script variable were added to specify a list of labels that should be
+  treated as subprojects by CDash. To use this value in both the CTest module
+  and the ctest command line :ref:`Dashboard Client` mode (e.g. ``ctest -S``)
+  set it in the ``CTestConfig.cmake`` config file.
+
+CPack
+-----
+
+* CPack gained a ``FREEBSD`` generator for FreeBSD ``pkg(8)``, configured
+  by the :module:`CPackFreeBSD` module.
+
+* The CPack ``DEB`` generator, configured by the :module:`CPackDeb` module,
+  was enabled on Windows.  While not fully featured (due to the lack of
+  external UNIX tools) this will allow building basic cross-platform Debian
+  packages.
+
+* The :module:`CPackDeb` module learned to set package release version in
+  ``Version`` info property.
+  See the :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` variable.
+
+* The :module:`CPackDeb` module learned more strict package version checking
+  that complies with Debian rules.
+
+* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
+  :command:`cpack_ifw_configure_component_group` commands gained a new
+  ``REPLACES`` and ``CHECKABLE`` options.
+
+* The :module:`CPackIFW` module gained new
+  :variable:`CPACK_IFW_PACKAGE_FILE_EXTENSION` variable to customize
+  target binary format.
+
+* The :module:`CPackIFW` module gained new
+  :variable:`CPACK_IFW_REPOSITORIES_DIRECTORIES` variable to specify
+  additional repositories dirs that will be used to resolve and
+  repack dependent components. This feature available only
+  since QtIFW 3.1.
+
+* Modules :module:`CPackRPM` and :module:`CPackDeb` learned to set package epoch
+  version.
+  See :variable:`CPACK_RPM_PACKAGE_EPOCH` and
+  :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables.
+
+Other
+-----
+
+* The :manual:`cmake(1)` ``-E`` mode gained support for ``sha1sum``,
+  ``sha224sum``, ``sha256sum``, ``sha384sum``, and ``sha512sum``.
+
+* The graphviz output now distinguishes among the different dependency types
+  ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` and represents them in the output
+  graph as solid, dashed and dotted edges.
+
+Deprecated and Removed Features
+===============================
+
+* Support for building CMake itself with C++98 compilers was dropped.
+  CMake is now implemented using C++11.
+
+* Support for building CMake on HP-UX has been dropped pending better
+  support for C++11 and a port of libuv.  See `CMake Issue 17137`_.
+  Use CMake 3.9 or lower instead for HP-UX support.
+
+.. _`CMake Issue 17137`: https://gitlab.kitware.com/cmake/cmake/issues/17137
+
+Other Changes
+=============
+
+* On FreeBSD the C++ compiler named ``c++`` is now the preferred default.
+
+* The :command:`file(GENERATE)` command now interprets relative paths
+  given to its ``OUTPUT`` and ``INPUT`` arguments with respect to the
+  caller's current binary and source directories, respectively.
+  See policy :policy:`CMP0070`.
+
+* The :command:`get_filename_component` ``PROGRAM`` mode semantics
+  have been revised to not tolerate unquoted spaces in the path
+  to the program while also accepting arguments.  While technically
+  incompatible with the old behavior, it is expected that behavior
+  under typical use cases with properly-quoted command-lines has
+  not changed.

Help/release/dev/FindCurses-wide.rst

-FindCurses-wide
----------------
-
-* The :module:`FindCurses` module gained a ``CURSES_NEED_WIDE`` option
-  to request the wide-character variant.

Help/release/dev/FindEXPAT-importedtargets.rst

-FindEXPAT-importedtargets
--------------------------
-
-* The :module:`FindEXPAT` module now provides imported targets.

Help/release/dev/FindFreetype-importedtargets.rst

-FindFreetype-importedtargets
-----------------------------
-
-* The :module:`FindFreetype` module now provides imported targets.

Help/release/dev/FindMPI-overhaul.rst

-findmpi-overhaul
-----------------
-
-* :module:`FindMPI` gained a number of new features, including:
-
-  * Language-specific components have been added to the module.
-  * Many more MPI environments are now supported.
-  * The environmental support for Fortran has been improved.
-  * A user now has fine-grained control over the MPI selection process,
-    including passing custom parameters to the MPI compiler.
-  * The version of the implemented MPI standard is now being exposed.
-  * MPI-2 C++ bindings can now be detected and also suppressed if so desired.
-  * The available Fortran bindings are now being detected and verified.
-  * Various MPI-3 information can be requested, including the library version
-    and Fortran capabilities of the individual bindings.
-  * Statically linked MPI implementations are supported.

Help/release/dev/FindOpenACC.rst

-FindOpenACC
------------
-
-* A :module:`FindOpenACC` module was added to detect compiler support
-  for OpenACC.  Currently only supports PGI, GNU and Cray compilers.

Help/release/dev/FindOpenGL-glvnd.rst

-FindOpenGL-glvnd
-----------------
-
-* The :module:`FindOpenGL` module gained support for GLVND on Linux.

Help/release/dev/GoogleTest.rst

-GoogleTest
-----------
-
-* The :module:`GoogleTest` module gained a new command
-  :command:`gtest_discover_tests` implementing dynamic (build-time) test
-  discovery.  Unlike the source parsing approach, dynamic discovery executes
-  the test (in 'list available tests' mode) at build time to discover tests.
-  This is robust against unusual ways of labeling tests, provides much better
-  support for advanced features such as parameterized tests, and does not
-  require re-running CMake to discover added or removed tests within a test
-  executable.

Help/release/dev/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst

-vs-dotnet-custom-reference-tags
--------------------------------
-
-* The :prop_tgt:`VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>`
-  target property was added to support custom XML tags for reference
-  assemblies in C# targets.

Help/release/dev/add-cppcheck.rst

-add-cppcheck
-------------
-
-* A :prop_tgt:`<LANG>_CPPCHECK` target property and supporting
-  :variable:`CMAKE_<LANG>_CPPCHECK` variable were introduced to tell
-  the :ref:`Makefile Generators` and the :generator:`Ninja` generator to
-  run ``cppcheck`` with the compiler for ``C`` and ``CXX`` languages.

Help/release/dev/add-vs-shader-properties.rst

-add-vs-shader-properties
-------------------------
-
-* Source file properties :prop_sf:`VS_SHADER_OUTPUT_HEADER_FILE` and
-  :prop_sf:`VS_SHADER_VARIABLE_NAME` have been added to specify more
-  details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.

Help/release/dev/autogen-configs.rst

-autogen-configs
----------------
-
-* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` with a
-  multi configuration generator (e.g. :generator:`Xcode`),
-  included ``*.moc``,  ``moc_*.cpp`` and ``ui_*.h`` files are generated in
-  ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` instead of
-  ``<AUTOGEN_BUILD_DIR>/include``.

Help/release/dev/autogen-generated-files.rst

-autogen-generated-files
------------------------
-
-* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`,
-  source files that are :prop_sf:`GENERATED` will be processed as well.
-  They were ignored by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`
-  in earlier releases.
-  See policy :policy:`CMP0071`.

Help/release/dev/autogen-macro-names.rst

-autogen-macro-names
--------------------
-
-* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``,
-  ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs
-  to be ``moc`` processed. The new variable
-  :variable:`CMAKE_AUTOMOC_MACRO_NAMES` allows to register additional
-  strings (macro names) so search for.
-
-* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``,
-  ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs
-  to be ``moc`` processed. The new target property
-  :prop_tgt:`AUTOMOC_MACRO_NAMES` allows to register additional strings
-  (macro names) so search for.

Help/release/dev/autogen-predefs.rst

-autogen-predefs
----------------
-
-* When using :prop_tgt:`AUTOMOC`, the new variable
-  :variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES` allows to default
-  enable or disable the generation of the compiler pre definitions file
-  ``moc_predefs.h``.
-
-* When using :prop_tgt:`AUTOMOC`, the new boolean target property
-  :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` allows to enable or disable the
-  generation of the compiler pre definitions file ``moc_predefs.h``.

Help/release/dev/cmake-command-mode-shasum.rst

-cmake-command-mode-shasum
--------------------------
-
-* Added sha1sum, sha224sum, sha256sum, sha384sum and sha512sum
-  as an equivalent to existing md5sum to cmake command mode.

Help/release/dev/cmake_host_system_information-extend.rst

-cmake_host_system_information-extend
-------------------------------------
-
-* The :command:`cmake_host_system_information` command learned more keys
-  to get information about the processor capabilities and the host OS
-  version.

Help/release/dev/codeblocks-exclude-external.rst

-codeblocks-exclude-external
----------------------------
-
-* A :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable was added
-  to tell the :generator:`CodeBlocks` extra generator to exclude files
-  from outside the project root directory from the generated project files.

Help/release/dev/cpack-freebsd-pkg.rst

-cpack-freebsd-pkg
------------------
-
-* CPack gained a ``FREEBSD`` generator for FreeBSD ``pkg(8)``, configured
-  by the :module:`CPackFreeBSD` module.

Help/release/dev/cpack-rpm-deb-version.rst

-cpack-rpm-deb-version
----------------------
-
-* Modules :module:`CPackRPM` and :module:`CPackDeb` learned to set package epoch
-  version.
-  See :variable:`CPACK_RPM_PACKAGE_EPOCH` and
-  :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables.
-
-* The :module:`CPackDeb` module learned to set package release version in
-  `Version` info property.
-  See :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` variable.
-
-* The :module:`CPackDeb` module learned more strict package version checking
-  that complies with Debian rules.