Merge branch 'master' into ninja-multi-automoc-regression

.clang-format

@@ -20,6 +20,8 @@ SortUsingDeclarations: false
 SpaceAfterTemplateKeyword: true
 IncludeBlocks: Regroup
 IncludeCategories:
+  - Regex:           '^[<"]cmSTL\.hxx'
+    Priority:        -2
   - Regex:           '^[<"]cmConfigure\.h'
     Priority:        -1
   - Regex:           '^<queue>'

.gitlab/artifacts.yml

@@ -34,10 +34,12 @@
             - build/Tests/CMake*/PseudoMemcheck/purify
             - build/Tests/CMake*/PseudoMemcheck/memcheck_fail
             - build/Tests/CMake*/PseudoMemcheck/BC
+            - build/Tests/CMake*/PseudoMemcheck/cuda-memcheck
             - build/Tests/CMake*/PseudoMemcheck/valgrind.exe
             - build/Tests/CMake*/PseudoMemcheck/purify.exe
             - build/Tests/CMake*/PseudoMemcheck/memcheck_fail.exe
             - build/Tests/CMake*/PseudoMemcheck/BC.exe
+            - build/Tests/CMake*/PseudoMemcheck/cuda-memcheck.exe
             - build/Tests/CMake*/PseudoMemcheck/NoLog
             - build/Tests/CMake*Lib/*LibTests
             - build/Tests/CMake*Lib/*LibTests.exe

.gitlab/ci/configure_fedora31_common.cmake

@@ -1,4 +1,5 @@
 set(BUILD_CursesDialog ON CACHE BOOL "")
 set(BUILD_QtDialog ON CACHE BOOL "")
 
+
 include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")

.gitlab/ci/configure_fedora31_makefiles.cmake

@@ -1 +1,2 @@
+set(CMake_TEST_ISPC "ON" CACHE STRING "")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")

.gitlab/ci/configure_fedora31_ninja.cmake

@@ -1 +1,2 @@
+set(CMake_TEST_ISPC "ON" CACHE STRING "")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora31_common.cmake")

.gitlab/ci/configure_fedora31_ninja_multi.cmake

@@ -1 +1,2 @@
+set(CMake_TEST_ISPC "ON" CACHE STRING "")
 include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")

.gitlab/ci/docker/fedora31/Dockerfile

@@ -3,3 +3,6 @@ MAINTAINER Ben Boeckel <[email protected]>
 
 COPY install_deps.sh /root/install_deps.sh
 RUN sh /root/install_deps.sh
+
+COPY install_ispc.sh /root/install_ispc.sh
+RUN sh /root/install_ispc.sh

.gitlab/ci/docker/fedora31/install_ispc.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+set -e
+
+readonly version="1.13.0"
+readonly sha256sum="8ab1189bd5db596b3eee9d9465d3528b6626a7250675d67102761bb0d284cd21"
+
+readonly filename="ispc-v$version-linux"
+readonly tarball="$filename.tar.gz"
+
+echo "$sha256sum  $tarball" > ispc.sha256sum
+curl -OL "https://github.com/ispc/ispc/releases/download/v$version/$tarball"
+sha256sum --check ispc.sha256sum
+tar --strip-components=1 -C /usr/local -xf "$tarball" "$filename/bin/ispc"

.gitlab/os-linux.yml

@@ -30,7 +30,7 @@
 ### Fedora
 
 .fedora31:
-    image: "kitware/cmake:ci-fedora31-x86_64-2020-06-01"
+    image: "kitware/cmake:ci-fedora31-x86_64-2020-08-18"
 
     variables:
         GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci"

Auxiliary/vim/syntax/cmake.vim

@@ -1048,6 +1048,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_HOST_UNIX
             \ CMAKE_HOST_WIN32
             \ CMAKE_IGNORE_PATH
+            \ CMAKE_ISPC_HEADER_DIRECTORY
             \ CMAKE_IMPORT_LIBRARY_PREFIX
             \ CMAKE_IMPORT_LIBRARY_SUFFIX
             \ CMAKE_INCLUDE_CURRENT_DIR

CMakeLists.txt

@@ -108,6 +108,11 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
   endif()
 endif()
 
+# Inform STL library header wrappers whether to use system versions.
+configure_file(${CMake_SOURCE_DIR}/Utilities/std/cmSTL.hxx.in
+  ${CMake_BINARY_DIR}/Utilities/cmSTL.hxx
+  @ONLY)
+
 # set the internal encoding of CMake to UTF-8
 set(KWSYS_ENCODING_DEFAULT_CODEPAGE CP_UTF8)
 

CTestConfig.cmake

@@ -6,7 +6,9 @@
 set(CTEST_PROJECT_NAME "CMake")
 set(CTEST_NIGHTLY_START_TIME "1:00:00 UTC")
 
-set(CTEST_DROP_METHOD "http")
+if(NOT CTEST_DROP_METHOD STREQUAL "https")
+  set(CTEST_DROP_METHOD "http")
+endif()
 set(CTEST_DROP_SITE "open.cdash.org")
 set(CTEST_DROP_LOCATION "/submit.php?project=CMake")
 set(CTEST_DROP_SITE_CDASH TRUE)

Help/command/add_compile_definitions.rst

@@ -1,6 +1,8 @@
 add_compile_definitions
 -----------------------
 
+.. versionadded:: 3.12
+
 Add preprocessor definitions to the compilation of source files.
 
 .. code-block:: cmake

Help/command/add_custom_command.rst

@@ -102,13 +102,22 @@ The options are:
   a target later in the command line (i.e. as a command argument rather
   than as the command to execute).
 
-  Whenever a target is used as a command to execute or is mentioned in a
-  generator expression as a command argument, a target-level dependency
-  will be added automatically so that the mentioned target will be built
-  before any target using this custom command.  However this does NOT add
-  a file-level dependency that would cause the custom command to re-run
-  whenever the executable is recompiled.  List target names with
-  the ``DEPENDS`` option to add such file-level dependencies.
+  Whenever one of the following target based generator expressions are used as
+  a command to execute or is mentioned in a command argument, a target-level
+  dependency will be added automatically so that the mentioned target will be
+  built before any target using this custom command
+  (see policy :policy:`CMP0112`).
+
+    * ``TARGET_FILE``
+    * ``TARGET_LINKER_FILE``
+    * ``TARGET_SONAME_FILE``
+    * ``TARGET_PDB_FILE``
+
+  This target-level dependency does NOT add a file-level dependency that would
+  cause the custom command to re-run whenever the executable is recompiled.
+  List target names with the ``DEPENDS`` option to add such file-level
+  dependencies.
+
 
 ``COMMENT``
   Display the given message before the commands are executed at

Help/command/add_custom_target.rst

@@ -81,10 +81,15 @@ The options are:
   a target later in the command line (i.e. as a command argument rather
   than as the command to execute).
 
-  Whenever a target is used as a command to execute or is mentioned in a
-  generator expression as a command argument, a target-level dependency
-  will be added automatically so that the mentioned target will be built
-  before this custom target.
+  Whenever one of the following target based generator expressions are used as
+  a command to execute or is mentioned in a command argument, a target-level
+  dependency will be added automatically so that the mentioned target will be
+  built before this custom target (see policy :policy:`CMP0112`).
+
+    * ``TARGET_FILE``
+    * ``TARGET_LINKER_FILE``
+    * ``TARGET_SONAME_FILE``
+    * ``TARGET_PDB_FILE``
 
   The command and arguments are optional and if not specified an empty
   target will be created.

Help/command/add_library.rst

@@ -64,42 +64,6 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
 pre-processed, and you want to have the original sources reachable from
 within IDE.
 
-Imported Libraries
-^^^^^^^^^^^^^^^^^^
-
-.. code-block:: cmake
-
-  add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
-              [GLOBAL])
-
-An :ref:`IMPORTED library target <Imported Targets>` references a library
-file located outside the project.  No rules are generated to build it, and
-the :prop_tgt:`IMPORTED` target property is ``True``.  The target name has
-scope in the directory in which it is created and below, but the ``GLOBAL``
-option extends visibility.  It may be referenced like any target built
-within the project.  ``IMPORTED`` libraries are useful for convenient
-reference from commands like :command:`target_link_libraries`.  Details
-about the imported library are specified by setting properties whose names
-begin in ``IMPORTED_`` and ``INTERFACE_``.
-
-The most important properties are:
-
-* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
-  variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
-  location of the main library file on disk.
-* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
-  for object libraries, specifies the locations of object files on disk.
-* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation
-
-See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
-for more information.
-
-An ``UNKNOWN`` library type is typically only used in the implementation of
-:ref:`Find Modules`.  It allows the path to an imported library (often found
-using the :command:`find_library` command) to be used without having to know
-what type of library it is.  This is especially useful on Windows where a
-static library and a DLL's import library both have the same file extension.
-
 Object Libraries
 ^^^^^^^^^^^^^^^^
 
@@ -129,6 +93,112 @@ systems (such as Xcode) may not like targets that have only object files, so
 consider adding at least one real source file to any target that references
 ``$<TARGET_OBJECTS:objlib>``.
 
+Interface Libraries
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: cmake
+
+  add_library(<name> INTERFACE)
+
+Creates an :ref:`Interface Library <Interface Libraries>`.
+An ``INTERFACE`` library target does not compile sources and does
+not produce a library artifact on disk.  However, it may have
+properties set on it and it may be installed and exported.
+Typically, ``INTERFACE_*`` properties are populated on an interface
+target using the commands:
+
+* :command:`set_property`,
+* :command:`target_link_libraries(INTERFACE)`,
+* :command:`target_link_options(INTERFACE)`,
+* :command:`target_include_directories(INTERFACE)`,
+* :command:`target_compile_options(INTERFACE)`,
+* :command:`target_compile_definitions(INTERFACE)`, and
+* :command:`target_sources(INTERFACE)`,
+
+and then it is used as an argument to :command:`target_link_libraries`
+like any other target.
+
+An interface library created with the above signature has no source files
+itself and is not included as a target in the generated buildsystem.
+
+Since CMake 3.19, an interface library target may be created with
+source files:
+
+.. code-block:: cmake
+
+  add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
+
+Source files may be listed directly in the ``add_library`` call or added
+later by calls to :command:`target_sources` with the ``PRIVATE`` or
+``PUBLIC`` keywords.
+
+If an interface library has source files (i.e. the :prop_tgt:`SOURCES`
+target property is set), it will appear in the generated buildsystem
+as a build target much like a target defined by the
+:command:`add_custom_target` command.  It does not compile any sources,
+but does contain build rules for custom commands created by the
+:command:`add_custom_command` command.
+
+.. note::
+  In most command signatures where the ``INTERFACE`` keyword appears,
+  the items listed after it only become part of that target's usage
+  requirements and are not part of the target's own settings.  However,
+  in this signature of ``add_library``, the ``INTERFACE`` keyword refers
+  to the library type only.  Sources listed after it in the ``add_library``
+  call are ``PRIVATE`` to the interface library and do not appear in its
+  :prop_tgt:`INTERFACE_SOURCES` target property.
+
+Imported Libraries
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: cmake
+
+  add_library(<name> <type> IMPORTED [GLOBAL])
+
+Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
+No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
+property is ``True``.  The target name has scope in the directory in which
+it is created and below, but the ``GLOBAL`` option extends visibility.
+It may be referenced like any target built within the project.
+``IMPORTED`` libraries are useful for convenient reference from commands
+like :command:`target_link_libraries`.  Details about the imported library
+are specified by setting properties whose names begin in ``IMPORTED_`` and
+``INTERFACE_``.
+
+The ``<type>`` must be one of:
+
+``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
+  References a library file located outside the project.  The
+  :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
+  variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
+  location of the main library file on disk.  In the case of a ``SHARED``
+  library on Windows, the :prop_tgt:`IMPORTED_IMPLIB` target property
+  (or its per-configuration variant :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`)
+  specifies the location of the DLL import library file (``.lib`` or
+  ``.dll.a``) on disk, and the ``IMPORTED_LOCATION`` is the location of
+  the ``.dll`` runtime library (and is optional).
+  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
+
+  An ``UNKNOWN`` library type is typically only used in the implementation of
+  :ref:`Find Modules`.  It allows the path to an imported library (often found
+  using the :command:`find_library` command) to be used without having to know
+  what type of library it is.  This is especially useful on Windows where a
+  static library and a DLL's import library both have the same file extension.
+
+``OBJECT``
+  References a set of object files located outside the project.
+  The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
+  variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
+  object files on disk.
+  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
+
+``INTERFACE``
+  Does not reference any library or object files on disk, but may
+  specify usage requirements in ``INTERFACE_*`` properties.
+
+See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
+for more information.
+
 Alias Libraries
 ^^^^^^^^^^^^^^^
 
@@ -153,35 +223,3 @@ to modify properties of ``<target>``, that is, it may not be used as the
 operand of :command:`set_property`, :command:`set_target_properties`,
 :command:`target_link_libraries` etc.  An ``ALIAS`` target may not be
 installed or exported.
-
-Interface Libraries
-^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: cmake
-
-  add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
-
-Creates an :ref:`Interface Library <Interface Libraries>`.  An ``INTERFACE``
-library target does not directly create build output, though it may
-have properties set on it and it may be installed, exported and
-imported. Typically the ``INTERFACE_*`` properties are populated on
-the interface target using the commands:
-
-* :command:`set_property`,
-* :command:`target_link_libraries(INTERFACE)`,
-* :command:`target_link_options(INTERFACE)`,
-* :command:`target_include_directories(INTERFACE)`,
-* :command:`target_compile_options(INTERFACE)`,
-* :command:`target_compile_definitions(INTERFACE)`, and
-* :command:`target_sources(INTERFACE)`,
-
-and then it is used as an argument to :command:`target_link_libraries`
-like any other target.
-
-An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be
-created with this signature.  An ``IMPORTED`` library target references a
-library defined outside the project.  The target name has scope in the
-directory in which it is created and below, but the ``GLOBAL`` option
-extends visibility.  It may be referenced like any target built within
-the project.  ``IMPORTED`` libraries are useful for convenient reference
-from commands like :command:`target_link_libraries`.

Help/command/add_link_options.rst

@@ -1,6 +1,8 @@
 add_link_options
 ----------------
 
+.. versionadded:: 3.13
+
 Add options to the link step for executable, shared library or module
 library targets in the current directory and below that are added after
 this command is invoked.

Help/command/add_test.rst

@@ -10,8 +10,9 @@ Add a test to the project to be run by :manual:`ctest(1)`.
            [WORKING_DIRECTORY <dir>]
            [COMMAND_EXPAND_LISTS])
 
-Adds a test called ``<name>``.  The test name may not contain spaces,
-quotes, or other characters special in CMake syntax.  The options are:
+Adds a test called ``<name>``.  The test name may contain arbitrary
+characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument`
+if necessary.  See policy :policy:`CMP0110`.  The options are:
 
 ``COMMAND``
   Specify the test command-line.  If ``<command>`` specifies an

Help/command/cmake_language.rst

@@ -1,6 +1,8 @@
 cmake_language
 --------------
 
+.. versionadded:: 3.18
+
 Call meta-operations on CMake commands.
 
 Synopsis

Help/command/cmake_parse_arguments.rst

@@ -1,6 +1,8 @@
 cmake_parse_arguments
 ---------------------
 
+.. versionadded:: 3.5
+
 Parse function or macro arguments.
 
 .. code-block:: cmake

Help/command/configure_file.rst

@@ -7,6 +7,7 @@ Copy a file to another location and modify its contents.
 
   configure_file(<input> <output>
                  [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
+                 [NO_SOURCE_PERMISSIONS]
                  [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
 
 Copies an ``<input>`` file to an ``<output>`` file and substitutes
@@ -82,6 +83,11 @@ The arguments are:
   Restrict variable replacement to references of the form ``@VAR@``.
   This is useful for configuring scripts that use ``${VAR}`` syntax.
 
+ ``NO_SOURCE_PERMISSIONS``
+  Does not transfer the file permissions of the original file to the copy.
+  The copied file permissions default to the standard 644 value
+  (-rw-r--r--).
+
 ``NEWLINE_STYLE <style>``
   Specify the newline style for the output file.  Specify
   ``UNIX`` or ``LF`` for ``\n`` newlines, or specify

Help/command/continue.rst

@@ -1,6 +1,8 @@
 continue
 --------
 
+.. versionadded:: 3.2
+
 Continue to the top of enclosing foreach or while loop.
 
 .. code-block:: cmake

Help/command/enable_language.rst

@@ -9,7 +9,8 @@ Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
 Enables support for the named language in CMake.  This is
 the same as the :command:`project` command but does not create any of the extra
 variables that are created by the project command.  Example languages
-are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, and ``ASM``.
+are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``,
+``ISPC``, and ``ASM``.
 
 If enabling ``ASM``, enable it last so that CMake can check whether
 compilers for other languages like ``C`` work for assembly too.

Help/command/file.rst

@@ -30,6 +30,8 @@ Synopsis
     file(`SIZE`_ <filename> <out-var>)
     file(`READ_SYMLINK`_ <linkname> <out-var>)
     file(`CREATE_LINK`_ <original> <linkname> [...])
+    file(`CHMOD`_ <files>... <directories>... PERMISSIONS <permissions>... [...])
+    file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...])
 
   `Path Conversion`_
     file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
@@ -449,7 +451,7 @@ modified.
 
   file(GENERATE OUTPUT output-file
        <INPUT input-file|CONTENT content>
-       [CONDITION expression])
+       [CONDITION expression] [TARGET target])
 
 Generate an output file for each build configuration supported by the current
 :manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
@@ -479,6 +481,10 @@ from the input content to produce the output content.  The options are:
   with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
   See policy :policy:`CMP0070`.
 
+``TARGET <target>``
+  Specify target which to use when evaluating generator expressions.  Enables
+  use of generator expressions requiring a target.
+
 Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
 ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
 Generated files are modified and their timestamp updated on subsequent cmake
@@ -737,6 +743,51 @@ creating the link fails.  It can be useful for handling situations such as
 ``<original>`` and ``<linkname>`` being on different drives or mount points,
 which would make them unable to support a hard link.
 
+.. _CHMOD:
+
+.. code-block:: cmake
+
+  file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...]
+      [FILE_PERMISSIONS <permissions>...]
+      [DIRECTORY_PERMISSIONS <permissions>...])
+
+Set the permissions for the ``<files>...`` and ``<directories>...`` specified.
+Valid permissions are  ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``,
+``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``,
+``WORLD_WRITE``, ``WORLD_EXECUTE``.
+
+Valid combination of keywords are:
+
+``PERMISSIONS``
+  all items are changed
+
+``FILE_PERMISSIONS``
+  only files are changed
+
+``DIRECTORY_PERMISSIONS``
+  only directories are changed
+
+``PERMISSIONS`` and ``FILE_PERMISSIONS``
+  ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files
+
+``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
+  ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories
+
+``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
+  use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
+  directories
+
+
+.. _CHMOD_RECURSE:
+
+.. code-block:: cmake
+
+  file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>...
+       FILE_PERMISSIONS <permissions>... DIRECTORY_PERMISSIONS <permissions>...)
+
+Same as `CHMOD`_, but change the permissions of files and directories present in
+the ``<directories>..`` recursively.
+
 Path Conversion
 ^^^^^^^^^^^^^^^
 
@@ -776,11 +827,14 @@ Transfer
 
 .. code-block:: cmake
 
-  file(DOWNLOAD <url> <file> [<options>...])
+  file(DOWNLOAD <url> [<file>] [<options>...])
   file(UPLOAD   <file> <url> [<options>...])
 
-The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``.
-The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``.
+The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``. If
+``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. This
+can be useful if you want to know if a file can be downloaded (for example, to
+check that it exists) without actually saving it anywhere. The ``UPLOAD`` mode
+uploads a local ``<file>`` to a given ``<url>``.
 
 Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 
@@ -853,10 +907,12 @@ Additional options to ``DOWNLOAD`` are:
 
   Verify that the downloaded content hash matches the expected value, where
   ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``.
-  If it does not match, the operation fails with an error.
+  If it does not match, the operation fails with an error. It is an error to
+  specify this if ``DOWNLOAD`` is not given a ``<file>``.
 
 ``EXPECTED_MD5 <value>``
-  Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
+  Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to
+  specify this if ``DOWNLOAD`` is not given a ``<file>``.
 
 Locking
 ^^^^^^^

Help/command/include_guard.rst

@@ -1,6 +1,8 @@
 include_guard
 -------------
 
+.. versionadded:: 3.10
+
 Provides an include guard for the file currently being processed by CMake.
 
 .. code-block:: cmake

Help/command/install.rst

@@ -45,6 +45,9 @@ signatures that specify them.  The common options are:
 
   As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer
   generators, it is preferable to use relative paths throughout.
+  In particular, there is no need to make paths absolute by prepending
+  :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if
+  the DESTINATION is a relative path.
 
 ``PERMISSIONS``
   Specify permissions for installed files.  Valid permissions are

Help/command/project.rst

@@ -88,7 +88,7 @@ The options are:
 
   Selects which programming languages are needed to build the project.
   Supported languages include ``C``, ``CXX`` (i.e.  C++), ``CUDA``,
-  ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, and ``ASM``.
+  ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``ISPC``, and ``ASM``.
   By default ``C`` and ``CXX`` are enabled if no language options are given.
   Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
   to skip enabling any languages.

Help/command/target_compile_features.rst

@@ -1,6 +1,8 @@
 target_compile_features
 -----------------------
 
+.. versionadded:: 3.1
+
 Add expected compiler features to a target.
 
 .. code-block:: cmake

Help/command/target_link_directories.rst

@@ -1,6 +1,8 @@
 target_link_directories
 -----------------------
 
+.. versionadded:: 3.13
+
 Add link directories to a target.
 
 .. code-block:: cmake

Help/command/target_link_options.rst

@@ -1,6 +1,8 @@
 target_link_options
 -------------------
 
+.. versionadded:: 3.13
+
 Add options to the link step for an executable, shared library or module
 library target.
 

Help/command/target_precompile_headers.rst

@@ -1,6 +1,8 @@
 target_precompile_headers
 -------------------------
 
+.. versionadded:: 3.16
+
 Add a list of header files to precompile.
 
 Precompiling header files can speed up compilation by creating a partially

Help/command/target_sources.rst

@@ -1,6 +1,8 @@
 target_sources
 --------------
 
+.. versionadded:: 3.1
+
 Add sources to a target.
 
 .. code-block:: cmake
@@ -9,19 +11,21 @@ Add sources to a target.
     <INTERFACE|PUBLIC|PRIVATE> [items1...]
     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
 
-Specifies sources to use when compiling a given target.  Relative
-source file paths are interpreted as being relative to the current
+Specifies sources to use when building a target and/or its dependents.
+Relative source file paths are interpreted as being relative to the current
 source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).  The
 named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
 :ref:`ALIAS target <Alias Targets>`.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
+specify the scope of the items following them.  ``PRIVATE`` and ``PUBLIC``
 items will populate the :prop_tgt:`SOURCES` property of
-``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
-:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``.
-(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
+``<target>``, which are used when building the target itself.
+``PUBLIC`` and ``INTERFACE`` items will populate the
+:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
+when building dependents.  (:ref:`IMPORTED targets <Imported Targets>`
+only support ``INTERFACE`` items because they are not build targets.)
 The following arguments specify sources.  Repeated calls for the same
 ``<target>`` append items in the order called.
 

Help/command/variable_watch.rst

@@ -7,9 +7,42 @@ Watch the CMake variable for change.
 
   variable_watch(<variable> [<command>])
 
-If the specified ``<variable>`` changes, a message will be printed
-to inform about the change.
+If the specified ``<variable>`` changes and no ``<command>`` is given,
+a message will be printed to inform about the change.
 
-Additionally, if ``<command>`` is given, this command will be executed.
+If ``<command>`` is given, this command will be executed instead.
 The command will receive the following arguments:
 ``COMMAND(<variable> <access> <value> <current_list_file> <stack>)``
+
+``<variable>``
+ Name of the variable being accessed.
+
+``<access>``
+ One of ``READ_ACCESS``, ``UNKNOWN_READ_ACCESS``, ``MODIFIED_ACCESS``,
+ ``UNKNOWN_MODIFIED_ACCESS``, or ``REMOVED_ACCESS``.  The ``UNKNOWN_``
+ values are only used when the variable has never been set.  Once set,
+ they are never used again during the same CMake run, even if the
+ variable is later unset.
+
+``<value>``
+ The value of the variable.  On a modification, this is the new
+ (modified) value of the variable.  On removal, the value is empty.
+
+``<current_list_file>``
+ Full path to the file doing the access.
+
+``<stack>``
+ List of absolute paths of all files currently on the stack of file
+ inclusion, with the bottom-most file first and the currently
+ processed file (that is, ``current_list_file``) last.
+
+Note that for some accesses such as :command:`list(APPEND)`, the watcher
+is executed twice, first with a read access and then with a write one.
+Also note that an :command:`if(DEFINED)` query on the variable does not
+register as an access and the watcher is not executed.
+
+Only non-cache variables can be watched using this command.  Access to
+cache variables is never watched.  However, the existence of a cache
+variable ``var`` causes accesses to the non-cache variable ``var`` to
+not use the ``UNKNOWN_`` prefix, even if a non-cache variable ``var``
+has never existed.

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.

Help/cpack_gen/packagemaker.rst

@@ -29,7 +29,7 @@ macOS using PackageMaker:
 
 .. variable:: CPACK_PACKAGEMAKER_BACKGROUND
 
- Adds a background to Distribtion XML if specified. The value contains the
+ Adds a background to Distribution XML if specified. The value contains the
  path to image in ``Resources`` directory.
 
 .. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT

Help/cpack_gen/productbuild.rst

@@ -68,7 +68,7 @@ macOS using ProductBuild:
 
 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND
 
- Adds a background to Distribtion XML if specified. The value contains the
+ Adds a background to Distribution XML if specified. The value contains the
  path to image in ``Resources`` directory.
 
 .. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT

Help/cpack_gen/wix.rst

@@ -286,3 +286,11 @@ Windows using WiX.
 
  When unspecified CPack will try to locate a WiX Toolset
  installation via the ``WIX`` environment variable instead.
+
+.. variable:: CPACK_WIX_CUSTOM_XMLNS
+
+ This variable provides a list of custom namespace declarations that are necessary
+ for using WiX extensions. Each declaration should be in the form name=url, where
+ name is the plain namespace without the usual xmlns: prefix and url is an unquoted
+ namespace url. A list of commonly known WiX schemata can be found here:
+ https://wixtoolset.org/documentation/manual/v3/xsd/

Help/dev/maint.rst

@@ -200,6 +200,23 @@ the notes, and revise wording.  Then commit with a message such as::
   Add section headers similar to the $prev release notes and move each
   individual bullet into an appropriate section.  Revise a few bullets.
 
+Update Sphinx ``versionadded`` directives in documents added since
+the previous release by running the `update_versions.py`_ script:
+
+.. code-block:: shell
+
+  Utilities/Sphinx/update_versions.py --since v$prev.0 --overwrite
+
+.. _`update_versions.py`: ../../Utilities/Sphinx/update_versions.py
+
+Commit the changes with a message such as::
+
+  Help: Update Sphinx versionadded directives for $ver release
+
+  Run the script:
+
+      Utilities/Sphinx/update_versions.py --since v$prev.0 --overwrite
+
 Open a merge request with the ``doc-$ver-relnotes`` branch for review
 and integration.  Further steps may proceed after this has been merged
 to ``master``.
@@ -299,3 +316,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.

Help/dev/review.rst

@@ -260,10 +260,11 @@ This may be generated with
 If the commit is a fix for the mentioned commit, consider using a ``Fixes:``
 trailer in the commit message with the specified format. This trailer should
 not be word-wrapped. Note that if there is also an issue for what is being
-fixed, it is preferrable to link to the issue instead.
+fixed, it is preferable to link to the issue instead.
 
 If relevant, add the first release tag of CMake containing the commit after
 the ``<date>``, i.e., ``commit <shorthash> (<subject>, <date>, <tag>)``.
+Or, use the output of ``git describe --contains <commit>`` as the ``<tag>``.
 
 Alternatively, the full commit ``<hash>`` may be used.
 

Help/dev/source.rst

@@ -35,6 +35,9 @@ Available features are:
 
 * From ``C++14``:
 
+  * ``<cm/iomanip>``:
+    ``cm::quoted``
+
   * ``<cm/iterator>``:
     ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``,
     ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend``
@@ -53,6 +56,9 @@ Available features are:
   * ``<cm/algorithm>``:
     ``cm::clamp``
 
+  * ``cm/filesystem>``:
+    ``cm::filesystem::path``
+
   * ``<cm/iterator>``:
     ``cm::size``, ``cm::empty``, ``cm::data``
 

Help/envvar/ASM_DIALECT.rst

@@ -1,6 +1,8 @@
 ASM<DIALECT>
 ------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling a specific dialect of assembly language
@@ -12,3 +14,11 @@ in the cache as
 :variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. For subsequent
 configuration runs, the environment variable will be ignored in favor of
 :variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`.
+
+.. note::
+  Options that are required to make the compiler work correctly can be included;
+  they can not be changed.
+
+.. code-block:: console
+
+  $ export ASM="custom-compiler --arg1 --arg2"

Help/envvar/ASM_DIALECTFLAGS.rst

@@ -1,6 +1,8 @@
 ASM<DIALECT>FLAGS
 -----------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Default compilation flags to be used when compiling a specific dialect of an

Help/envvar/CC.rst

@@ -1,6 +1,8 @@
 CC
 --
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``C`` language files. Will only be used by
@@ -9,3 +11,11 @@ value for ``CC`` is stored in the cache as
 :variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run
 (including the first), the environment variable will be ignored if the
 :variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+  Options that are required to make the compiler work correctly can be included;
+  they can not be changed.
+
+.. code-block:: console
+
+  $ export CC="custom-compiler --arg1 --arg2"

Help/envvar/CCMAKE_COLORS.rst

@@ -1,6 +1,8 @@
 CCMAKE_COLORS
 -------------
 
+.. versionadded:: 3.18
+
 Determines what colors are used by the CMake curses interface,
 when run on a terminal that supports colors.
 The syntax follows the same conventions as ``LS_COLORS``;

Help/envvar/CFLAGS.rst

@@ -1,6 +1,8 @@
 CFLAGS
 ------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Default compilation flags to be used when compiling ``C`` files. Will only be

Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst

@@ -1,6 +1,8 @@
 CMAKE_BUILD_PARALLEL_LEVEL
 --------------------------
 
+.. versionadded:: 3.12
+
 .. include:: ENV_VAR.txt
 
 Specifies the maximum number of concurrent processes to use when building

Help/envvar/CMAKE_CONFIG_TYPE.rst

@@ -1,6 +1,8 @@
 CMAKE_CONFIG_TYPE
 -----------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 The default build configuration for :ref:`Build Tool Mode` and

Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst

@@ -1,6 +1,8 @@
 CMAKE_EXPORT_COMPILE_COMMANDS
 -----------------------------
 
+.. versionadded:: 3.17
+
 .. include:: ENV_VAR.txt
 
 The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there

Help/envvar/CMAKE_GENERATOR.rst

@@ -1,6 +1,8 @@
 CMAKE_GENERATOR
 ---------------
 
+.. versionadded:: 3.15
+
 .. include:: ENV_VAR.txt
 
 Specifies the CMake default generator to use when no generator is supplied

Help/envvar/CMAKE_GENERATOR_INSTANCE.rst

@@ -1,6 +1,8 @@
 CMAKE_GENERATOR_INSTANCE
 ------------------------
 
+.. versionadded:: 3.15
+
 .. include:: ENV_VAR.txt
 
 Default value for :variable:`CMAKE_GENERATOR_INSTANCE` if no Cache entry is

Help/envvar/CMAKE_GENERATOR_PLATFORM.rst

@@ -1,6 +1,8 @@
 CMAKE_GENERATOR_PLATFORM
 ------------------------
 
+.. versionadded:: 3.15
+
 .. include:: ENV_VAR.txt
 
 Default value for :variable:`CMAKE_GENERATOR_PLATFORM` if no Cache entry

Help/envvar/CMAKE_GENERATOR_TOOLSET.rst

@@ -1,6 +1,8 @@
 CMAKE_GENERATOR_TOOLSET
 -----------------------
 
+.. versionadded:: 3.15
+
 .. include:: ENV_VAR.txt
 
 Default value for :variable:`CMAKE_GENERATOR_TOOLSET` if no Cache entry

Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst

@@ -1,6 +1,8 @@
 CMAKE_<LANG>_COMPILER_LAUNCHER
 ------------------------------
 
+.. versionadded:: 3.17
+
 .. include:: ENV_VAR.txt
 
 Default compiler launcher to use for the specified language. Will only be used

Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst

@@ -1,6 +1,8 @@
 CMAKE_MSVCIDE_RUN_PATH
 ----------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Extra PATH locations for custom commands when using

Help/envvar/CMAKE_NO_VERBOSE.rst

@@ -1,6 +1,8 @@
 CMAKE_NO_VERBOSE
 ----------------
 
+.. versionadded:: 3.14
+
 Disables verbose output from CMake when :envvar:`VERBOSE` environment variable
 is set.
 

Help/envvar/CMAKE_OSX_ARCHITECTURES.rst

@@ -1,6 +1,8 @@
 CMAKE_OSX_ARCHITECTURES
 -----------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Target specific architectures for macOS.

Help/envvar/CMAKE_PREFIX_PATH.rst

@@ -1,6 +1,8 @@
 CMAKE_PREFIX_PATH
 -----------------
 
+.. versionadded:: 3.18
+
 .. include:: ENV_VAR.txt
 
 The ``CMAKE_PREFIX_PATH`` environment variable may be set to a list of

Help/envvar/CSFLAGS.rst

@@ -1,9 +1,11 @@
 CSFLAGS
 -------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
-Preferred executable for compiling ``CSharp`` language files. Will only be
+Default compilation flags to be used when compiling ``CSharp`` files. Will only be
 used by CMake on the first configuration to determine ``CSharp`` default
 compilation flags, after which the value for ``CSFLAGS`` is stored in the cache
 as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration

Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst

@@ -1,6 +1,8 @@
 CTEST_INTERACTIVE_DEBUG_MODE
 ----------------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Environment variable that will exist and be set to ``1`` when a test executed

Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst

@@ -1,6 +1,8 @@
 CTEST_OUTPUT_ON_FAILURE
 -----------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Boolean environment variable that controls if the output should be logged for

Help/envvar/CTEST_PARALLEL_LEVEL.rst

@@ -1,6 +1,8 @@
 CTEST_PARALLEL_LEVEL
 --------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Specify the number of tests for CTest to run in parallel. See :manual:`ctest(1)`

Help/envvar/CTEST_PROGRESS_OUTPUT.rst

@@ -1,6 +1,8 @@
 CTEST_PROGRESS_OUTPUT
 ---------------------
 
+.. versionadded:: 3.13
+
 .. include:: ENV_VAR.txt
 
 Boolean environment variable that affects how :manual:`ctest <ctest(1)>`

Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst

@@ -1,6 +1,8 @@
 CTEST_USE_LAUNCHERS_DEFAULT
 ---------------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Initializes the :variable:`CTEST_USE_LAUNCHERS` variable if not already defined.

Help/envvar/CUDACXX.rst

@@ -1,6 +1,8 @@
 CUDACXX
 -------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``CUDA`` language files. Will only be used by
@@ -9,3 +11,11 @@ value for ``CUDA`` is stored in the cache as
 :variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration
 run (including the first), the environment variable will be ignored if the
 :variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+  Options that are required to make the compiler work correctly can be included;
+  they can not be changed.
+
+.. code-block:: console
+
+  $ export CUDACXX="custom-compiler --arg1 --arg2"

Help/envvar/CUDAFLAGS.rst

@@ -1,6 +1,8 @@
 CUDAFLAGS
 ---------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Default compilation flags to be used when compiling ``CUDA`` files. Will only be

Help/envvar/CUDAHOSTCXX.rst

@@ -1,6 +1,8 @@
 CUDAHOSTCXX
 -----------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling host code when compiling ``CUDA``

Help/envvar/CXX.rst

@@ -1,6 +1,8 @@
 CXX
 ---
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``CXX`` language files. Will only be used by
@@ -9,3 +11,11 @@ value for ``CXX`` is stored in the cache as
 :variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration
 run (including the first), the environment variable will be ignored if the
 :variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+  Options that are required to make the compiler work correctly can be included;
+  they can not be changed.
+
+.. code-block:: console
+
+  $ export CXX="custom-compiler --arg1 --arg2"

Help/envvar/CXXFLAGS.rst

@@ -1,6 +1,8 @@
 CXXFLAGS
 --------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Default compilation flags to be used when compiling ``CXX`` (C++) files. Will

Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst

@@ -1,6 +1,8 @@
 DASHBOARD_TEST_FROM_CTEST
 -------------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Environment variable that will exist when a test executed by :manual:`ctest(1)`

Help/envvar/DESTDIR.rst

@@ -1,6 +1,8 @@
 DESTDIR
 -------
 
+.. versionadded:: 3.12
+
 .. include:: ENV_VAR.txt
 
 On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the

Help/envvar/FC.rst

@@ -1,6 +1,8 @@
 FC
 --
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``Fortran`` language files. Will only be used
@@ -10,3 +12,11 @@ which the value for ``Fortran`` is stored in the cache as
 configuration run (including the first), the environment variable will be
 ignored if the :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>`
 variable is defined.
+
+.. note::
+  Options that are required to make the compiler work correctly can be included;
+  they can not be changed.
+
+.. code-block:: console
+
+  $ export FC="custom-compiler --arg1 --arg2"

Help/envvar/FFLAGS.rst

@@ -1,6 +1,8 @@
 FFLAGS
 ------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Default compilation flags to be used when compiling ``Fortran`` files. Will only

Help/envvar/ISPC.rst

@@ -0,0 +1,13 @@
+ISPC
+-------
+
+.. versionadded:: 3.19
+
+.. include:: ENV_VAR.txt
+
+Preferred executable for compiling ``ISPC`` language files. Will only be used by
+CMake on the first configuration to determine ``ISPC`` compiler, after which the
+value for ``ISPC`` is stored in the cache as
+:variable:`CMAKE_ISPC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration
+run (including the first), the environment variable will be ignored if the
+:variable:`CMAKE_ISPC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.

Help/envvar/ISPCFLAGS.rst

@@ -0,0 +1,15 @@
+ISPCFLAGS
+---------
+
+.. versionadded:: 3.19
+
+.. include:: ENV_VAR.txt
+
+Default compilation flags to be used when compiling ``ISPC`` files. Will only be
+used by CMake on the first configuration to determine ``ISPC`` default
+compilation flags, after which the value for ``ISPCFLAGS`` is stored in the
+cache as :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+run (including the first), the environment variable will be ignored if
+the :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+
+See also :variable:`CMAKE_ISPC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/LDFLAGS.rst

@@ -1,6 +1,8 @@
 LDFLAGS
 -------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Will only be used by CMake on the first configuration to determine the default

Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst

@@ -1,6 +1,8 @@
 MACOSX_DEPLOYMENT_TARGET
 ------------------------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Specify the minimum version of macOS on which the target binaries are

Help/envvar/OBJC.rst

@@ -1,6 +1,8 @@
 OBJC
 ----
 
+.. versionadded:: 3.16.7
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``OBJC`` language files. Will only be used

Help/envvar/OBJCXX.rst

@@ -1,6 +1,8 @@
 OBJCXX
 ------
 
+.. versionadded:: 3.16.7
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``OBJCXX`` language files. Will only be used

Help/envvar/PackageName_ROOT.rst

@@ -1,6 +1,8 @@
 <PackageName>_ROOT
 ------------------
 
+.. versionadded:: 3.12.1
+
 .. include:: ENV_VAR.txt
 
 Calls to :command:`find_package(<PackageName>)` will search in prefixes

Help/envvar/RC.rst

@@ -1,6 +1,8 @@
 RC
 --
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``resource`` files. Will only be used by CMake
@@ -9,3 +11,11 @@ value for ``RC`` is stored in the cache as
 :variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run
 (including the first), the environment variable will be ignored if the
 :variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+  Options that are required to make the compiler work correctly can be included;
+  they can not be changed.
+
+.. code-block:: console
+
+  $ export RC="custom-compiler --arg1 --arg2"

Help/envvar/RCFLAGS.rst

@@ -1,6 +1,8 @@
 RCFLAGS
 -------
 
+.. versionadded:: 3.10
+
 .. include:: ENV_VAR.txt
 
 Default compilation flags to be used when compiling ``resource`` files. Will

Help/envvar/SWIFTC.rst

@@ -1,6 +1,8 @@
 SWIFTC
 ------
 
+.. versionadded:: 3.15
+
 .. include:: ENV_VAR.txt
 
 Preferred executable for compiling ``Swift`` language files. Will only be used by
@@ -9,3 +11,11 @@ value for ``SWIFTC`` is stored in the cache as
 :variable:`CMAKE_Swift_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run
 (including the first), the environment variable will be ignored if the
 :variable:`CMAKE_Swift_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
+
+.. note::
+  Options that are required to make the compiler work correctly can be included;
+  they can not be changed.
+
+.. code-block:: console
+
+  $ export SWIFTC="custom-compiler --arg1 --arg2"

Help/envvar/VERBOSE.rst

@@ -1,6 +1,8 @@
 VERBOSE
 -------
 
+.. versionadded:: 3.14
+
 Activates verbose output from CMake and your build tools of choice when
 you start to actually build your project.
 

Help/generator/Green Hills MULTI.rst

@@ -1,6 +1,8 @@
 Green Hills MULTI
 -----------------
 
+.. versionadded:: 3.3
+
 Generates Green Hills MULTI project files (experimental, work-in-progress).
 
 The buildsystem has predetermined build-configuration settings that can be controlled

Help/generator/Ninja Multi-Config.rst

@@ -1,6 +1,8 @@
 Ninja Multi-Config
 ------------------
 
+.. versionadded:: 3.17
+
 Generates multiple ``build-<Config>.ninja`` files.
 
 This generator is very much like the :generator:`Ninja` generator, but with

Help/generator/Visual Studio 14 2015.rst

@@ -1,6 +1,8 @@
 Visual Studio 14 2015
 ---------------------
 
+.. versionadded:: 3.1
+
 Generates Visual Studio 14 (VS 2015) project files.
 
 Project Types
@@ -43,3 +45,19 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
    By default this generator uses the 32-bit variant even on a 64-bit host.
 
 .. include:: VS_TOOLSET_HOST_ARCH.txt
+
+.. _`Windows 10 SDK Maximum Version for VS 2015`:
+
+Windows 10 SDK Maximum Version for VS 2015
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Microsoft stated in a "Windows 10 October 2018 Update" blog post that Windows
+10 SDK versions (15063, 16299, 17134, 17763) are not supported by VS 2015 and
+are only supported by VS 2017 and later.  Therefore by default CMake
+automatically ignores Windows 10 SDKs beyond ``10.0.14393.0``.
+
+However, there are other recommendations for certain driver/Win32 builds that
+indicate otherwise.  A user can override this behavior by either setting the
+:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to a false value
+or setting the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to
+the string value of the required maximum (e.g. ``10.0.15063.0``).

Help/generator/Visual Studio 15 2017.rst

@@ -1,6 +1,8 @@
 Visual Studio 15 2017
 ---------------------
 
+.. versionadded:: 3.7.1
+
 Generates Visual Studio 15 (VS 2017) project files.
 
 Project Types

Help/generator/Visual Studio 16 2019.rst

@@ -1,6 +1,8 @@
 Visual Studio 16 2019
 ---------------------
 
+.. versionadded:: 3.14
+
 Generates Visual Studio 16 (VS 2019) project files.
 
 Project Types

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)

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)

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)

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)

Help/guide/tutorial/index.rst

@@ -81,8 +81,8 @@ replaced.
 Next modify ``tutorial.cxx`` to include the configured header file,
 ``TutorialConfig.h``.
 
-Finally, let's print out the version number by updating ``tutorial.cxx`` as
-follows:
+Finally, let's print out the executable name and version number by updating
+``tutorial.cxx`` as follows:
 
 .. literalinclude:: Step2/tutorial.cxx
   :language: c++
@@ -106,7 +106,8 @@ correct flags. The easiest way to enable support for a specific C++ standard
 in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this
 tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the
 ``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to
-True:
+True. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the call
+to ``add_executable``.
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake
@@ -120,18 +121,28 @@ Run the :manual:`cmake <cmake(1)>` executable or the
 with your chosen build tool.
 
 For example, from the command line we could navigate to the
-``Help/guide/tutorial`` directory of the CMake source code tree and run the
-following commands:
+``Help/guide/tutorial`` directory of the CMake source code tree and create a
+build directory:
 
 .. code-block:: console
 
   mkdir Step1_build
+
+Next, navigate to the build directory and run CMake to configure the project
+and generate a native build system:
+
+.. code-block:: console
+
   cd Step1_build
   cmake ../Step1
+
+Then call that build system to actually compile/link the project:
+
+.. code-block:: console
+
   cmake --build .
 
-Navigate to the directory where Tutorial was built (likely the make directory
-or a Debug or Release build configuration subdirectory) and run these commands:
+Finally, try to use the newly built ``Tutorial`` with these commands:
 
 .. code-block:: console
 
@@ -212,8 +223,9 @@ libraries to later be linked into the executable. The variable
 classic approach when dealing with many optional components, we will cover
 the modern approach in the next step.
 
-The corresponding changes to the source code are fairly straightforward. First,
-in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we need it:
+The corresponding changes to the source code are fairly straightforward.
+First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we
+need it:
 
 .. literalinclude:: Step3/tutorial.cxx
   :language: c++
@@ -242,8 +254,17 @@ Run the :manual:`cmake  <cmake(1)>` executable or the
 :manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool. Then run the built Tutorial executable.
 
-Use the :manual:`ccmake <ccmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>`
-to update the value of ``USE_MYMATH``. Rebuild and run the tutorial again.
+Now let's update the value of ``USE_MYMATH``. The easiest way is to use the
+:manual:`cmake-gui <cmake-gui(1)>` or  :manual:`ccmake <ccmake(1)>` if you're
+in the terminal. Or, alternatively, if you want to change the option from the
+command-line, try:
+
+.. code-block:: console
+
+  cmake ../Step2 -DUSE_MYMATH=OFF
+
+Rebuild and run the tutorial again.
+
 Which function gives better results, sqrt or mysqrt?
 
 Adding Usage Requirements for Library (Step 3)
@@ -320,21 +341,32 @@ And to the end of the top-level ``CMakeLists.txt`` we add:
 
 That is all that is needed to create a basic local install of the tutorial.
 
-Run the :manual:`cmake  <cmake(1)>` executable or the
+Now run the :manual:`cmake  <cmake(1)>` executable or the
 :manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
-with your chosen build tool. Run the install step by using the ``install``
-option of the :manual:`cmake  <cmake(1)>` command (introduced in 3.15, older
-versions of CMake must use ``make install``) from the command line, or build
-the ``INSTALL`` target from an IDE. This will install the appropriate header
-files, libraries, and executables.
+with your chosen build tool.
+
+Then run the install step by using the ``install`` option of the
+:manual:`cmake  <cmake(1)>` command (introduced in 3.15, older versions of
+CMake must use ``make install``) from the command line. For
+multi-configuration tools, don't forget to use the ``--config`` argument to
+specify the configuration. If using an IDE, simply build the ``INSTALL``
+target. This step will install the appropriate header files, libraries, and
+executables. For example:
+
+.. code-block:: console
+
+  cmake --install .
 
 The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
-root of where the files will be installed. If using ``cmake --install`` a
-custom installation directory can be given via the ``--prefix`` argument. For
-multi-configuration tools, use the ``--config`` argument to specify the
-configuration.
+root of where the files will be installed. If using the ``cmake --install``
+command, the installation prefix can be overridden via the ``--prefix``
+argument. For example:
+
+.. code-block:: console
+
+  cmake --install . --prefix "/home/myuser/installdir"
 
-Verify that the installed Tutorial runs.
+Navigate to the install directory and verify that the installed Tutorial runs.
 
 Testing Support
 ---------------
@@ -520,6 +552,7 @@ We also have to add the current binary directory to the list of include
 directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
 
 .. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+  :language: cmake
   :start-after: # state that we depend on our bin
   :end-before: # install rules
 
@@ -675,9 +708,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 +736,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
@@ -750,7 +783,7 @@ A common usage of
 :manual:`generator expressions <cmake-generator-expressions(7)>` is to
 conditionally add compiler flags, such as those for language levels or
 warnings. A nice pattern is to associate this information to an ``INTERFACE``
-target allowing this information to propagate. Lets start by constructing an
+target allowing this information to propagate. Let's start by constructing an
 ``INTERFACE`` target and specifying the required C++ standard level of ``11``
 instead of using :variable:`CMAKE_CXX_STANDARD`.
 

Help/manual/cmake-buildsystem.7.rst

@@ -96,6 +96,9 @@ Apple Frameworks
 
 A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
 target property to create an macOS or iOS Framework Bundle.
+A library with the ``FRAMEWORK`` target property should also set the
+:prop_tgt:`FRAMEWORK_VERSION` target property.  This property is typically
+set to the value of "A" by macOS conventions.
 The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key
 and it uniquely identifies the bundle.
 
@@ -104,7 +107,7 @@ and it uniquely identifies the bundle.
   add_library(MyFramework SHARED MyFramework.cpp)
   set_target_properties(MyFramework PROPERTIES
     FRAMEWORK TRUE
-    FRAMEWORK_VERSION A
+    FRAMEWORK_VERSION A # Version "A" is macOS convention
     MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
   )
 
@@ -115,7 +118,10 @@ Object Libraries
 
 The ``OBJECT`` library type defines a non-archival collection of object files
 resulting from compiling the given source files.  The object files collection
-may be used as source inputs to other targets:
+may be used as source inputs to other targets by using the syntax
+``$<TARGET_OBJECTS:name>``.  This is a
+:manual:`generator expression <cmake-generator-expressions(7)>` that can be
+used to supply the ``OBJECT`` library content to other targets:
 
 .. code-block:: cmake
 
@@ -373,8 +379,12 @@ position-independent-code, so a diagnostic is issued.
 The ``lib1`` and ``lib2`` requirements are not "compatible".  One of them
 requires that consumers are built as position-independent-code, while
 the other requires that consumers are not built as position-independent-code.
-Because ``exe2`` links to both and they are in conflict, a diagnostic is
-issued.
+Because ``exe2`` links to both and they are in conflict, a CMake error message
+is issued::
+
+  CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
+  not agree with the value of POSITION_INDEPENDENT_CODE already determined
+  for "exe2".
 
 To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property,
 if set must be either the same, in a boolean sense, as the
@@ -732,7 +742,7 @@ As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of
 the ``exe1`` target is dependent on the linked libraries (``lib3``), and the
 edge of linking ``exe1`` is determined by the same
 :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
-contains a cycle.  :manual:`cmake(1)` issues a diagnostic in this case.
+contains a cycle.  :manual:`cmake(1)` issues an error message.
 
 .. _`Output Artifacts`:
 
@@ -922,8 +932,8 @@ property from it:
 Interface Libraries
 -------------------
 
-An ``INTERFACE`` target has no :prop_tgt:`LOCATION` and is mutable, but is
-otherwise similar to an :prop_tgt:`IMPORTED` target.
+An ``INTERFACE`` library target does not compile sources and does not
+produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`.
 
 It may specify usage requirements such as
 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
@@ -937,11 +947,22 @@ Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
 :command:`target_sources`, and :command:`target_link_libraries` commands
 may be used with ``INTERFACE`` libraries.
 
+Since CMake 3.19, an ``INTERFACE`` library target may optionally contain
+source files.  An interface library that contains source files will be
+included as a build target in the generated buildsystem.  It does not
+compile sources, but may contain custom commands to generate other sources.
+Additionally, IDEs will show the source files as part of the target for
+interactive reading and editing.
+
 A primary use-case for ``INTERFACE`` libraries is header-only libraries.
 
 .. code-block:: cmake
 
-  add_library(Eigen INTERFACE)
+  add_library(Eigen INTERFACE
+    src/eigen.h
+    src/vector.h
+    src/matrix.h
+    )
   target_include_directories(Eigen INTERFACE
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
     $<INSTALL_INTERFACE:include/Eigen>
@@ -975,25 +996,17 @@ This way, the build specification of ``exe1`` is expressed entirely as linked
 targets, and the complexity of compiler-specific flags is encapsulated in an
 ``INTERFACE`` library target.
 
-The properties permitted to be set on or read from an ``INTERFACE`` library
-are:
-
-* Properties matching ``INTERFACE_*``
-* Built-in properties matching ``COMPATIBLE_INTERFACE_*``
-* ``EXPORT_NAME``
-* ``EXPORT_PROPERTIES``
-* ``IMPORTED``
-* ``MANUALLY_ADDED_DEPENDENCIES``
-* ``NAME``
-* Properties matching ``IMPORTED_LIBNAME_*``
-* Properties matching ``MAP_IMPORTED_CONFIG_*``
-
 ``INTERFACE`` libraries may be installed and exported.  Any content they refer
 to must be installed separately:
 
 .. code-block:: cmake
 
-  add_library(Eigen INTERFACE)
+  set(Eigen_headers
+    src/eigen.h
+    src/vector.h
+    src/matrix.h
+    )
+  add_library(Eigen INTERFACE ${Eigen_headers})
   target_include_directories(Eigen INTERFACE
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
     $<INSTALL_INTERFACE:include/Eigen>
@@ -1003,9 +1016,6 @@ to must be installed separately:
   install(EXPORT eigenExport NAMESPACE Upstream::
     DESTINATION lib/cmake/Eigen
   )
-  install(FILES
-      ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h
-      ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h
-      ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h
+  install(FILES ${Eigen_headers}
     DESTINATION include/Eigen
   )

Help/manual/cmake-env-variables.7.rst

@@ -63,6 +63,8 @@ Environment Variables for Languages
    /envvar/CXXFLAGS
    /envvar/FC
    /envvar/FFLAGS
+   /envvar/ISPC
+   /envvar/ISPCFLAGS
    /envvar/OBJC
    /envvar/OBJCXX
    /envvar/RC

Help/manual/cmake-file-api.7.rst

@@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from
 
   {
     "kind": "codemodel",
-    "version": { "major": 2, "minor": 1 },
+    "version": { "major": 2, "minor": 2 },
     "paths": {
       "source": "/path/to/top-level-source-dir",
       "build": "/path/to/top-level-build-dir"
@@ -650,7 +650,8 @@ with members:
 ``type``
   A string specifying the type of the target.  The value is one of
   ``EXECUTABLE``, ``STATIC_LIBRARY``, ``SHARED_LIBRARY``,
-  ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, or ``UTILITY``.
+  ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, ``INTERFACE_LIBRARY``,
+  or ``UTILITY``.
 
 ``backtrace``
   Optional member that is present when a CMake language backtrace to
@@ -869,6 +870,26 @@ 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.
+
+    This field was added in codemodel version 2.2.
+
   ``compileCommandFragments``
     Optional member that is present when fragments of the compiler command
     line invocation are available.  The value is a JSON array of entries

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 entries 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.
@@ -145,6 +146,11 @@ Variable Queries
   ``1`` if the CMake's compiler id of the Fortran compiler matches any one
   of the entries in ``compiler_ids``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+``$<ISPC_COMPILER_ID:compiler_ids>``
+  where ``compiler_ids`` is a comma-separated list.
+  ``1`` if the CMake's compiler id of the ISPC compiler matches any one
+  of the entries in ``compiler_ids``, otherwise ``0``.
+  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
 ``$<C_COMPILER_VERSION:version>``
   ``1`` if the version of the C compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
@@ -163,6 +169,9 @@ Variable Queries
 ``$<Fortran_COMPILER_VERSION:version>``
   ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+``$<ISPC_COMPILER_VERSION:version>``
+  ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``.
+  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
 ``$<TARGET_POLICY:policy>``
   ``1`` if the ``policy`` was NEW when the 'head' target was created,
   else ``0``.  If the ``policy`` was not set, the warning message for the policy
@@ -542,6 +551,9 @@ Variable Queries
 ``$<Fortran_COMPILER_ID>``
   The CMake's compiler id of the Fortran compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
+``$<ISPC_COMPILER_ID>``
+  The CMake's compiler id of the ISPC compiler used.
+  See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable.
 ``$<C_COMPILER_VERSION>``
   The version of the C compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
@@ -560,6 +572,9 @@ Variable Queries
 ``$<Fortran_COMPILER_VERSION>``
   The version of the Fortran compiler used.
   See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
+``$<ISPC_COMPILER_VERSION>``
+  The version of the ISPC compiler used.
+  See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable.
 ``$<COMPILE_LANGUAGE>``
   The compile language of source files when evaluating compile options.
   See :ref:`the related boolean expression
@@ -595,6 +610,9 @@ which is just the string ``tgt``.
 
 ``$<TARGET_NAME_IF_EXISTS:tgt>``
   The target name ``tgt`` if the target exists, an empty string otherwise.
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on.
 ``$<TARGET_FILE:tgt>``
   Full path to the ``tgt`` binary file.
 ``$<TARGET_FILE_BASE_NAME:tgt>``
@@ -632,6 +650,9 @@ which is just the string ``tgt``.
   The ``tgt`` filename.
 ``$<TARGET_FILE_DIR:tgt>``
   Directory of the ``tgt`` binary file.
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_LINKER_FILE:tgt>``
   File used when linking to the ``tgt`` target.  This will usually
   be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``),
@@ -673,14 +694,26 @@ which is just the string ``tgt``.
   expression is evaluated on.
 ``$<TARGET_LINKER_FILE_NAME:tgt>``
   Name of file used to link target ``tgt``.
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_LINKER_FILE_DIR:tgt>``
   Directory of file used to link target ``tgt``.
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_SONAME_FILE:tgt>``
   File with soname (``.so.3``) where ``tgt`` is the name of a target.
 ``$<TARGET_SONAME_FILE_NAME:tgt>``
   Name of file with soname (``.so.3``).
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_SONAME_FILE_DIR:tgt>``
   Directory of with soname (``.so.3``).
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_PDB_FILE:tgt>``
   Full path to the linker generated program database file (.pdb)
   where ``tgt`` is the name of a target.
@@ -706,17 +739,29 @@ which is just the string ``tgt``.
   expression is evaluated on.
 ``$<TARGET_PDB_FILE_NAME:tgt>``
   Name of the linker generated program database file (.pdb).
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_PDB_FILE_DIR:tgt>``
   Directory of the linker generated program database file (.pdb).
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_BUNDLE_DIR:tgt>``
   Full path to the bundle directory (``my.app``, ``my.framework``, or
   ``my.bundle``) where ``tgt`` is the name of a target.
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>``
   Full path to the bundle content directory where ``tgt`` is the name of a
   target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``,
   or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to
   ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle
   structure.
+
+  Note that ``tgt`` is not added as a dependency of the target this
+  expression is evaluated on (see policy :policy:`CMP0112`).
 ``$<TARGET_PROPERTY:tgt,prop>``
   Value of the property ``prop`` on the target ``tgt``.
 

Help/manual/cmake-policies.7.rst

@@ -51,6 +51,17 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.19
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112>
+   CMP0111: An imported target with a missing location fails during generation. </policy/CMP0111>
+   CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110>
+   CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109>
+
 Policies Introduced by CMake 3.18
 =================================
 

Help/manual/cmake-properties.7.rst

@@ -258,6 +258,7 @@ Properties on Targets
    /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG
    /prop_tgt/INTERPROCEDURAL_OPTIMIZATION
    /prop_tgt/IOS_INSTALL_COMBINED
+   /prop_tgt/ISPC_HEADER_DIRECTORY
    /prop_tgt/JOB_POOL_COMPILE
    /prop_tgt/JOB_POOL_LINK
    /prop_tgt/JOB_POOL_PRECOMPILE_HEADER
@@ -307,6 +308,7 @@ Properties on Targets
    /prop_tgt/OBJCXX_EXTENSIONS
    /prop_tgt/OBJCXX_STANDARD
    /prop_tgt/OBJCXX_STANDARD_REQUIRED
+   /prop_tgt/OPTIMIZE_DEPENDENCIES
    /prop_tgt/OSX_ARCHITECTURES_CONFIG
    /prop_tgt/OSX_ARCHITECTURES
    /prop_tgt/OUTPUT_NAME_CONFIG
@@ -394,6 +396,7 @@ Properties on Targets
    /prop_tgt/XCODE_ATTRIBUTE_an-attribute
    /prop_tgt/XCODE_EXPLICIT_FILE_TYPE
    /prop_tgt/XCODE_GENERATE_SCHEME
+   /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE
    /prop_tgt/XCODE_PRODUCT_TYPE
    /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER
    /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN

Help/manual/cmake-variables.7.rst

@@ -124,6 +124,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
    /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
+   /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
    /variable/CMAKE_XCODE_GENERATE_SCHEME
    /variable/CMAKE_XCODE_PLATFORM_TOOLSET
    /variable/PROJECT-NAME_BINARY_DIR
@@ -158,6 +159,7 @@ Variables that Change Behavior
    /variable/CMAKE_AUTOMOC_RELAXED_MODE
    /variable/CMAKE_BACKWARDS_COMPATIBILITY
    /variable/CMAKE_BUILD_TYPE
+   /variable/CMAKE_CLANG_VFS_OVERLAY
    /variable/CMAKE_CODEBLOCKS_COMPILER_ID
    /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
    /variable/CMAKE_CODELITE_USE_TARGETS
@@ -245,6 +247,7 @@ Variables that Change Behavior
    /variable/CMAKE_WARN_DEPRECATED
    /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
    /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
+   /variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE
    /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
    /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
    /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
@@ -436,6 +439,7 @@ Variables that Control the Build
    /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
    /variable/CMAKE_NO_BUILTIN_CHRPATH
    /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED
+   /variable/CMAKE_OPTIMIZE_DEPENDENCIES
    /variable/CMAKE_OSX_ARCHITECTURES
    /variable/CMAKE_OSX_DEPLOYMENT_TARGET
    /variable/CMAKE_OSX_SYSROOT
@@ -507,6 +511,7 @@ Variables for Languages
    /variable/CMAKE_Fortran_MODDIR_DEFAULT
    /variable/CMAKE_Fortran_MODDIR_FLAG
    /variable/CMAKE_Fortran_MODOUT_FLAG
+   /variable/CMAKE_ISPC_HEADER_DIRECTORY
    /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE
    /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX
    /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX