Imported Upstream version 3.17.1upstream/3.17.1

17 files changed, 136 insertions, 76 deletions

diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst
index a310e9f36..d1e495f99 100644
--- a/Help/cpack_gen/nsis.rst
+++ b/Help/cpack_gen/nsis.rst
@@ -1,7 +1,9 @@
 CPack NSIS Generator
 --------------------
 
-CPack Nullsoft Scriptable Install System (NSIS) generator specific options
+CPack Nullsoft Scriptable Install System (NSIS) generator specific options.
+
+The NSIS generator requires NSIS 3.0 or newer.
 
 Variables specific to CPack NSIS generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst
index 1f68535ff..f480eb82e 100644
--- a/Help/generator/Ninja Multi-Config.rst
+++ b/Help/generator/Ninja Multi-Config.rst
@@ -33,53 +33,19 @@ below for how to enable cross-config mode.
 The ``Ninja Multi-Config`` generator recognizes the following variables:
 
 :variable:`CMAKE_CONFIGURATION_TYPES`
-  Specifies the total set of configurations to build. See the variable's
-  documentation for more information.
+  Specifies the total set of configurations to build.
 
 :variable:`CMAKE_CROSS_CONFIGS`
   Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
   configurations available from all ``build-<Config>.ninja`` files.
-  This variable activates cross-config mode.
-  Targets from each config specified in this variable can be built from any
-  ``build-<Config>.ninja`` file. Custom commands will use the configuration
-  native to ``build-<Config>.ninja``. If it is set to ``all``, all
-  configurations from :variable:`CMAKE_CONFIGURATION_TYPES` are cross-configs.
-  If it is not specified, or empty, each ``build-<Config>.ninja`` file will
-  only contain build rules for its own configuration.
-
-  The value of this variable must be a subset of
-  :variable:`CMAKE_CONFIGURATION_TYPES`.
 
 :variable:`CMAKE_DEFAULT_BUILD_TYPE`
-  Specifies the configuration to use by default in a ``build.ninja`` file. If
-  this variable is specified, ``build.ninja`` uses build rules from
-  ``build-<Config>.ninja`` by default. All custom commands are executed with
-  this configuration. If the variable is not specified, the first item from
-  :variable:`CMAKE_CONFIGURATION_TYPES` is used instead.
-
-  The value of this variable must be one of the items from
-  :variable:`CMAKE_CONFIGURATION_TYPES`.
+  Specifies the configuration to use by default in a ``build.ninja`` file.
 
 :variable:`CMAKE_DEFAULT_CONFIGS`
   Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
   configurations to build for a target in ``build.ninja``
-  if no ``:<Config>`` suffix is specified. If it is set to ``all``, all
-  configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If
-  it is not specified, it defaults to
-  :variable:`CMAKE_DEFAULT_BUILD_TYPE`.
-
-  For example, if you set
-  :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``, but
-  set :variable:`CMAKE_DEFAULT_CONFIGS` to ``Debug`` or ``all``,
-  all ``<target>`` aliases in ``build.ninja`` will resolve to
-  ``<target>:Debug`` or ``<target>:all``, but custom commands will still use
-  the ``Release`` configuration.
-
-  The value of this variable must be a subset of
-  :variable:`CMAKE_CROSS_CONFIGS` or be the same as
-  :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be
-  specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or
-  :variable:`CMAKE_CROSS_CONFIGS` is not used.
+  if no ``:<Config>`` suffix is specified.
 
 Consider the following example:
 
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 28a081f96..d34387431 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -242,10 +242,12 @@ Options
  :command:`message(SEND_ERROR)` calls.
 
 ``--debug-find``
- Put cmake find in a debug mode.
+ Put cmake find commands in a debug mode.
 
  Print extra find call information during the cmake run to standard
  error. Output is designed for human consumption and not for parsing.
+ See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging
+ a more local part of the project.
 
 ``--trace``
  Put cmake in trace mode.
diff --git a/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst
index f3fedbabe..26d5cc86c 100644
--- a/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst
+++ b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst
@@ -4,11 +4,22 @@ MACHO_COMPATIBILITY_VERSION
 What compatibility version number is this target for Mach-O binaries.
 
 For shared libraries on Mach-O systems (e.g. macOS, iOS)
-the ``MACHO_COMPATIBILITY_VERSION`` property correspond to
-``compatibility version`` and :prop_tgt:`MACHO_CURRENT_VERSION` to
-``current version``.
-See the :prop_tgt:`FRAMEWORK` target property for an example.
-
-Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
-command.  If ``MACHO_COMPATIBILITY_VERSION`` is not set, the value of
-the :prop_tgt:`SOVERSION` property will be used.
+the ``MACHO_COMPATIBILITY_VERSION`` property corresponds to the
+*compatibility version* and :prop_tgt:`MACHO_CURRENT_VERSION` corresponds to
+the *current version*.  These are both embedded in the shared library binary
+and can be checked with the ``otool -L <binary>`` command.
+
+It should be noted that the :prop_tgt:`MACHO_CURRENT_VERSION` and
+``MACHO_COMPATIBILITY_VERSION`` properties do not affect the file
+names or version-related symlinks that CMake generates for the library.
+The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still
+control the file and symlink names.  The ``install_name`` is also still
+controlled by :prop_tgt:`SOVERSION`.
+
+When :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION``
+are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for
+the version details to be embedded in the binaries respectively.
+The :prop_tgt:`MACHO_CURRENT_VERSION` and ``MACHO_COMPATIBILITY_VERSION``
+properties only need to be given if the project needs to decouple the file
+and symlink naming from the version details embedded in the binaries
+(e.g. to match libtool conventions).
diff --git a/Help/prop_tgt/MACHO_CURRENT_VERSION.rst b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst
index 4a1d3f063..9afb35699 100644
--- a/Help/prop_tgt/MACHO_CURRENT_VERSION.rst
+++ b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst
@@ -4,10 +4,22 @@ MACHO_CURRENT_VERSION
 What current version number is this target for Mach-O binaries.
 
 For shared libraries on Mach-O systems (e.g. macOS, iOS)
-the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property correspond to
-``compatibility version`` and ``MACHO_CURRENT_VERSION`` to ``current version``.
-See the :prop_tgt:`FRAMEWORK` target property for an example.
+the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property corresponds to the
+*compatibility version* and ``MACHO_CURRENT_VERSION`` corresponds to the
+*current version*.  These are both embedded in the shared library binary
+and can be checked with the ``otool -L <binary>`` command.
 
-Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
-command.  If ``MACHO_CURRENT_VERSION`` is not set, the value of
-the :prop_tgt:`VERSION` property will be used.
+It should be noted that the ``MACHO_CURRENT_VERSION`` and
+:prop_tgt:`MACHO_COMPATIBILITY_VERSION` properties do not affect the file
+names or version-related symlinks that CMake generates for the library.
+The :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties still
+control the file and symlink names.  The ``install_name`` is also still
+controlled by :prop_tgt:`SOVERSION`.
+
+When ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION`
+are not given, :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` are used for
+the version details to be embedded in the binaries respectively.
+The ``MACHO_CURRENT_VERSION`` and :prop_tgt:`MACHO_COMPATIBILITY_VERSION`
+properties only need to be given if the project needs to decouple the file
+and symlink naming from the version details embedded in the binaries
+(e.g. to match libtool conventions).
diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst
index d6f8a941f..b377f2228 100644
--- a/Help/prop_tgt/SOVERSION.rst
+++ b/Help/prop_tgt/SOVERSION.rst
@@ -21,9 +21,17 @@ Mach-O Versions
 ^^^^^^^^^^^^^^^
 
 For shared libraries and executables on Mach-O systems (e.g. macOS, iOS),
-the ``SOVERSION`` property is a fallback to
-:prop_tgt:`MACHO_COMPATIBILITY_VERSION` property which corresponds to
-*compatiblity version* and :prop_tgt:`VERSION` is a fallback to
-:prop_tgt:`MACHO_CURRENT_VERSION` which corresponds to *current version*.
-See the :prop_tgt:`FRAMEWORK` target property for an example.  Versions
-of Mach-O binaries may be checked with the ``otool -L <binary>`` command.
+the ``SOVERSION`` property corresponds to the *compatibility version* and
+:prop_tgt:`VERSION` corresponds to the *current version* (unless Mach-O
+specific overrides are provided, as discussed below).
+See the :prop_tgt:`FRAMEWORK` target property for an example.
+
+For shared libraries, the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and
+:prop_tgt:`MACHO_CURRENT_VERSION` properties can be used to
+override the *compatibility version* and *current version* respectively.
+Note that ``SOVERSION`` will still be used to form the ``install_name``
+and both ``SOVERSION`` and :prop_tgt:`VERSION` may also affect the file
+and symlink names.
+
+Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
+command.
diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst
index f592f4a61..95db4837b 100644
--- a/Help/prop_tgt/VERSION.rst
+++ b/Help/prop_tgt/VERSION.rst
@@ -23,9 +23,17 @@ Mach-O Versions
 ^^^^^^^^^^^^^^^
 
 For shared libraries and executables on Mach-O systems (e.g. macOS, iOS),
