Merge branch 'master' into fileapi-version-doc

23 files changed, 188 insertions, 13 deletions

diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst
index 406f6be..7ef1071 100644
--- a/Help/cpack_gen/external.rst
+++ b/Help/cpack_gen/external.rst
@@ -281,3 +281,10 @@ Variables specific to CPack External generator
   It is invoked after (optional) staging took place and may
   run an external packaging tool. The script has access to
   the variables defined by the CPack config file.
+
+.. variable:: CPACK_EXTERNAL_BUILT_PACKAGES
+
+  The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the
+  full paths of generated package files.  CPack copy these files from the stage
+  directory back to the top build directory and possibly produce checksum files
+  if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.
diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst
index a1c1a6f..9b6774b 100644
--- a/Help/dev/maint.rst
+++ b/Help/dev/maint.rst
@@ -299,3 +299,28 @@ announcing that post-release development is open::
   before staging or merging.
 
 .. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development
+
+Initial Post-Release Development
+--------------------------------
+
+Deprecate policies more than 8 release series old by updating the
+policy range check in ``cmMakefile::SetPolicy``.
+Commit with a message such as::
+
+  Add deprecation warnings for policies CMP#### and below
+
+  The OLD behaviors of all policies are deprecated, but only by
+  documentation.  Add an explicit deprecation diagnostic for policies
+  introduced in CMake $OLDVER and below to encourage projects to port
+  away from setting policies to OLD.
+
+Update the ``cmake_policy`` version range generated by ``install(EXPORT)``
+in ``cmExportFileGenerator::GeneratePolicyHeaderCode`` to end at the
+previous release.  We use one release back since we now know all the
+policies added for that version.  Commit with a message such as::
+
+  export: Increase maximum policy version in exported files to $prev
+
+  The files generatd by `install(EXPORT)` and `export()` commands
+  are known to work with policies as of CMake $prev, so enable them
+  in sufficiently new CMake versions.
diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
index c911625..a47d5e0 100644
--- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
@@ -57,7 +57,11 @@ set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
 set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
 
 # install rules