-the ``VERSION`` property is a fallback to :prop_tgt:`MACHO_CURRENT_VERSION`
-property which corresponds to *current version* and :prop_tgt:`SOVERSION`
-is a fallback to :prop_tgt:`MACHO_COMPATIBILITY_VERSION` which corresponds
-to *compatiblity version*.  See the :prop_tgt:`FRAMEWORK` target
-property for an example.  Versions of Mach-O binaries may be checked with the
-``otool -L <binary>`` command.
+the :prop_tgt:`SOVERSION` property corresponds to the *compatibility version*
+and ``VERSION`` corresponds to the *current version* (unless Mach-O specific
+overrides are provided, as discussed below).
+See the :prop_tgt:`FRAMEWORK` target property for an example.
+
+For shared libraries, the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and
+:prop_tgt:`MACHO_CURRENT_VERSION` properties can be used to
+override the *compatibility version* and *current version* respectively.
+Note that :prop_tgt:`SOVERSION` will still be used to form the
+``install_name`` and both :prop_tgt:`SOVERSION` and ``VERSION`` may also
+affect the file and symlink names.
+
+Versions of Mach-O binaries may be checked with the ``otool -L <binary>``
+command.
diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst
index 0e182cfc2..c32b4dea3 100644
--- a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst
+++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst
@@ -38,3 +38,4 @@ The following target properties will be applied on the
 - :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING`
 - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT`
 - :prop_tgt:`XCODE_SCHEME_EXECUTABLE`