-install(TARGETS MathFunctions tutorial_compiler_flags
+set(installable_libs MathFunctions tutorial_compiler_flags)
+if(TARGET SqrtLibrary)
+  list(APPEND installable_libs SqrtLibrary)
+endif()
+install(TARGETS ${installable_libs}
         DESTINATION lib
         EXPORT MathFunctionsTargets)
 install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt
index e0c0621..0bfe20c 100644
--- a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt
@@ -47,5 +47,9 @@ endif()
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
 # install rules
-install(TARGETS MathFunctions DESTINATION lib)
+set(installable_libs MathFunctions)
+if(TARGET SqrtLibrary)
+  list(APPEND installable_libs SqrtLibrary)
+endif()
+install(TARGETS ${installable_libs} DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
index 32f5e08..0d287ca 100644
--- a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
@@ -51,5 +51,9 @@ target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
 # install rules
-install(TARGETS MathFunctions DESTINATION lib)
+set(installable_libs MathFunctions tutorial_compiler_flags)
+if(TARGET SqrtLibrary)
+  list(APPEND installable_libs SqrtLibrary)
+endif()
+install(TARGETS ${installable_libs} DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
index 720ee64..ea3861c 100644
--- a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
@@ -53,7 +53,11 @@ target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
 # install rules
-install(TARGETS MathFunctions tutorial_compiler_flags
+set(installable_libs MathFunctions tutorial_compiler_flags)
+if(TARGET SqrtLibrary)
+  list(APPEND installable_libs SqrtLibrary)
+endif()
+install(TARGETS ${installable_libs}
         DESTINATION lib
         EXPORT MathFunctionsTargets)
 install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst
index 6e26de9..e7ea290 100644
--- a/Help/guide/tutorial/index.rst
+++ b/Help/guide/tutorial/index.rst
@@ -675,9 +675,9 @@ The first step is to update the starting section of the top-level
 
 Now that we have made MathFunctions always be used, we will need to update
 the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to
-create a SqrtLibrary that will conditionally be built when ``USE_MYMATH`` is
-enabled. Now, since this is a tutorial, we are going to explicitly require
-that SqrtLibrary is built statically.
+create a SqrtLibrary that will conditionally be built and installed when
+``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to
+explicitly require that SqrtLibrary is built statically.
 
 The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
 
@@ -703,7 +703,7 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 .. literalinclude:: Step10/MathFunctions/MathFunctions.h
   :language: c++
 
-At this point, if you build everything, you will notice that linking fails
+At this point, if you build everything, you may notice that linking fails
 as we are combining a static library without position independent code with a
 library that has position independent code. The solution to this is to
 explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst
index cc50952..a66c098 100644
--- a/Help/manual/cmake-file-api.7.rst
+++ b/Help/manual/cmake-file-api.7.rst
@@ -869,6 +869,24 @@ with members:
     A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``)
     of the toolchain is used to compile the source file.
 
+  ``languageStandard``
+    Optional member that is present when the language standard is set
+    explicitly (e.g. via :prop_tgt:`CXX_STANDARD`) or implicitly by
+    compile features.  Each entry is a JSON object with two members:
+
+    ``backtraces``
+      Optional member that is present when a CMake language backtrace to
+      the ``<LANG>_STANDARD`` setting is available.  If the language
+      standard was set implicitly by compile features those are used as
+      the backtrace(s).  It's possible for multiple compile features to
+      require the same language standard so there could be multiple
+      backtraces. The value is a JSON array with each entry being an
+      unsigned integer 0-based index into the ``backtraceGraph``
+      member's ``nodes`` array.
+
+    ``standard``
+      String representing the language standard.
+
   ``compileCommandFragments``
     Optional member that is present when fragments of the compiler command
     line invocation are available.  The value is a JSON array of entries
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 124da44..935f557 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -105,10 +105,11 @@ Variable Queries
 
 ``$<TARGET_EXISTS:target>``
   ``1`` if ``target`` exists, else ``0``.
-``$<CONFIG:cfg>``
-  ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison.
-  The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by
-  this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED`
+``$<CONFIG:cfgs>``
+  ``1`` if config is any one of the entires in ``cfgs``, else ``0``. This is a
+  case-insensitive comparison. The mapping in
+  :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this
+  expression when it is evaluated on a property on an :prop_tgt:`IMPORTED`
   target.
 ``$<PLATFORM_ID:platform_ids>``
   where ``platform_ids`` is a comma-separated list.
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index e98038a..3ceb1df 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,14 @@ Policies Introduced by CMake 3.18
 .. toctree::
    :maxdepth: 1
 
+   CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109>
+
+Policies Introduced by CMake 3.18
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
    CMP0108: A target cannot link to itself through an alias. </policy/CMP0108>
    CMP0107: An ALIAS target cannot overwrite another target. </policy/CMP0107>
    CMP0106: The Documentation module is removed. </policy/CMP0106>
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 9becfc6..72ecfc7 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -450,6 +450,9 @@ The options are:
 ``--component <comp>``
   Component-based install. Only install component ``<comp>``.
 
+``--default-directory-permissions <permissions>``
+  Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``.
+
 ``--prefix <prefix>``
   Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`.
 
@@ -566,7 +569,8 @@ Available commands are:
 
 ``compare_files [--ignore-eol] <file1> <file2>``
   Check if ``<file1>`` is same as ``<file2>``. If files are the same,
-  then returns ``0``, if not it returns ``1``.  The ``--ignore-eol`` option
+  then returns ``0``, if not it returns ``1``.  In case of invalid
+  arguments, it retruns 2. The ``--ignore-eol`` option
   implies line-wise comparison and ignores LF/CRLF differences.
 
 ``copy <file>... <destination>``
diff --git a/Help/policy/CMP0109.rst b/Help/policy/CMP0109.rst
new file mode 100644
index 0000000..7542c8f
--- /dev/null
+++ b/Help/policy/CMP0109.rst
@@ -0,0 +1,22 @@
+CMP0109
+-------
+
+:command:`find_program` requires permission to execute but not to read.
+
+In CMake 3.18 and below, the :command:`find_program` command on UNIX
+would find files that are readable without requiring execute permission,
+and would not find files that are executable without read permission.
+In CMake 3.19 and above, ``find_program`` now prefers to require execute
+permission but not read permission.  This policy provides compatibility
+with projects that have not been updated to expect the new behavior.
+
+The ``OLD`` behavior for this policy is for ``find_program`` to require
+read permission but not execute permission.
+The ``NEW`` behavior for this policy is for ``find_program`` to require
+execute permission but not read permission.
+
+This policy was introduced in CMake version 3.19.  CMake version |release|
+warns when the policy is not set and uses ``OLD`` behavior.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst
new file mode 100644
index 0000000..e4cc01e
--- /dev/null
+++ b/Help/release/dev/0-sample-topic.rst
@@ -0,0 +1,7 @@
+0-sample-topic
+--------------
+
+* This is a sample release note for the change in a topic.
+  Developers should add similar notes for each topic branch
+  making a noteworthy change.  Each document should be named
+  and titled to match the topic name to avoid merge conflicts.
diff --git a/Help/release/dev/CPACK_EXTERNAL_BUILT_PACKAGES.rst b/Help/release/dev/CPACK_EXTERNAL_BUILT_PACKAGES.rst
new file mode 100644
index 0000000..af446d2
--- /dev/null
+++ b/Help/release/dev/CPACK_EXTERNAL_BUILT_PACKAGES.rst
@@ -0,0 +1,4 @@
+CPACK_EXTERNAL_BUILT_PACKAGES
+-----------------------------
+
+* :cpack_gen:`CPack External Generator` learned the :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
diff --git a/Help/release/dev/FindSDL-update.rst b/Help/release/dev/FindSDL-update.rst
new file mode 100644
index 0000000..a85d2b9
--- /dev/null
+++ b/Help/release/dev/FindSDL-update.rst
@@ -0,0 +1,11 @@
+FindSDL-update
+--------------
+
+* The :module:`FindSDL` module now provides:
+
+  * imported target ``SDL::SDL``,
+
+  * result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``,
+
+  * version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
+    ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.
diff --git a/Help/release/dev/FindVulkan-glslc.rst b/Help/release/dev/FindVulkan-glslc.rst
new file mode 100644
index 0000000..246bc8f
--- /dev/null
+++ b/Help/release/dev/FindVulkan-glslc.rst
@@ -0,0 +1,10 @@
+FindVulkan-glslc
+----------------
+
+* The :module:`FindVulkan` module gained a new output variable
+  ``Vulkan_GLSLC_EXECUTABLE`` which contains the path to the
+  GLSL SPIR-V compiler.
+
+* The :module:`FindVulkan` module gained a new target
+  ``Vulkan::glslc`` which contains the path to the
+  GLSL SPIR-V compiler.
diff --git a/Help/release/dev/cpack-pre-and-post-build-scripts.rst b/Help/release/dev/cpack-pre-and-post-build-scripts.rst
new file mode 100644
index 0000000..bf7958b
--- /dev/null
+++ b/Help/release/dev/cpack-pre-and-post-build-scripts.rst
@@ -0,0 +1,5 @@
+cpack-pre-and-post-build-scripts
+--------------------------------
+
+* CPack learned the :variable:`CPACK_PRE_BUILD_SCRIPTS`, :variable:`CPACK_POST_BUILD_SCRIPTS`,
+  and :variable:`CPACK_PACKAGE_FILES` variables.
diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst
new file mode 100644
index 0000000..1dc01cc
--- /dev/null
+++ b/Help/release/dev/deprecate-policy-old.rst
@@ -0,0 +1,13 @@
+deprecate-policy-old
+--------------------
+
+* An explicit deprecation diagnostic was added for policy ``CMP0071``
+  (``CMP0071`` 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.
+
+* Compatibility with versions of CMake older than 2.8.12 is now deprecated
+  and will be removed from a future version.  Calls to
+  :command:`cmake_minimum_required` or :command:`cmake_policy` that set
+  the policy version to an older value now issue a deprecation diagnostic.
diff --git a/Help/release/dev/find_program-exe-no-read.rst b/Help/release/dev/find_program-exe-no-read.rst
new file mode 100644
index 0000000..161b5db
--- /dev/null
+++ b/Help/release/dev/find_program-exe-no-read.rst
@@ -0,0 +1,5 @@
+find_program-exe-no-read
+------------------------
+
+* The :command:`find_program` command now requires permission to execute
+  but not to read the file found.  See policy :policy:`CMP0109`.
diff --git a/Help/release/dev/install-default-directory-permissions.rst b/Help/release/dev/install-default-directory-permissions.rst
new file mode 100644
index 0000000..27cffee
--- /dev/null
+++ b/Help/release/dev/install-default-directory-permissions.rst
@@ -0,0 +1,5 @@
+install-default-directory-permissions
+-------------------------------------
+
+* The ``--install`` argument of the :manual:`cmake(1)` command line tool gained a
+  ``--default-directory-permissions`` argument.
diff --git a/Help/release/dev/remove-cmake-gui-qt4.rst b/Help/release/dev/remove-cmake-gui-qt4.rst
new file mode 100644
index 0000000..2b29b75
--- /dev/null
+++ b/Help/release/dev/remove-cmake-gui-qt4.rst
@@ -0,0 +1,5 @@
+remove-cmake-gui-qt4
+--------------------
+
+* :manual:`cmake-gui(1)` now requires Qt5. Support for compiling with Qt4 has
+  been removed.
diff --git a/Help/release/dev/visual-studio-android.rst b/Help/release/dev/visual-studio-android.rst
new file mode 100644
index 0000000..4e1a110
--- /dev/null
+++ b/Help/release/dev/visual-studio-android.rst
@@ -0,0 +1,7 @@
+visual-studio-android
+---------------------
+
+* The :ref:`Visual Studio Generators` for Visual Studio 2015 and above gained
+  support for the Visual Studio Tools for Android. This allows you to set
+  :variable:`CMAKE_SYSTEM_NAME` to `Android` to generate `.vcxproj` files for
+  the Android tools.
diff --git a/Help/release/index.rst b/Help/release/index.rst
index 4578b3a..cdc3e8b 100644
--- a/Help/release/index.rst
+++ b/Help/release/index.rst
@@ -7,6 +7,8 @@ CMake Release Notes
   This file should include the adjacent "dev.txt" file
   in development versions but not in release versions.
 
+.. include:: dev.txt
+
 Releases
 ========