+- :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY`
diff --git a/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst
index 7ffa74bb4..f538f1da8 100644
--- a/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst
+++ b/Help/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY.rst
@@ -1,8 +1,8 @@
 XCODE_SCHEME_WORKING_DIRECTORY
 ------------------------------
 
-Specify the ``Working Directory`` a of the `Run` and `Profile`
-action in the generated Xcode scheme. In case the value contains
+Specify the ``Working Directory`` of the *Run* and *Profile*
+actions in the generated Xcode scheme. In case the value contains
 generator expressions those are evaluated.
 
 This property is initialized by the value of the variable
diff --git a/Help/release/3.15.rst b/Help/release/3.15.rst
index 957e6e958..e68e7d38b 100644
--- a/Help/release/3.15.rst
+++ b/Help/release/3.15.rst
@@ -332,6 +332,15 @@ Deprecated and Removed Features
 Other Changes
 =============
 
+* If a feature specified by :command:`target_compile_features` is available
+  in the compiler's default standard level, CMake 3.14 and below incorrectly
+  added unnecessary ``-std=`` flags that could lower the standard level.
+  This bug has been fixed in CMake 3.15.  This behavior change may expose
+  bugs in existing projects that were relying on undocumented implementation
+  details.  Specifying compile features only ensures that the compiler runs
+  in a mode that has those features, not that any specific standard level is
+  used or explicit ``-std=`` flag passed.
+
 * CMake learned how to compile C++14 with the IBM AIX XL compiler
   and the SunPro compiler and to compile C++20 with the AppleClang compiler.
 
diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst
index c2cfdf03f..7c5b44d9c 100644
--- a/Help/release/3.17.rst
+++ b/Help/release/3.17.rst
@@ -282,6 +282,8 @@ Deprecated and Removed Features
   option and cannot be fixed without breaking compatibility, and so have
   been superseded.
 
+* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.0 or later.
+
 Other Changes
 =============
 
@@ -319,3 +321,15 @@ Other Changes
 
 * The :generator:`Xcode` generator no longer hard-codes ``-Wmost``,
   ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags.
+
+Updates
+=======
+
+Changes made since CMake 3.17.0 include the following.
+
+3.17.1
+------
+
+* CMake 3.17.0 updated the :cpack_gen:`CPack NSIS Generator` with changes
+  that require NSIS 3.0 or later.  CMake 3.17.1 now enforces the use
+  of a sufficiently new version.
diff --git a/Help/variable/CMAKE_CROSS_CONFIGS.rst b/Help/variable/CMAKE_CROSS_CONFIGS.rst
index c850af204..94157f3bb 100644
--- a/Help/variable/CMAKE_CROSS_CONFIGS.rst
+++ b/Help/variable/CMAKE_CROSS_CONFIGS.rst
@@ -3,5 +3,13 @@ CMAKE_CROSS_CONFIGS
 
 Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
 configurations available from all ``build-<Config>.ninja`` files in the
-:generator:`Ninja Multi-Config` generator. See the generator's
-documentation for more details.
+:generator:`Ninja Multi-Config` generator.  This variable activates
+cross-config mode. Targets from each config specified in this variable can be
+built from any ``build-<Config>.ninja`` file. Custom commands will use the
+configuration native to ``build-<Config>.ninja``. If it is set to ``all``, all
+configurations from :variable:`CMAKE_CONFIGURATION_TYPES` are cross-configs. If
+it is not specified, or empty, each ``build-<Config>.ninja`` file will only
+contain build rules for its own configuration.
+
+The value of this variable must be a subset of
+:variable:`CMAKE_CONFIGURATION_TYPES`.
diff --git a/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst
index 62ee0d294..aa4f82dbd 100644
--- a/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst
+++ b/Help/variable/CMAKE_DEFAULT_BUILD_TYPE.rst
@@ -2,5 +2,11 @@ CMAKE_DEFAULT_BUILD_TYPE
 ------------------------
 
 Specifies the configuration to use by default in a ``build.ninja`` file in the
-:generator:`Ninja Multi-Config` generator. See the generator's documentation
-for more details.
+:generator:`Ninja Multi-Config` generator. If this variable is specified,
+``build.ninja`` uses build rules from ``build-<Config>.ninja`` by default. All
+custom commands are executed with this configuration. If the variable is not
+specified, the first item from :variable:`CMAKE_CONFIGURATION_TYPES` is used
+instead.
+
+The value of this variable must be one of the items from
+:variable:`CMAKE_CONFIGURATION_TYPES`.
diff --git a/Help/variable/CMAKE_DEFAULT_CONFIGS.rst b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst
index 86d8a5a49..84c642aa5 100644
--- a/Help/variable/CMAKE_DEFAULT_CONFIGS.rst
+++ b/Help/variable/CMAKE_DEFAULT_CONFIGS.rst
@@ -3,5 +3,17 @@ CMAKE_DEFAULT_CONFIGS
 
 Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of configurations
 to build for a target in ``build.ninja`` if no ``:<Config>`` suffix is specified in
-the :generator:`Ninja Multi-Config` generator.
-See the generator's documentation for more details.
+the :generator:`Ninja Multi-Config` generator. If it is set to ``all``, all
+configurations from :variable:`CMAKE_CROSS_CONFIGS` are used. If it is not
+specified, it defaults to :variable:`CMAKE_DEFAULT_BUILD_TYPE`.
+
+For example, if you set :variable:`CMAKE_DEFAULT_BUILD_TYPE` to ``Release``,
+but set :variable:`CMAKE_DEFAULT_CONFIGS` to ``Debug`` or ``all``, all
+``<target>`` aliases in ``build.ninja`` will resolve to ``<target>:Debug`` or
+``<target>:all``, but custom commands will still use the ``Release``
+configuration.
+
+The value of this variable must be a subset of :variable:`CMAKE_CROSS_CONFIGS`
+or be the same as :variable:`CMAKE_DEFAULT_BUILD_TYPE`. It must not be
+specified if :variable:`CMAKE_DEFAULT_BUILD_TYPE` or
+:variable:`CMAKE_CROSS_CONFIGS` is not used.
diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
index 33ffdd681..f5fd8ce9f 100644
--- a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
+++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
@@ -3,6 +3,7 @@ CMAKE_FIND_DEBUG_MODE
 
 Print extra find call information for the following commands to standard
 error:
+
 * :command:`find_program`
 * :command:`find_library`
 * :command:`find_file`
diff --git a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst
index a99c108c8..34524d1d6 100644
--- a/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst
+++ b/Help/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH.rst
@@ -9,5 +9,5 @@ any directories outside the project that are in the linker search path or
 contain linked library files.  The directories are appended after the
 value of the :prop_tgt:`INSTALL_RPATH` target property.
 
-This varibale is used to initialize the target property
+This variable is used to initialize the target property
 :prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` for all targets.
diff --git a/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst
index cc690f7b1..5bb790797 100644
--- a/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst
+++ b/Help/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY.rst
@@ -1,8 +1,8 @@
 CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
 ------------------------------------
 
-Specify the ``Working Directory`` a of the `Run` and `Profile`
-action in the generated Xcode scheme.
+Specify the ``Working Directory`` of the *Run* and *Profile*
+actions in the generated Xcode scheme.
 
 This variable initializes the
 :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY`