Merge branch 'master' into ninja-order-only-fix

.clang-tidy

@@ -13,9 +13,11 @@ modernize-*,\
 -modernize-avoid-c-arrays,\
 -modernize-use-nodiscard,\
 -modernize-use-noexcept,\
+-modernize-use-trailing-return-type,\
 -modernize-use-transparent-functors,\
 performance-*,\
 readability-*,\
+-readability-convert-member-functions-to-static,\
 -readability-function-size,\
 -readability-identifier-naming,\
 -readability-implicit-bool-conversion,\

Auxiliary/CMakeLists.txt

@@ -1,4 +1,4 @@
-install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMAKE_DATA_DIR}/editors/vim)
-install(FILES cmake-mode.el DESTINATION ${CMAKE_DATA_DIR}/editors/emacs)
+install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMAKE_XDGDATA_DIR}/vim/vimfiles)
+install(FILES cmake-mode.el DESTINATION ${CMAKE_XDGDATA_DIR}/emacs/site-lisp)
 install(FILES cmake.m4 DESTINATION ${CMAKE_XDGDATA_DIR}/aclocal)
 add_subdirectory (bash-completion)

Auxiliary/bash-completion/CMakeLists.txt

@@ -1,8 +1,16 @@
-# Always install completion file in local dir
-# in order to be sure to always be able to install
-# in a local user directory rooted in a single directory.
-# packager should either patch that out or
-# add symlinks to the files in appropriate places
-#  /etc/bash_completion.d/
-#  DATADIR/completions (may be /usr/share/<package>/completions
-install(FILES cmake cpack ctest DESTINATION ${CMAKE_DATA_DIR}/completions)
+# We need to integrate into the system install, or this will silently fail to
+# accomplish anything at all, and packagers won't even know it exists. Use the
+# `<sharedir>/bash-completion/completions/` hierarchy by default, rooted in
+# CMake's XDGDATA_DIR definition of the sharedir. This works with installation
+# to `/usr` or `/usr/local` (or any prefix which bash-completion is configured
+# with) as well as a simple installation by a local user into their home
+# directory *if* the prefix is `$HOME/.local` since `.local/share/` is part of
+# the bash-completion search path too.
+# For more complex installations, packagers can set CMAKE_BASH_COMP_DIR to
+# another system location.
+
+set(CMAKE_BASH_COMP_DIR_DEFAULT ${CMAKE_XDGDATA_DIR}/bash-completion/completions)
+if (NOT CMAKE_BASH_COMP_DIR)
+  set(CMAKE_BASH_COMP_DIR "${CMAKE_BASH_COMP_DIR_DEFAULT}")
+endif()
+install(FILES cmake cpack ctest DESTINATION ${CMAKE_BASH_COMP_DIR})

CMakeLists.txt

@@ -154,7 +154,7 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
 
   # Allow the user to enable/disable all system utility library options by
   # defining CMAKE_USE_SYSTEM_LIBRARIES or CMAKE_USE_SYSTEM_LIBRARY_${util}.
-  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV ZLIB ZSTD)
+  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV NGHTTP2 ZLIB ZSTD)
   foreach(util ${UTILITIES})
     if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
         AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
@@ -192,6 +192,8 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
     "${CMAKE_USE_SYSTEM_LIBRARY_ZSTD}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
   CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_LIBLZMA "Use system-installed liblzma"
     "${CMAKE_USE_SYSTEM_LIBRARY_LIBLZMA}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
+  CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_NGHTTP2 "Use system-installed nghttp2"
+    "${CMAKE_USE_SYSTEM_LIBRARY_NGHTTP2}" "NOT CMAKE_USE_SYSTEM_CURL" ON)
   option(CMAKE_USE_SYSTEM_FORM "Use system-installed libform" "${CMAKE_USE_SYSTEM_LIBRARY_FORM}")
   option(CMAKE_USE_SYSTEM_JSONCPP "Use system-installed jsoncpp" "${CMAKE_USE_SYSTEM_LIBRARY_JSONCPP}")
   option(CMAKE_USE_SYSTEM_LIBRHASH "Use system-installed librhash" "${CMAKE_USE_SYSTEM_LIBRARY_LIBRHASH}")
@@ -465,9 +467,19 @@ macro (CMAKE_BUILD_UTILITIES)
       set(CURL_CA_PATH "" CACHE PATH "Path to SSL CA Certificate Directory")
       mark_as_advanced(CURL_CA_BUNDLE CURL_CA_PATH)
     endif()
+    if(NOT CMAKE_USE_SYSTEM_NGHTTP2)
+      # Tell curl's FindNGHTTP2 module to use our library.
+      set(NGHTTP2_LIBRARY cmnghttp2)
+      set(NGHTTP2_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmnghttp2/lib/includes)
+    endif()
     add_subdirectory(Utilities/cmcurl)
     CMAKE_SET_TARGET_FOLDER(cmcurl "Utilities/3rdParty")
     CMAKE_SET_TARGET_FOLDER(LIBCURL "Utilities/3rdParty")
+    if(NOT CMAKE_USE_SYSTEM_NGHTTP2)
+      # Configure after curl to re-use some check results.
+      add_subdirectory(Utilities/cmnghttp2)
+      CMAKE_SET_TARGET_FOLDER(cmnghttp2 "Utilities/3rdParty")
+    endif()
   endif()
 
   #---------------------------------------------------------------------
@@ -547,21 +559,25 @@ macro (CMAKE_BUILD_UTILITIES)
     set(ZLIB_INCLUDE_DIR ${CMAKE_ZLIB_INCLUDES})
     set(ZLIB_LIBRARY ${CMAKE_ZLIB_LIBRARIES})
     add_definitions(-DLIBARCHIVE_STATIC)
+    set(ENABLE_MBEDTLS OFF CACHE INTERNAL "Enable use of mbed TLS")
     set(ENABLE_NETTLE OFF CACHE INTERNAL "Enable use of Nettle")
     set(ENABLE_OPENSSL ${CMAKE_USE_OPENSSL} CACHE INTERNAL "Enable use of OpenSSL")
+    set(ENABLE_LIBB2 OFF CACHE INTERNAL "Enable the use of the system LIBB2 library if found")
     set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system LZMA library if found")
     set(ENABLE_LZ4 OFF CACHE INTERNAL "Enable the use of the system LZ4 library if found")
     set(ENABLE_LZO OFF CACHE INTERNAL "Enable the use of the system LZO library if found")
     set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system ZLIB library if found")
     set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system BZip2 library if found")
+    set(ENABLE_ZSTD ON CACHE INTERNAL "Enable the use of the system zstd library if found")
     set(ENABLE_LIBXML2 OFF CACHE INTERNAL "Enable the use of the system libxml2 library if found")
-    set(ENABLE_EXPAT ON CACHE INTERNAL "Enable the use of the system EXPAT library if found")
+    set(ENABLE_EXPAT OFF CACHE INTERNAL "Enable the use of the system EXPAT library if found")
     set(ENABLE_PCREPOSIX OFF CACHE INTERNAL "Enable the use of the system PCREPOSIX library if found")
     set(ENABLE_LibGCC OFF CACHE INTERNAL "Enable the use of the system LibGCC library if found")
     set(ENABLE_XATTR OFF CACHE INTERNAL "Enable extended attribute support")
     set(ENABLE_ACL OFF CACHE INTERNAL "Enable ACL support")
     set(ENABLE_ICONV OFF CACHE INTERNAL "Enable iconv support")
     set(ENABLE_CNG OFF CACHE INTERNAL "Enable the use of CNG(Crypto Next Generation)")
+    SET(POSIX_REGEX_LIB "" CACHE INTERNAL "Choose what library should provide POSIX regular expression support")
     add_subdirectory(Utilities/cmlibarchive)
     CMAKE_SET_TARGET_FOLDER(cmlibarchive "Utilities/3rdParty")
     set(CMAKE_TAR_LIBRARIES cmlibarchive ${BZIP2_LIBRARIES})

CTestCustom.cmake.in

@@ -99,6 +99,9 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "liblzma/common/index_encoder.c:[0-9]+:[0-9]+: warning: Value stored to .* during its initialization is never read"
   "libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
   "libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '==' is a garbage value"
+  "libuv/src/.*:[0-9]+:[0-9]+: warning: 1st function call argument is an uninitialized value"
+  "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
+  "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to .* is never read"
   )
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")

Help/command/DEVICE_LINK_OPTIONS.txt

@@ -0,0 +1,10 @@
+
+When a device link step is involved, which is controlled by
+:prop_tgt:`CUDA_SEPARABLE_COMPILATION` and
+:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties, the raw options will be
+delivered to the host and device link steps (wrapped in ``-Xcompiler`` or
+equivalent for device link). Options wrapped with ``$<DEVICE_LINK:...>``
+:manual:`generator expression <cmake-generator-expressions(7)>` will be used
+only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
+:manual:`generator expression <cmake-generator-expressions(7)>` will be used
+only for the host link step.

Help/command/FIND_XXX.txt

@@ -15,6 +15,7 @@ The general signature is:
              [PATHS path1 [path2 ... ENV var]]
              [PATH_SUFFIXES suffix1 [suffix2 ...]]
              [DOC "cache documentation string"]
+             [REQUIRED]
              [NO_DEFAULT_PATH]
              [NO_PACKAGE_ROOT_PATH]
              [NO_CMAKE_PATH]
@@ -31,8 +32,9 @@ A cache entry named by ``<VAR>`` is created to store the result
 of this command.
 If the |SEARCH_XXX| is found the result is stored in the variable
 and the search will not be repeated unless the variable is cleared.
-If nothing is found, the result will be
-``<VAR>-NOTFOUND``, and the search will be attempted again the
+If nothing is found, the result will be ``<VAR>-NOTFOUND``.
+The ``REQUIRED`` option stops processing with an error message if nothing
+is found, otherwise the search will be attempted again the
 next time |FIND_XXX| is invoked with the same variable.
 
 Options include:
@@ -57,6 +59,9 @@ Options include:
 ``DOC``
   Specify the documentation string for the ``<VAR>`` cache entry.
 
+``REQUIRED``
+  Stop processing with an error message if nothing is found.
+
 If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
 added to the search.
 If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:

Help/command/add_link_options.rst

@@ -26,6 +26,8 @@ the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
+.. include:: DEVICE_LINK_OPTIONS.txt
+
 .. include:: OPTIONS_SHELL.txt
 
 .. include:: LINK_OPTIONS_LINKER.txt

Help/command/cmake_command.rst

@@ -0,0 +1,90 @@
+cmake_command
+-------------
+
+Call meta-operations on CMake commands.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  cmake_command(`INVOKE`_ <command> [<args>...])
+  cmake_command(`EVAL`_ CODE <code>...)
+
+Introduction
+^^^^^^^^^^^^
+
+This command will call meta-operations on built-in CMake commands or
+those created via the :command:`macro` or :command:`function` commands.
+
+``cmake_command`` does not introduce a new variable or policy scope.
+
+Invoking Commands
+^^^^^^^^^^^^^^^^^
+
+.. _INVOKE:
+
+.. code-block:: cmake
+
+  cmake_command(INVOKE <command> [<args>...])
+
+Invokes the named ``<command>`` with the given arguments (if any).
+For example, the code:
+
+.. code-block:: cmake
+
+  set(message_command "message")
+  cmake_command(INVOKE ${message_command} STATUS "Hello World!")
+
+is equivalent to
+
+.. code-block:: cmake
+
+  message(STATUS "Hello World!")
+
+Evaluating Code
+^^^^^^^^^^^^^^^
+
+.. _EVAL:
+
+.. code-block:: cmake
+
+  cmake_command(EVAL CODE <code>...)
+
+Evaluates the ``<code>...`` as CMake code.
+
+For example, the code:
+
+.. code-block:: cmake
+
+  set(A TRUE)
+  set(B TRUE)
+  set(C TRUE)
+  set(condition "(A AND B) OR C")
+
+  cmake_command(EVAL CODE "
+    if (${condition})
+      message(STATUS TRUE)
+    else()
+      message(STATUS FALSE)
+    endif()"
+  )
+
+is equivalent to
+
+.. code-block:: cmake
+
+  set(A TRUE)
+  set(B TRUE)
+  set(C TRUE)
+  set(condition "(A AND B) OR C")
+
+  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
+    if (${condition})
+      message(STATUS TRUE)
+    else()
+      message(STATUS FALSE)
+    endif()"
+  )
+
+  include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

Help/command/ctest_test.rst

@@ -20,6 +20,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
              [RESOURCE_SPEC_FILE <file>]
              [TEST_LOAD <threshold>]
              [SCHEDULE_RANDOM <ON|OFF>]
+             [STOP_ON_FAILURE]
              [STOP_TIME <time-of-day>]
              [RETURN_VALUE <result-var>]
              [CAPTURE_CMAKE_ERROR <result-var>]
@@ -119,6 +120,9 @@ The options are:
   Launch tests in a random order.  This may be useful for detecting
   implicit test dependencies.
 
+``STOP_ON_FAILURE``
+  Stop the execution of the tests once one has failed.
+
 ``STOP_TIME <time-of-day>``
   Specify a time of day at which the tests should all stop running.
 

Help/command/execute_process.rst

@@ -21,7 +21,9 @@ Execute one or more child processes.
                   [COMMAND_ECHO <where>]
                   [OUTPUT_STRIP_TRAILING_WHITESPACE]
                   [ERROR_STRIP_TRAILING_WHITESPACE]
-                  [ENCODING <name>])
+                  [ENCODING <name>]
+                  [ECHO_OUTPUT_VARIABLE]
+                  [ECHO_ERROR_VARIABLE])
 
 Runs the given sequence of one or more commands.
 
@@ -105,6 +107,15 @@ Options:
    for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with
    the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
 
+``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
+  The standard output or standard error will not be exclusively redirected to
+  the configured variables.
+
+  The output will be duplicated, it will be sent into the configured variables
+  and also on standard output or standard error.
+
+  This is analogous to the ``tee`` Unix command.
+
 If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
 same pipe the precedence is not specified.
 If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will

Help/command/file.rst

@@ -19,6 +19,7 @@ Synopsis
     file({`WRITE`_ | `APPEND`_} <filename> <content>...)
     file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
     file(`GENERATE`_ OUTPUT <output-file> [...])
+    file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])
 
   `Filesystem`_
     file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
@@ -41,6 +42,10 @@ Synopsis
   `Locking`_
     file(`LOCK`_ <path> [...])
 
+   `Archiving`_
+     file(`ARCHIVE_CREATE`_ OUTPUT <archive> FILES <files> [...])
+     file(`ARCHIVE_EXTRACT`_ INPUT <archive> DESTINATION <dir> [...])
+
 Reading
 ^^^^^^^
 
@@ -54,7 +59,9 @@ Reading
 Read content from a file called ``<filename>`` and store it in a
 ``<variable>``.  Optionally start from the given ``<offset>`` and
 read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
-be converted to a hexadecimal representation (useful for binary data).
+be converted to a hexadecimal representation (useful for binary data). If the
+``HEX`` option is specified, letters in the output (``a`` through ``f``) are in
+lowercase.
 
 .. _STRINGS:
 
@@ -395,8 +402,8 @@ dependency resolution:
   Determines the path to the tool to use for dependency resolution. This is the
   actual path to ``objdump``, ``dumpbin``, or ``otool``.
 
-  If this variable is not specified, it is determined automatically by system
-  introspection.
+  If this variable is not specified, it is determined by the value of
+  ``CMAKE_OBJDUMP`` if set, else by system introspection.
 
 Writing
 ^^^^^^^
@@ -482,6 +489,45 @@ generation phase. The output file will not yet have been written when the
 ``file(GENERATE)`` command returns, it is written only after processing all
 of a project's ``CMakeLists.txt`` files.
 
+.. _CONFIGURE:
+
+.. code-block:: cmake
+
+  file(CONFIGURE OUTPUT output-file
+       CONTENT content
+       [ESCAPE_QUOTES] [@ONLY]
+       [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
+
+Generate an output file using the input given by ``CONTENT`` and substitute
+variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
+substitution rules behave the same as the :command:`configure_file` command.
+In order to match :command:`configure_file`'s behavior, generator expressions
+are not supported for both ``OUTPUT`` and ``CONTENT``.
+
+The arguments are:
+
+``OUTPUT <output-file>``
+  Specify the output file name to generate. A relative path is treated with
+  respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. See policy
+  :policy:`CMP0070`.
+  ``<output-file>`` does not support generator expressions.
+
+``CONTENT <content>``
+  Use the content given explicitly as input.
+  ``<content>`` does not support generator expressions.
+
+``ESCAPE_QUOTES``
+  Escape any substituted quotes with backslashes (C-style).
+
+``@ONLY``
+  Restrict variable replacement to references of the form ``@VAR@``.
+  This is useful for configuring scripts that use ``${VAR}`` syntax.
+
+``NEWLINE_STYLE <style>``
+  Specify the newline style for the output file.  Specify
+  ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
+  ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
+
 Filesystem
 ^^^^^^^^^^
 
@@ -790,6 +836,18 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 If neither ``NETRC`` option is given CMake will check variables
 ``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively.
 
+``TLS_VERIFY <ON|OFF>``
+  Specify whether to verify the server certificate for ``https://`` URLs.
+  The default is to *not* verify.
+
+``TLS_CAINFO <file>``
+  Specify a custom Certificate Authority file for ``https://`` URLs.
+
+For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
+certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
+check certificates. If neither ``TLS`` option is given CMake will check
+variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
+
 Additional options to ``DOWNLOAD`` are:
 
 ``EXPECTED_HASH ALGO=<value>``
@@ -801,19 +859,6 @@ Additional options to ``DOWNLOAD`` are:
 ``EXPECTED_MD5 <value>``
   Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
 
-``TLS_VERIFY <ON|OFF>``
-  Specify whether to verify the server certificate for ``https://`` URLs.
-  The default is to *not* verify.
-
-``TLS_CAINFO <file>``
-  Specify a custom Certificate Authority file for ``https://`` URLs.
-
-For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
-certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
-check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
-If neither ``TLS`` option is given CMake will check variables
-``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
-
 Locking
 ^^^^^^^
 
@@ -846,3 +891,62 @@ child directory or file.
 Trying to lock file twice is not allowed.  Any intermediate directories and
 file itself will be created if they not exist.  ``GUARD`` and ``TIMEOUT``
 options ignored on ``RELEASE`` operation.
+
+Archiving
+^^^^^^^^^
+
+.. _ARCHIVE_CREATE:
+
+.. code-block:: cmake
+
+  file(ARCHIVE_CREATE OUTPUT <archive>
+    [FILES <files>]
+    [DIRECTORY <dirs>]
+    [FORMAT <format>]
+    [TYPE <type>]
+    [MTIME <mtime>]
+    [VERBOSE])
+
+Creates an archive specifed by ``OUTPUT`` with the content of ``FILES`` and
+``DIRECTORY``.
+
+To specify the format of the archive set the ``FORMAT`` option.
+Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw``,
+(restricted pax, default), and ``zip``.
+
+To specify the type of compression set the ``TYPE`` option.
+Supported compression types are: ``None``, ``BZip2``, ``GZip``, ``XZ``,
+and ``Zstd``.
+
+.. note::
+  With ``FORMAT`` set to ``raw`` only one file will be compressed with the
+  compression type specified by ``TYPE``.
+
+With ``VERBOSE`` the command will produce verbose output.
+
+To specify the modification time recorded in tarball entries use
+the ``MTIME`` option.
+
+.. _ARCHIVE_EXTRACT:
+
+.. code-block:: cmake
+
+  file(ARCHIVE_EXTRACT INPUT <archive>
+    [FILES <files>]
+    [DIRECTORY <dirs>]
+    [DESTINATION <dir>]
+    [LIST_ONLY]
+    [VERBOSE])
+
+Extracts or lists the content of an archive specified by ``INPUT``.
+
+The directory where the content of the archive will be extracted can
+be specified via ``DESTINATION``. If the directory does not exit, it
+will be created.
+
+To select which files and directories will be extracted or listed
+use  ``FILES`` and ``DIRECTORY`` options.
+
+``LIST_ONLY`` will only list the files in the archive.
+
+With ``VERBOSE`` the command will produce verbose output.

Help/command/find_package.rst

@@ -302,23 +302,23 @@ enabled.
    are intended to be used on the command line with a ``-DVAR=value``.
    The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
    This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
-   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``::
+   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:
 
-     CMAKE_PREFIX_PATH
-     CMAKE_FRAMEWORK_PATH
-     CMAKE_APPBUNDLE_PATH
+   * :variable:`CMAKE_PREFIX_PATH`
+   * :variable:`CMAKE_FRAMEWORK_PATH`
+   * :variable:`CMAKE_APPBUNDLE_PATH`
 
 3. Search paths specified in cmake-specific environment variables.
    These are intended to be set in the user's shell configuration,
    and therefore use the host's native path separator
    (``;`` on Windows and ``:`` on UNIX).
    This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting
-   the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``::
+   the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:
 
-     <PackageName>_DIR
-     CMAKE_PREFIX_PATH
-     CMAKE_FRAMEWORK_PATH
-     CMAKE_APPBUNDLE_PATH
+   * ``<PackageName>_DIR``
+   * :envvar:`CMAKE_PREFIX_PATH`
+   * ``CMAKE_FRAMEWORK_PATH``
+   * ``CMAKE_APPBUNDLE_PATH``
 
 4. Search paths specified by the ``HINTS`` option.  These should be paths
    computed by system introspection, such as a hint provided by the

Help/command/function.rst

@@ -44,11 +44,15 @@ can be invoked through any of
   foo()
   Foo()
   FOO()
+  cmake_command(INVOKE foo)
 
 and so on. However, it is strongly recommended to stay with the
 case chosen in the function definition. Typically functions use
 all-lowercase names.
 
+The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the
+function.
+
 Arguments
 ^^^^^^^^^
 

Help/command/install.rst

@@ -30,13 +30,20 @@ signatures that specify them.  The common options are:
 
 ``DESTINATION``
   Specify the directory on disk to which a file will be installed.
-  If a full path (with a leading slash or drive letter) is given
-  it is used directly.  If a relative path is given it is interpreted
-  relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable.
+  Arguments can be relative or absolute paths.
+
+  If a relative path is given it is interpreted relative to the value
+  of the :variable:`CMAKE_INSTALL_PREFIX` variable.
   The prefix can be relocated at install time using the ``DESTDIR``
   mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
   documentation.
 
+  If an absolute path (with a leading slash or drive letter) is given
+  it is used verbatim.
+
+  As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer
+  generators, it is preferable to use relative paths throughout.
+
 ``PERMISSIONS``
   Specify permissions for installed files.  Valid permissions are
   ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
@@ -119,31 +126,38 @@ Installing Targets
           )
 
 The ``TARGETS`` form specifies rules for installing targets from a
-project.  There are several kinds of target files that may be installed:
+project.  There are several kinds of target :ref:`Output Artifacts`
+that may be installed:
 
 ``ARCHIVE``
-  Static libraries are treated as ``ARCHIVE`` targets, except those
-  marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK``
-  below.) For DLL platforms (all Windows-based systems including
-  Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
-  On AIX, the linker import file created for executables with
-  :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target.
+  Target artifacts of this kind include:
+
+  * *Static libraries*
+    (except on macOS when marked as ``FRAMEWORK``, see below);
+  * *DLL import libraries*
+    (on all Windows-based systems including Cygwin; they have extension
+    ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``);
+  * On AIX, the *linker import file* created for executables with
+    :prop_tgt:`ENABLE_EXPORTS` enabled.
 
 ``LIBRARY``
-  Module libraries are always treated as ``LIBRARY`` targets. For non-
-  DLL platforms shared libraries are treated as ``LIBRARY`` targets,
-  except those marked with the ``FRAMEWORK`` property on macOS (see
-  ``FRAMEWORK`` below.)
+  Target artifacts of this kind include:
+
+  * *Shared libraries*, except
+
+    - DLLs (these go to ``RUNTIME``, see below),
+    - on macOS when marked as ``FRAMEWORK`` (see below).
 
 ``RUNTIME``
-  Executables are treated as ``RUNTIME`` objects, except those marked
-  with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.)
-  For DLL platforms (all Windows-based systems including Cygwin), the
-  DLL part of a shared library is treated as a ``RUNTIME`` target.
+  Target artifacts of this kind include:
+
+  * *Executables*
+    (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below);
+  * DLLs (on all Windows-based systems including Cygwin; note that the
+    accompanying import libraries are of kind ``ARCHIVE``).
 
 ``OBJECTS``
-  Object libraries (a simple group of object files) are always treated
-  as ``OBJECTS`` targets.
+  Object files associated with *object libraries*.
 
 ``FRAMEWORK``
   Both static and shared libraries marked with the ``FRAMEWORK``
@@ -630,6 +644,13 @@ present, causes the contents of the properties matching
 ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
 policy :policy:`CMP0022` is ``NEW``.
 
+.. note::
+  The installed ``<export-name>.cmake`` file may come with additional
+  per-configuration ``<export-name>-*.cmake`` files to be loaded by
+  globbing.  Do not use an export name that is the same as the package
+  name in combination with installing a ``<package-name>-config.cmake``
+  file or the latter may be incorrectly matched by the glob and loaded.
+
 When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly
 depends on all components mentioned in the export set. The exported
 ``<name>.cmake`` file will require each of the exported components to be
@@ -684,6 +705,11 @@ executable from the installation tree using the imported target name
 Generated Installation Script
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. note::
+
+  Use of this feature is not recommended. Please consider using the
+  ``--install`` argument of :manual:`cmake(1)` instead.
+
 The ``install()`` command generates a file, ``cmake_install.cmake``, inside
 the build directory, which is used internally by the generated install target
 and by CPack. You can also invoke this script manually with ``cmake -P``. This

Help/command/list.rst

@@ -308,6 +308,13 @@ The ``<compare>`` option should be one of:
 * ``STRING``: Sorts a list of strings alphabetically.  This is the
   default behavior if the ``COMPARE`` option is not given.
 * ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames.
+* ``NATURAL``: Sorts a list of strings using natural order
+  (see ``strverscmp(3)`` manual), i.e. such that contiguous digits
+  are compared as whole numbers.
+  For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
+  will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
+  comparison is selected where it will be sorted as
+  `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
 
 Use the ``CASE`` keyword to select a case sensitive or case insensitive
 sort mode.  The ``<case>`` option should be one of:

Help/command/macro.rst

@@ -42,11 +42,15 @@ can be invoked through any of
   foo()
   Foo()
   FOO()
+  cmake_command(INVOKE foo)
 
 and so on. However, it is strongly recommended to stay with the
 case chosen in the macro definition.  Typically macros use
 all-lowercase names.
 
+The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the
+macro.
+
 Arguments
 ^^^^^^^^^
 

Help/command/separate_arguments.rst

@@ -19,7 +19,7 @@ They are specified by the ``<mode>`` argument which must
 be one of the following keywords:
 
 ``UNIX_COMMAND``
-  Arguments are separated by by unquoted whitespace.
+  Arguments are separated by unquoted whitespace.
   Both single-quote and double-quote pairs are respected.
   A backslash escapes the next literal character (``\"`` is ``"``);
   there are no special escapes (``\n`` is just ``n``).

Help/command/set_property.rst

@@ -66,7 +66,8 @@ the property to set.  Remaining arguments are used to compose the
 property value in the form of a semicolon-separated list.
 
 If the ``APPEND`` option is given the list is appended to any existing
-property value.  If the ``APPEND_STRING`` option is given the string is
+property value (except that empty values are ignored and not appended).
+If the ``APPEND_STRING`` option is given the string is
 appended to any existing property value as string, i.e. it results in a
 longer string and not a list of strings.  When using ``APPEND`` or
 ``APPEND_STRING`` with a property defined to support ``INHERITED``

Help/command/string.rst

@@ -11,8 +11,6 @@ Synopsis
   `Search and Replace`_
     string(`FIND`_ <string> <substring> <out-var> [...])
     string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
-
-  `Regular Expressions`_
     string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
     string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
     string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)
@@ -38,6 +36,7 @@ Synopsis
 
   `Generation`_
     string(`ASCII`_ <number>... <out-var>)
+    string(`HEX`_ <string> <out-var>)
     string(`CONFIGURE`_ <string> <out-var> [...])
     string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
     string(`RANDOM`_ [<option>...] <out-var>)
@@ -47,6 +46,9 @@ Synopsis
 Search and Replace
 ^^^^^^^^^^^^^^^^^^
 
+Search and Replace With Plain Strings
+"""""""""""""""""""""""""""""""""""""
+
 .. _FIND:
 
 .. code-block:: cmake
@@ -74,8 +76,8 @@ so strings containing multi-byte characters may lead to unexpected results.
 Replace all occurrences of ``<match_string>`` in the ``<input>``
 with ``<replace_string>`` and store the result in the ``<output_variable>``.
 
-Regular Expressions
-^^^^^^^^^^^^^^^^^^^
+Search and Replace With Regular Expressions
+"""""""""""""""""""""""""""""""""""""""""""
 
 .. _`REGEX MATCH`:
 
@@ -87,6 +89,7 @@ Regular Expressions
 Match the ``<regular_expression>`` once and store the match in the
 ``<output_variable>``.
 All ``<input>`` arguments are concatenated before matching.
+Regular expressions are specified in the subsection just below.
 
 .. _`REGEX MATCHALL`:
 
@@ -353,6 +356,16 @@ Generation
 
 Convert all numbers into corresponding ASCII characters.
 
+.. _HEX:
+
+.. code-block:: cmake
+
+  string(HEX <string> <output_variable>)
+
+Convert each byte in the input ``<string>`` to its hexadecimal representation
+and store the concatenated hex digits in the ``<output_variable>``. Letters in
+the output (``a`` through ``f``) are in lowercase.
+
 .. _CONFIGURE:
 
 .. code-block:: cmake

Help/command/target_link_options.rst

@@ -43,6 +43,8 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
+.. include:: DEVICE_LINK_OPTIONS.txt
+
 .. include:: OPTIONS_SHELL.txt
 
 .. include:: LINK_OPTIONS_LINKER.txt

Help/cpack_gen/archive.rst

@@ -1,8 +1,8 @@
 CPack Archive Generator
 -----------------------
 
-Archive CPack generator that supports packaging of sources and binaries in
-different formats:
+CPack generator for packaging files into an archive, which can have
+any of the following formats:
 
   - 7Z - 7zip - (.7z)
   - TBZ2 (.tar.bz2)
@@ -12,25 +12,64 @@ different formats:
   - TZST (.tar.zst)
   - ZIP (.zip)
 
+When this generator is called from ``CPackSourceConfig.cmake`` (or through
+the ``package_source`` target), then the generated archive will contain all
+files in the project directory, except those specified in
+:variable:`CPACK_SOURCE_IGNORE_FILES`.  The following is one example of
+packaging all source files of a project:
+
+.. code-block:: cmake
+
+  set(CPACK_SOURCE_GENERATOR "TGZ")
+  set(CPACK_SOURCE_IGNORE_FILES
+    \\.git/
+    build/
+    ".*~$"
+  )
+  set(CPACK_VERBATIM_VARIABLES YES)
+  include(CPack)
+
+When this generator is called from ``CPackConfig.cmake`` (or through the
+``package`` target), then the generated archive will contain all files
+that have been installed via CMake's :command:`install` command (and the
+deprecated commands :command:`install_files`, :command:`install_programs`,
+and :command:`install_targets`).
+
 Variables specific to CPack Archive generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. variable:: CPACK_ARCHIVE_FILE_NAME
               CPACK_ARCHIVE_<component>_FILE_NAME
 
- Package file name without extension which is added automatically depending
- on the archive format.
-
- * Mandatory : YES
- * Default   : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with
-               spaces replaced by '-'
+  Package file name without extension. The extension is determined from the
+  archive format (see list above) and automatically appended to the file name.
+  The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
+  replaced by '-'.
 
 .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
 
- Enable component packaging for CPackArchive
+  Enable component packaging. If enabled (ON), then the archive generator
+  creates  multiple packages. The default is OFF, which means that a single
+  package containing files of all components is generated.
+
+Variables used by CPack Archive generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These variables are used by the Archive generator, but are also available to
+CPack generators which are essentially archives at their core. These include:
+
+  - :cpack_gen:`CPack Cygwin Generator`
+  - :cpack_gen:`CPack FreeBSD Generator`
+
+.. variable:: CPACK_ARCHIVE_THREADS
+
+  The number of threads to use when performing the compression. If set to
+  ``0``, the number of available cores on the machine will be used instead.
+  The default is ``1`` which limits compression to a single thread. Note that
+  not all compression modes support threading in all environments. Currently,
+  only the XZ compression may support it.
 
- * Mandatory : NO
- * Default   : OFF
+.. note::
 
- If enabled (ON) multiple packages are generated. By default a single package
- containing files of all components is generated.
+    Official CMake binaries available on ``cmake.org`` ship with a ``liblzma``
+    that does not support parallel compression.

Help/cpack_gen/cygwin.rst

@@ -3,6 +3,11 @@ CPack Cygwin Generator
 
 Cygwin CPack generator (Cygwin).
 
+Variables affecting the CPack Cygwin generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  - :variable:`CPACK_ARCHIVE_THREADS`
+
 Variables specific to CPack Cygwin generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/cpack_gen/freebsd.rst

@@ -3,6 +3,11 @@ CPack FreeBSD Generator
 
 The built in (binary) CPack FreeBSD (pkg) generator (Unix only)
 
+Variables affecting the CPack FreeBSD (pkg) generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  - :variable:`CPACK_ARCHIVE_THREADS`
+
 Variables specific to CPack FreeBSD (pkg) generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/cpack_gen/ifw.rst

@@ -1,73 +1,28 @@
 CPack IFW Generator
 -------------------
 
+Configure and run the Qt Installer Framework to generate a Qt installer.
+
+.. only:: html
+
+  .. contents::
+
 Overview
 ^^^^^^^^
 
 This :manual:`cpack generator <cpack-generators(7)>` generates
 configuration and meta information for the `Qt Installer Framework
-<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW).
+<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
+and runs QtIFW tools to generate a Qt installer.
 
 QtIFW provides tools and utilities to create installers for
 the platforms supported by `Qt <https://www.qt.io>`_: Linux,
 Microsoft Windows, and macOS.
 
-To make use of this generator, QtIFW should also be installed.
-The module :module:`CPackIFW` looks for the location of the
-QtIFW command-line utilities.
-
-Hints
-^^^^^
-
-Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
-but if you don't use a default path for installation of the QtIFW tools,
-the path may be specified in either a CMake or an environment variable:
-
-.. variable:: CPACK_IFW_ROOT
-
- An CMake variable which specifies the location of the QtIFW tool suite.
-
- The variable will be cached in the ``CPackConfig.cmake`` file and used at
- CPack runtime.
-
-.. variable:: QTIFWDIR
-
- An environment variable which specifies the location of the QtIFW tool
- suite.
-
-.. note::
-  The specified path should not contain "bin" at the end
-  (for example: "D:\\DevTools\\QtIFW2.0.5").
-
-The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
-the value of the :variable:`QTIFWDIR` variable.
-
-Internationalization
-^^^^^^^^^^^^^^^^^^^^
-
-Some variables and command arguments support internationalization via
-CMake script. This is an optional feature.
-
-Installers created by QtIFW tools have built-in support for
-internationalization and many phrases are localized to many languages,
-but this does not apply to the description of the your components and groups
-that will be distributed.
-
-Localization of the description of your components and groups is useful for
-users of your installers.
-
-A localized variable or argument can contain a single default value, and a
-set of pairs the name of the locale and the localized value.
-
-For example:
-
-.. code-block:: cmake
-
-   set(LOCALIZABLE_VARIABLE "Default value"
-     en "English value"
-     en_US "American value"
-     en_GB "Great Britain value"
-     )
+To make use of this generator, QtIFW needs to be installed.
+The :module:`CPackIFW` module looks for the location of the
+QtIFW command-line utilities, and defines several commands to
+control the behavior of this generator.
 
 Variables
 ^^^^^^^^^
@@ -157,6 +112,8 @@ Package
  Default target directory for installation.
  By default used
  "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
+ (variables embedded in '@' are expanded by the
+ `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
 
  You can use predefined variables.
 
@@ -263,55 +220,111 @@ Components
  repack dependent components. This feature available only
  since QtIFW 3.1.
 
-Tools
-"""""
+QtIFW Tools
+"""""""""""
 
 .. variable:: CPACK_IFW_FRAMEWORK_VERSION
 
  The version of used QtIFW tools.
 
-.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE
+The following variables provide the locations of the QtIFW
+command-line tools as discovered by the module :module:`CPackIFW`.
+These variables are cached, and may be configured if needed.
 
- The path to "binarycreator" command line client.
+.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE
 
- This variable is cached and may be configured if needed.
+ The path to ``binarycreator``.
 
 .. variable:: CPACK_IFW_REPOGEN_EXECUTABLE
 
- The path to "repogen" command line client.
-
- This variable is cached and may be configured if needed.
+ The path to ``repogen``.
 
 .. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE
 
- The path to "installerbase" installer executable base.
-
- This variable is cached and may be configured if needed.
+ The path to ``installerbase``.
 
 .. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE
 
- The path to "devtool" command line client.
+ The path to ``devtool``.
+
+Hints for Finding QtIFW
+"""""""""""""""""""""""
+
+Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
+but if you don't use a default path for installation of the QtIFW tools,
+the path may be specified in either a CMake or an environment variable:
+
+.. variable:: CPACK_IFW_ROOT
 
- This variable is cached and may be configured if needed.
+ An CMake variable which specifies the location of the QtIFW tool suite.
+
+ The variable will be cached in the ``CPackConfig.cmake`` file and used at
+ CPack runtime.
+
+.. variable:: QTIFWDIR
+
+ An environment variable which specifies the location of the QtIFW tool
+ suite.
+
+.. note::
+  The specified path should not contain "bin" at the end
+  (for example: "D:\\DevTools\\QtIFW2.0.5").
+
+The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
+the value of the :variable:`QTIFWDIR` variable.
 
+Other Settings
+^^^^^^^^^^^^^^
 
 Online installer
-^^^^^^^^^^^^^^^^
+""""""""""""""""
 
-By default CPack IFW generator makes offline installer. This means that all
-components will be packaged into a binary file.
+By default, this generator generates an *offline installer*. This means that
+that all packaged files are fully contained in the installer executable.
 
-To make a component downloaded, you must set the ``DOWNLOADED`` option in
-:command:`cpack_add_component`.
+In contrast, an *online installer* will download some or all components from
+a remote server.
 
-Then you would use the command :command:`cpack_configure_downloads`.
-If you set ``ALL`` option all components will be downloaded.
+The ``DOWNLOADED`` option in the :command:`cpack_add_component` command
+specifies that a component is to be downloaded. Alternatively, the ``ALL``
+option in the :command:`cpack_configure_downloads` command specifies that
+`all` components are to be be downloaded.
 
-You also can use command :command:`cpack_ifw_add_repository` and
-variable :variable:`CPACK_IFW_DOWNLOAD_ALL` for more specific configuration.
+The :command:`cpack_ifw_add_repository` command and the
+:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific
+configuration.
 
-CPack IFW generator creates "repository" dir in current binary dir. You
-would copy content of this dir to specified ``site`` (``url``).
+When there are online components, CPack will write them to archive files.
+The help page of the :module:`CPackComponent` module, especially the section
+on the :command:`cpack_configure_downloads` function, explains how to make
+these files accessible from a download URL.
+
+Internationalization
+""""""""""""""""""""
+
+Some variables and command arguments support internationalization via
+CMake script. This is an optional feature.
+
+Installers created by QtIFW tools have built-in support for
+internationalization and many phrases are localized to many languages,
+but this does not apply to the description of the your components and groups
+that will be distributed.
+
+Localization of the description of your components and groups is useful for
+users of your installers.
+
+A localized variable or argument can contain a single default value, and a
+set of pairs the name of the locale and the localized value.
+
+For example:
+
+.. code-block:: cmake
+
+   set(LOCALIZABLE_VARIABLE "Default value"
+     en "English value"
+     en_US "American value"
+     en_GB "Great Britain value"
+     )
 
 See Also
 ^^^^^^^^
@@ -330,5 +343,5 @@ Qt Installer Framework Manual:
 * Promoting Updates:
   http://doc.qt.io/qtinstallerframework/ifw-updates.html
 
-Download Qt Installer Framework for you platform from Qt site:
+Download Qt Installer Framework for your platform from Qt site:
  http://download.qt.io/official_releases/qt-installer-framework

Help/cpack_gen/nsis.rst

@@ -155,3 +155,7 @@ on Windows Nullsoft Scriptable Install System.
 .. variable:: CPACK_NSIS_MUI_HEADERIMAGE
 
  The image to display on the header of installers pages.
+
+.. variable:: CPACK_NSIS_MANIFEST_DPI_AWARE
+
+ If set, declares that the installer is DPI-aware.

Help/cpack_gen/rpm.rst

@@ -473,38 +473,42 @@ List of CPack RPM generator specific variables:
 
 .. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
               CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
+              CPACK_RPM_PRE_TRANS_SCRIPT_FILE
 
- Path to file containing pre (un)install script.
+ Path to file containing pre install/uninstall/transaction script.
 
  * Mandatory : NO
  * Default   : -
 
- May be used to embed a pre (un)installation script in the spec file.
+ May be used to embed a pre installation/uninstallation/transaction script in the spec file.
  The referred script file (or both) will be read and directly
  put after the ``%pre`` or ``%preun`` section
- If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
+ If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
  script for each component can be overridden with
- ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and
- ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``.
+ ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``,
+ ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and
+ ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE``
  One may verify which scriptlet has been included with::
 
   rpm -qp --scripts  package.rpm
 
 .. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
               CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
+              CPACK_RPM_POST_TRANS_SCRIPT_FILE
 
- Path to file containing post (un)install script.
+ Path to file containing post install/uninstall/transaction script.
 
  * Mandatory : NO
  * Default   : -
 
- May be used to embed a post (un)installation script in the spec file.
+ May be used to embed a post installation/uninstallation/transaction script in the spec file.
  The referred script file (or both) will be read and directly
  put after the ``%post`` or ``%postun`` section.
- If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
+ If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
  script for each component can be overridden with
- ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and
- ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``.
+ ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``,
+ ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and
+ ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE``
  One may verify which scriptlet has been included with::
 
   rpm -qp --scripts  package.rpm

Help/dev/source.rst

@@ -23,12 +23,145 @@ format only a subset of files, such as those that are locally modified.
 C++ Subset Permitted
 ====================
 
-CMake requires compiling as C++11 or above.  However, in order to support
-building on older toolchains some constructs need to be handled with care:
+CMake requires compiling as C++11 in order to support building on older
+toolchains.  However, to facilitate development, some standard library
+features from more recent C++ standards are supported through a compatibility
+layer.  These features are defined under the namespace ``cm`` and headers
+are accessible under the ``cm/`` directory.  The headers under ``cm/`` can
+be used in place of the standard ones when extended features are needed.
+For example ``<cm/memory>`` can be used in place of ``<memory>``.
 
-* Do not use ``std::auto_ptr``.
+Available features are:
 
-  The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``.
+* From ``C++14``:
+
+  * ``<cm/iterator>``:
+    ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``,
+    ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/memory>``:
+    ``cm::make_unique``
+
+  * ``<cm/shared_mutex>``:
+    ``cm::shared_lock``
+
+  * ``<cm/type_traits>``:
+    ``cm::enable_if_t``
+
+* From ``C++17``:
+
+  * ``<cm/algorithm>``:
+    ``cm::clamp``
+
+  * ``<cm/iterator>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
+  * ``<cm/optional>``:
+    ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``,
+    ``cm::make_optional``, ``cm::bad_optional_access``
+
+  * ``<cm/shared_mutex>``:
+    ``cm::shared_mutex``
+
+  * ``<cm/string_view>``:
+    ``cm::string_view``
+
+  * ``<cm/type_traits>``:
+    ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``,
+    ``cm::void_t``
+
+  * ``<cm/utility>``:
+    ``cm::in_place_t``, ``cm::in_place``
+
+* From ``C++20``:
+
+  * ``<cm/deque>``:
+    ``cm::erase``, ``cm::erase_if``
+
+  * ``<cm/list>``:
+    ``cm::erase``, ``cm::erase_if``
+
+  * ``<cm/map>`` :
+    ``cm::erase_if``
+
+  * ``<cm/set>`` :
+    ``cm::erase_if``
+
+  * ``<cm/string>``:
+    ``cm::erase``, ``cm::erase_if``
+
+  * ``<cm/unordered_map>``:
+    ``cm::erase_if``
+
+  * ``<cm/unordered_set>``:
+    ``cm::erase_if``
+
+  * ``<cm/vector>``:
+    ``cm::erase``, ``cm::erase_if``
+
+Additionally, some useful non-standard extensions to the C++ standard library
+are available in headers under the directory ``cmext/`` in namespace ``cm``.
+These are:
+
+* ``<cmext/algorithm>``:
+
+  * ``cm::append``:
+    Append elements to a sequential container.
+
+  * ``cm::contains``:
+    Checks if element or key is contained in container.
+
+* ``<cmext/iterator>``:
+
+  * ``cm::is_terator``:
+    Checks if a type is an iterator type.
+
+  * ``cm::is_input_iterator``:
+    Checks if a type is an input iterator type.
+
+  * ``cm::is_range``:
+    Checks if a type is a range type: functions ``std::begin()`` and
+    ``std::end()`` apply.
+
+  * ``cm::is_input_range``:
+    Checks if a type is an input range type: functions ``std::begin()`` and
+    ``std::end()`` apply and return an input iterator.
+
+* ``<cmext/memory>``:
+
+  * ``cm::static_reference_cast``:
+    Apply a ``static_cast`` to a smart pointer.
+
+  * ``cm::dynamic_reference_cast``:
+    Apply a ``dynamic_cast`` to a smart pointer.
+
+* ``<cmext/type_traits>``:
+
+  * ``cm::is_container``:
+    Checks if a type is a container type.
+
+  * ``cm::is_associative_container``:
+    Checks if a type is an associative container type.
+
+  * ``cm::is_unordered_associative_container``:
+    Checks if a type is an unordered associative container type.
+
+  * ``cm::is_sequence_container``:
+    Checks if a type is a sequence container type.
+
+  * ``cm::is_unique_ptr``:
+    Checks if a type is a ``std::unique_ptr`` type.
+
+Dynamic Memory Management
+=========================
+
+To ensure efficient memory management, i.e. no memory leaks, it is required
+to use smart pointers.  Any dynamic memory allocation must be handled by a
+smart pointer such as ``std::unique_ptr`` or ``std::shared_ptr``.
+
+It is allowed to pass raw pointers between objects to enable objects sharing.
+A raw pointer **must** not be deleted. Only the object(s) owning the smart
+pointer are allowed to delete dynamically allocated memory.
 
 Source Tree Layout
 ==================
@@ -69,6 +202,12 @@ The CMake source tree is organized as follows.
 * ``Utilities/``:
   Scripts, third-party source code.
 
+  * ``Utilities/std/cm``:
+    Support files for various C++ standards.
+
+  * ``Utilities/std/cmext``:
+    Extensions to the C++ STL.
+
   * ``Utilities/Sphinx/``:
     Sphinx configuration to build CMake user documentation.
 

Help/envvar/CMAKE_PREFIX_PATH.rst

@@ -0,0 +1,17 @@
+CMAKE_PREFIX_PATH
+-----------------
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_PREFIX_PATH`` environment variable may be set to a list of
+directories specifying installation *prefixes* to be searched by the
+:command:`find_package`, :command:`find_program`, :command:`find_library`,
+:command:`find_file`, and :command:`find_path` commands.  Each command will
+add appropriate subdirectories (like ``bin``, ``lib``, or ``include``)
+as specified in its own documentation.
+
+This variable may hold a single prefix or a list of prefixes separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`CMAKE_PREFIX_PATH` CMake variable.

Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt

@@ -8,10 +8,20 @@ target_include_directories(MathFunctions
 
 # does this system provide the log and exp functions?
 include(CheckSymbolExists)
-set(CMAKE_REQUIRED_LIBRARIES "m")
 check_symbol_exists(log "math.h" HAVE_LOG)
 check_symbol_exists(exp "math.h" HAVE_EXP)
+if(NOT (HAVE_LOG AND HAVE_EXP))
+  unset(HAVE_LOG CACHE)
+  unset(HAVE_EXP CACHE)
+  set(CMAKE_REQUIRED_LIBRARIES "m")
+  check_symbol_exists(log "math.h" HAVE_LOG)
+  check_symbol_exists(exp "math.h" HAVE_EXP)
+  if(HAVE_LOG AND HAVE_EXP)
+    target_link_libraries(MathFunctions PRIVATE m)
+  endif()
+endif()
 
+# add compile definitions
 if(HAVE_LOG AND HAVE_EXP)
   target_compile_definitions(MathFunctions
                              PRIVATE "HAVE_LOG" "HAVE_EXP")

Help/guide/tutorial/index.rst

@@ -386,7 +386,7 @@ these functions using the :module:`CheckSymbolExists` module in the top-level
 .. literalinclude:: Step6/MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # does this system provide the log and exp functions?
-  :end-before: if(HAVE_LOG AND HAVE_EXP)
+  :end-before: # add compile definitions
 
 Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them
 from ``mysqrt.cxx``:

Help/manual/cmake-commands.7.rst

@@ -16,6 +16,7 @@ These commands are always available.
    :maxdepth: 1
 
    /command/break
+   /command/cmake_command
    /command/cmake_host_system_information
    /command/cmake_minimum_required
    /command/cmake_parse_arguments

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

@@ -14,6 +14,13 @@ For general information on environment variables, see the
 :ref:`Environment Variables <CMake Language Environment Variables>`
 section in the cmake-language manual.
 
+Environment Variables that Change Behavior
+==========================================
+
+.. toctree::
+   :maxdepth: 1
+
+   /envvar/CMAKE_PREFIX_PATH
 
 Environment Variables that Control the Build
 ============================================

Help/manual/cmake-generator-expressions.7.rst

@@ -259,6 +259,121 @@ Variable Queries
     add_executable(myapp main.cpp)
     target_link_libraries(myapp myapp_c myapp_cxx)
 
+.. _`Boolean LINK_LANGUAGE Generator Expression`:
+
+``$<LINK_LANG_AND_ID:language,compiler_ids>``
+  ``1`` when the language used for link step matches ``language`` and the
+  CMake's compiler id of the language linker matches any one of the entries
+  in ``compiler_ids``, otherwise ``0``. This expression is a short form for the
+  combination of ``$<LINK_LANGUAGE:language>`` and
+  ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
+  link libraries, link options, link directories and link dependencies of a
+  particular language and linker combination in a target. For example:
+
+  .. code-block:: cmake
+
+    add_library(libC_Clang ...)
+    add_library(libCXX_Clang ...)
+    add_library(libC_Intel ...)
+    add_library(libCXX_Intel ...)
+
+    add_executable(myapp main.c)
+    if (CXX_CONFIG)
+      target_sources(myapp PRIVATE file.cxx)
+    endif()
+    target_link_libraries(myapp
+      PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
+              $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
+              $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
+              $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
+
+  This specifies the use of different link libraries based on both the
+  compiler id and link language. This example will have target ``libCXX_Clang``
+  as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX``
+  linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker.
+  Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target
+  ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when
+  ``Intel`` is the ``C`` linker.
+
+  See :ref:`the note related to
+  <Constraints LINK_LANGUAGE Generator Expression>`
+  ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this
+  generator expression.
+
+``$<LINK_LANGUAGE:languages>``
+  ``1`` when the language used for link step matches any of the entries
+  in ``languages``, otherwise ``0``.  This expression may be used to specify
+  link libraries, link options, link directories and link dependencies of a
+  particular language in a target. For example:
+
+  .. code-block:: cmake
+
+    add_library(api_C ...)
+    add_library(api_CXX ...)
+    add_library(api INTERFACE)
+    target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
+                                        $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
+    target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
+                                        $<$<LINK_LANGUAGE:CXX>:api_CXX>)
+
+    add_executable(myapp1 main.c)
+    target_link_options(myapp1 PRIVATE api)
+
+    add_executable(myapp2 main.cpp)
+    target_link_options(myapp2 PRIVATE api)
+
+  This specifies to use the ``api`` target for linking targets ``myapp1`` and
+  ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and
+  option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2``
+  will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be
+  the link language.
+
+  .. _`Constraints LINK_LANGUAGE Generator Expression`:
+
+  .. note::
+
+    To determine the link language of a target, it is required to collect,
+    transitively, all the targets which will be linked to it. So, for link
+    libraries properties, a double evaluation will be done. During the first
+    evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``.
+    The link language computed after this first pass will be used to do the
+    second pass. To avoid inconsistency, it is required that the second pass
+    do not change the link language. Moreover, to avoid unexpected
+    side-effects, it is required to specify complete entities as part of the
+    ``$<LINK_LANGUAGE:..>`` expression. For example:
+
+    .. code-block:: cmake
+
+      add_library(lib STATIC file.cxx)
+      add_library(libother STATIC file.c)
+
+      # bad usage
+      add_executable(myapp1 main.c)
+      target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
+
+      # correct usage
+      add_executable(myapp2 main.c)
+      target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
+
+    In this example, for ``myapp1``, the first pass will, unexpectedly,
+    determine that the link language is ``CXX`` because the evaluation of the
+    generator expression will be an empty string so ``myapp1`` will depends on
+    target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first
+    evaluation will give ``C`` as link language, so the second pass will
+    correctly add target ``libother`` as link dependency.
+
+``$<DEVICE_LINK:list>``
+  Returns the list if it is the device link step, an empty list otherwise.
+  The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
+  and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties. This expression can
+  only be used to specify link options.
+
+``$<HOST_LINK:list>``
+  Returns the list if it is the normal link step, an empty list otherwise.
+  This expression is mainly useful when a device link step is also involved
+  (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only
+  be used to specify link options.
+
 String-Valued Generator Expressions
 ===================================
 
@@ -450,22 +565,41 @@ Variable Queries
   <Boolean COMPILE_LANGUAGE Generator Expression>`
   ``$<COMPILE_LANGUAGE:language>``
   for notes about the portability of this generator expression.
+``$<LINK_LANGUAGE>``
+  The link language of target when evaluating link options.
+  See :ref:`the related boolean expression
+  <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>``
+  for notes about the portability of this generator expression.
+
+  .. note::
+
+    This generator expression is not supported by the link libraries
+    properties to avoid side-effects due to the double evaluation of
+    these properties.
 
 Target-Dependent Queries
 ------------------------
 
+These queries refer to a target ``tgt``. This can be any runtime artifact,
+namely:
+
+* an executable target created by :command:`add_executable`
+* a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library)
+  created by :command:`add_library`
+* a static library target created by :command:`add_library`
+
+In the following, "the ``tgt`` filename" means the name of the ``tgt``
+binary file. This has to be distinguished from "the target name",
+which is just the string ``tgt``.
+
 ``$<TARGET_NAME_IF_EXISTS:tgt>``
-  Expands to the ``tgt`` if the given target exists, an empty string
-  otherwise.
+  The target name ``tgt`` if the target exists, an empty string otherwise.
 ``$<TARGET_FILE:tgt>``
-  Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a
-  target.
+  Full path to the ``tgt`` binary file.
 ``$<TARGET_FILE_BASE_NAME:tgt>``
-  Base name of main file where ``tgt`` is the name of a target.
-
-  The base name corresponds to the target file name (see
-  ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if
-  target file name is ``libbase.so``, the base name is ``base``.
+  Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and
+  suffix.
+  For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``.
 
   See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
   :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
@@ -480,32 +614,31 @@ Target-Dependent Queries
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
 ``$<TARGET_FILE_PREFIX:tgt>``
-  Prefix of main file where ``tgt`` is the name of a target.
+  Prefix of the ``tgt`` filename (such as ``lib``).
 
   See also the :prop_tgt:`PREFIX` target property.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
 ``$<TARGET_FILE_SUFFIX:tgt>``
-  Suffix of main file where ``tgt`` is the name of a target.
-
-  The suffix corresponds to the file extension (such as ".so" or ".exe").
+  Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``).
 
   See also the :prop_tgt:`SUFFIX` target property.
 
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
 ``$<TARGET_FILE_NAME:tgt>``
-  Name of main file (.exe, .so.1.2, .a).
+  The ``tgt`` filename.
 ``$<TARGET_FILE_DIR:tgt>``
-  Directory of main file (.exe, .so.1.2, .a).
+  Directory of the ``tgt`` binary file.
 ``$<TARGET_LINKER_FILE:tgt>``
-  File used to link (.a, .lib, .so) where ``tgt`` is the name of a target.
+  File used when linking to the ``tgt`` target.  This will usually
+  be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``),
+  but for a shared library on DLL platforms, it would be the ``.lib``
+  import library associated with the DLL.
 ``$<TARGET_LINKER_FILE_BASE_NAME:tgt>``
-  Base name of file used to link where ``tgt`` is the name of a target.
-
-  The base name corresponds to the target linker file name (see
-  ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example,
+  Base name of file used to link the target ``tgt``, i.e.
+  ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example,
   if target file name is ``libbase.a``, the base name is ``base``.
 
   See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
@@ -520,7 +653,7 @@ Target-Dependent Queries
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
 ``$<TARGET_LINKER_FILE_PREFIX:tgt>``
-  Prefix of file used to link where ``tgt`` is the name of a target.
+  Prefix of file used to link target ``tgt``.
 
   See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target
   properties.
@@ -538,15 +671,15 @@ Target-Dependent Queries
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
 ``$<TARGET_LINKER_FILE_NAME:tgt>``
-  Name of file used to link (.a, .lib, .so).
+  Name of file used to link target ``tgt``.
 ``$<TARGET_LINKER_FILE_DIR:tgt>``
-  Directory of file used to link (.a, .lib, .so).
+  Directory of file used to link target ``tgt``.
 ``$<TARGET_SONAME_FILE:tgt>``
-  File with soname (.so.3) where ``tgt`` is the name of a target.
+  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).
+  Name of file with soname (``.so.3``).
 ``$<TARGET_SONAME_FILE_DIR:tgt>``
-  Directory of with soname (.so.3).
+  Directory of with soname (``.so.3``).
 ``$<TARGET_PDB_FILE:tgt>``
   Full path to the linker generated program database file (.pdb)
   where ``tgt`` is the name of a target.
@@ -589,11 +722,10 @@ Target-Dependent Queries
   Note that ``tgt`` is not added as a dependency of the target this
   expression is evaluated on.
 ``$<TARGET_PROPERTY:prop>``
-  Value of the property ``prop`` on the target on which the generator
-  expression is evaluated. Note that for generator expressions in
-  :ref:`Target Usage Requirements` this is the value of the property
-  on the consuming target rather than the target specifying the
-  requirement.
+  Value of the property ``prop`` on the target for which the expression
+  is being evaluated. Note that for generator expressions in
+  :ref:`Target Usage Requirements` this is the consuming target rather
+  than the target specifying the requirement.
 ``$<INSTALL_PREFIX>``
   Content of the install prefix when the target is exported via
   :command:`install(EXPORT)`, or when evaluated in

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.18
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0106: The Documentation module is removed. </policy/CMP0106>
+   CMP0105: Device link step uses the link options. </policy/CMP0105>
+   CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104>
+   CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103>
+
 Policies Introduced by CMake 3.17
 =================================
 

Help/manual/cmake-properties.7.rst

@@ -127,6 +127,7 @@ Properties on Targets
    /prop_tgt/ARCHIVE_OUTPUT_DIRECTORY
    /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG
    /prop_tgt/ARCHIVE_OUTPUT_NAME
+   /prop_tgt/PCH_WARN_INVALID
    /prop_tgt/AUTOGEN_BUILD_DIR
    /prop_tgt/AUTOGEN_ORIGIN_DEPENDS
    /prop_tgt/AUTOGEN_PARALLEL
@@ -171,6 +172,7 @@ Properties on Targets
    /prop_tgt/CONFIG_OUTPUT_NAME
    /prop_tgt/CONFIG_POSTFIX
    /prop_tgt/CROSSCOMPILING_EMULATOR
+   /prop_tgt/CUDA_ARCHITECTURES
    /prop_tgt/CUDA_PTX_COMPILATION
    /prop_tgt/CUDA_SEPARABLE_COMPILATION
    /prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS
@@ -200,6 +202,7 @@ Properties on Targets
    /prop_tgt/Fortran_FORMAT
    /prop_tgt/Fortran_MODULE_DIRECTORY
    /prop_tgt/FRAMEWORK
+   /prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG
    /prop_tgt/FRAMEWORK_VERSION
    /prop_tgt/GENERATOR_FILE_NAME
    /prop_tgt/GHS_INTEGRITY_APP
@@ -375,6 +378,8 @@ Properties on Targets
    /prop_tgt/VS_SCC_PROJECTNAME
    /prop_tgt/VS_SCC_PROVIDER
    /prop_tgt/VS_SDK_REFERENCES
+   /prop_tgt/VS_SOLUTION_DEPLOY
+   /prop_tgt/VS_SOURCE_SETTINGS_tool
    /prop_tgt/VS_USER_PROPS
    /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
    /prop_tgt/VS_WINRT_COMPONENT
@@ -484,6 +489,7 @@ Properties on Source Files
    /prop_sf/VS_DEPLOYMENT_LOCATION
    /prop_sf/VS_INCLUDE_IN_VSIX
    /prop_sf/VS_RESOURCE_GENERATOR
+   /prop_sf/VS_SETTINGS
    /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS
    /prop_sf/VS_SHADER_ENABLE_DEBUG
    /prop_sf/VS_SHADER_ENTRYPOINT

Help/manual/cmake-variables.7.rst

@@ -388,6 +388,7 @@ Variables that Control the Build
    /variable/CMAKE_EXE_LINKER_FLAGS_INIT
    /variable/CMAKE_FOLDER
    /variable/CMAKE_FRAMEWORK
+   /variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG
    /variable/CMAKE_Fortran_FORMAT
    /variable/CMAKE_Fortran_MODULE_DIRECTORY
    /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE
@@ -437,6 +438,7 @@ Variables that Control the Build
    /variable/CMAKE_OSX_ARCHITECTURES
    /variable/CMAKE_OSX_DEPLOYMENT_TARGET
    /variable/CMAKE_OSX_SYSROOT
+   /variable/CMAKE_PCH_WARN_INVALID
    /variable/CMAKE_PDB_OUTPUT_DIRECTORY
    /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_POSITION_INDEPENDENT_CODE
@@ -486,6 +488,7 @@ Variables for Languages
    /variable/CMAKE_COMPILER_IS_GNUCC
    /variable/CMAKE_COMPILER_IS_GNUCXX
    /variable/CMAKE_COMPILER_IS_GNUG77
+   /variable/CMAKE_CUDA_ARCHITECTURES
    /variable/CMAKE_CUDA_COMPILE_FEATURES
    /variable/CMAKE_CUDA_HOST_COMPILER
    /variable/CMAKE_CUDA_EXTENSIONS
@@ -621,6 +624,7 @@ Variables for CTest
    /variable/CTEST_P4_COMMAND
    /variable/CTEST_P4_OPTIONS
    /variable/CTEST_P4_UPDATE_OPTIONS
+   /variable/CTEST_RESOURCE_SPEC_FILE
    /variable/CTEST_RUN_CURRENT_SCRIPT
    /variable/CTEST_SCP_COMMAND
    /variable/CTEST_SITE

Help/manual/cmake.1.rst

@@ -358,6 +358,20 @@ Options
  in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
  This flag tells CMake to warn about other files as well.
 
+``--profiling-output=<path>``
+ Used in conjuction with ``--profiling-format`` to output to a given path.
+
+``--profiling-format=<file>``
+ Enable the output of profiling data of CMake script in the given format.
+
+ This can aid performance analysis of CMake scripts executed. Third party
+ applications should be used to process the output into human readable format.
+
+ Currently supported values are:
+ ``google-trace`` Outputs in Google Trace Format, which can be parsed by the
+ about:tracing tab of Google Chrome or using a plugin for a tool like Trace
+ Compass.
+
 .. _`Build Tool Mode`:
 
 Build a Project
@@ -540,6 +554,9 @@ Available commands are:
   ``serverMode``
     ``true`` if cmake supports server-mode and ``false`` otherwise.
 
+``cat <files>...``
+  Concatenate files and print on the standard output.
+
 ``chdir <dir> <cmd> [<arg>...]``
   Change the current working directory and run a command.
 

Help/manual/ctest.1.rst

@@ -72,6 +72,9 @@ Options
  This option can also be enabled by setting the
  :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable
 
+``--stop-on-failure``
+ Stop running the tests when the first failure happens.
+
 ``-F``
  Enable failover.
 
@@ -994,8 +997,12 @@ Configuration settings include:
 
 ``ResourceSpecFile``
   Specify a
-  :ref:`resource specification file <ctest-resource-specification-file>`. See
-  :ref:`ctest-resource-allocation` for more information.
+  :ref:`resource specification file <ctest-resource-specification-file>`.
+
+  * `CTest Script`_ variable: :variable:`CTEST_RESOURCE_SPEC_FILE`
+  * :module:`CTest` module variable: ``CTEST_RESOURCE_SPEC_FILE``
+
+  See :ref:`ctest-resource-allocation` for more information.
 
 ``LabelsForSubprojects``
   Specify a semicolon-separated list of labels that will be treated as

Help/policy/CMP0103.rst

@@ -0,0 +1,22 @@
+CMP0103
+-------
+
+Multiple calls to :command:`export` command with same ``FILE`` without
+``APPEND`` is no longer allowed.
+
+In CMake 3.17 and below, multiple calls to :command:`export` command with the
+same ``FILE`` without ``APPEND`` are accepted silently but only the last
+occurrence is taken into account during the generation.
+
+The ``OLD`` behavior for this policy is to ignore the multiple occurrences of
+ :command:`export` command except the last one.
+
+The ``NEW`` behavior of this policy is to raise an error on second call to
+:command:`export` command with same ``FILE`` without ``APPEND``.
+
+This policy was introduced in CMake version 3.18.  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

Help/policy/CMP0104.rst

@@ -0,0 +1,31 @@
+CMP0104
+-------
+
+Initialize :variable:`CMAKE_CUDA_ARCHITECTURES` when
+:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
+Raise an error if :prop_tgt:`CUDA_ARCHITECTURES` is empty.
+
+:variable:`CMAKE_CUDA_ARCHITECTURES` introduced in CMake 3.18 is used to
+initialize :prop_tgt:`CUDA_ARCHITECTURES`, which passes correct code generation
+flags to the CUDA compiler.
+
+Previous to this users had to manually specify the code generation flags. This
+policy is for backwards compatibility with manually specifying code generation
+flags.
+
+The ``OLD`` behavior for this policy is to not initialize
+:variable:`CMAKE_CUDA_ARCHITECTURES` when
+:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
+Empty :prop_tgt:`CUDA_ARCHITECTURES` is allowed.
+
+The ``NEW`` behavior of this policy is to initialize
+:variable:`CMAKE_CUDA_ARCHITECTURES` when
+:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``
+and raise an error if :prop_tgt:`CUDA_ARCHITECTURES` is empty during generation.
+
+This policy was introduced in CMake version 3.18.  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

Help/policy/CMP0105.rst

@@ -0,0 +1,19 @@
+CMP0105
+-------
+
+:prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
+properties are now used for the device link step.
+
+In CMake 3.17 and below, link options are not used by the device link step.
+
+The ``OLD`` behavior for this policy is to ignore the link options.
+
+The ``NEW`` behavior of this policy is to use the link options during the
+device link step.
+
+This policy was introduced in CMake version 3.17.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0106.rst

@@ -0,0 +1,19 @@
+CMP0106
+-------
+
+The :module:`Documentation` module is removed.
+
+The :module:`Documentation` was added as a support mechanism for the VTK
+project and was tuned for that project. Instead of CMake providing this module
+with (now old) VTK patterns for cache variables and required packages, the
+module is now deprecated by CMake itself.
+
+The ``OLD`` behavior of this policy is for :module:`Documentation` to add
+cache variables and find VTK documentation dependent packages. The ``NEW``
+behavior is to act as an empty module.
+
+This policy was introduced in CMake version 3.18.  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

Help/prop_dir/LINK_OPTIONS.rst

@@ -2,7 +2,7 @@ LINK_OPTIONS
 ------------
 
 List of options to use for the link step of shared library, module
-and executable targets.
+and executable targets as well as the device link step.
 
 This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
 given so far to the :command:`add_link_options` command.

Help/prop_sf/VS_SETTINGS.rst

@@ -0,0 +1,18 @@
+VS_SETTINGS
+-----------
+
+Set any item metadata on a non-built file.
+
+Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator to set
+``Key`` to ``Value`` as item metadata on the file.
+
+For example:
+
+.. code-block:: cmake
+
+  set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2")
+
+will set ``Key`` to ``Value`` and ``Key2`` to ``Value2`` on the
+``file.hlsl`` item as metadata.
+
+Generator expressions are supported.

Help/prop_tgt/CONFIG_POSTFIX.rst

@@ -8,3 +8,6 @@ is appended to the target file name built on disk.  For non-executable
 targets, this property is initialized by the value of the variable
 CMAKE_<CONFIG>_POSTFIX if it is set when a target is created.  This
 property is ignored on the Mac for Frameworks and App Bundles.
+
+For macOS see also the :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
+target property.

Help/prop_tgt/CUDA_ARCHITECTURES.rst

@@ -0,0 +1,30 @@
+CUDA_ARCHITECTURES
+------------------
+
+List of architectures to generate device code for.
+
+An architecture can be suffixed by either ``-real`` or ``-virtual`` to specify
+the kind of architecture to generate code for.
+If no suffix is given then code is generated for both real and virtual
+architectures.
+
+This property is initialized by the value of the :variable:`CMAKE_CUDA_ARCHITECTURES`
+variable if it is set when a target is created.
+
+The ``CUDA_ARCHITECTURES`` target property must be set to a non-empty value on targets
+that compile CUDA sources, or it is an error.  See policy :policy:`CMP0104`.
+
+Examples
+^^^^^^^^
+
+.. code-block:: cmake
+
+  set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72)
+
+Generates code for real and virtual architectures ``30``, ``50`` and ``72``.
+
+.. code-block:: cmake
+
+  set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)
+
+Generates code for real architecture ``70`` and virtual architecture ``72``.

Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst

@@ -0,0 +1,25 @@
+FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
+---------------------------------------
+
+Postfix to append to the framework file name for configuration <CONFIG>,
+when using a multi-config generator (like Xcode and Ninja Multi-Config).
+
+When building with configuration <CONFIG> the value of this property
+is appended to the framework file name built on disk.
+
+For example given a framework called ``my_fw``, a value of ``_debug``
+for the :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` property, and
+``Debug;Release`` in `CMAKE_CONFIGURATION_TYPES`, the following relevant
+files would be created for the ``Debug`` and ``Release`` configurations:
+
+- Release/my_fw.framework/my_fw
+- Release/my_fw.framework/Versions/A/my_fw
+- Debug/my_fw.framework/my_fw_debug
+- Debug/my_fw.framework/Versions/A/my_fw_debug
+
+For framework targets, this property is initialized by the value of the
+variable :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` if it
+is set when a target is created.
+
+This property is ignored for non-framework targets, and when using single
+config generators.

Help/prop_tgt/LINK_OPTIONS.rst

@@ -2,12 +2,16 @@ LINK_OPTIONS
 ------------
 
 List of options to use for the link step of shared library, module
-and executable targets. Targets that are static libraries need to use
-the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
+and executable targets as well as the device link step. Targets that are static
+libraries need to use the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
 
+These options are used for both normal linking and device linking
+(see policy :policy:`CMP0105`). To control link options for normal and device
+link steps, ``$<HOST_LINK>`` and ``$<DEVICE_LINK>``
+:manual:`generator expressions <cmake-generator-expressions(7)>` can be used.
 
-This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
-specified so far for its target.  Use the :command:`target_link_options`
+This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of
+options specified so far for its target.  Use the :command:`target_link_options`
 command to append more options.
 
 This property is initialized by the :prop_dir:`LINK_OPTIONS` directory

Help/prop_tgt/PCH_WARN_INVALID.rst

@@ -0,0 +1,8 @@
+PCH_WARN_INVALID
+----------------
+
+When this property is set to true, the precompile header compiler options
+will contain a compiler flag wich should warn about invalid precompiled
+headers e.g. ``-Winvalid-pch`` for GNU compiler.
+
+The defalut value is ``ON``.

Help/prop_tgt/VS_SOLUTION_DEPLOY.rst

@@ -0,0 +1,29 @@
+VS_SOLUTION_DEPLOY
+------------------
+
+Specify that the target should be marked for deployment when not targeting
+Windows CE, Windows Phone or a Windows Store application.
+
+If the target platform doesn't support deployment, this property won't have any effect.
+
+Generator expressions are supported.
+
+Example 1
+^^^^^^^^^
+
+This shows setting the variable for the target foo.
+
+.. code-block:: cmake
+
+  add_executable(foo SHARED foo.cpp)
+  set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON)
+
+Example 2
+^^^^^^^^^
+
+This shows setting the variable for the Release configuration only.
+
+.. code-block:: cmake
+
+  add_executable(foo SHARED foo.cpp)
+  set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>")

Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst

@@ -0,0 +1,19 @@
+VS_SOURCE_SETTINGS_<tool>
+-------------------------
+
+Set any item metadata on all non-built files that use <tool>.
+
+Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator
+to set ``Key`` to ``Value`` as item metadata on all non-built files
+that use ``<tool>``.
+
+For example:
+
+.. code-block:: cmake
+
+  set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2")
+
+will set ``Key`` to ``Value`` and ``Key2`` to ``Value2`` for all
+non-built files that use ``FXCompile``.
+
+Generator expressions are supported.

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.

Help/release/dev/CPackRPM-trans-scripts.rst

@@ -0,0 +1,7 @@
+CPackRPM-trans-scripts
+----------------------
+
+* The :cpack_gen:`CPack RPM Generator` gained
+  :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE`
+  :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE`
+  variables to specify pre- and post-trans scripts.

Help/release/dev/FindPython-artifacts-interactive.rst

@@ -0,0 +1,6 @@
+FindPython-artifacts-interactive
+--------------------------------
+
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+  modules gained the possibility to create artifacts cache variables for
+  interactive edition.

Help/release/dev/FindPython-dev-subcomponents.rst

@@ -0,0 +1,6 @@
+FindPython-dev-subcomponents
+----------------------------
+
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+  modules gained sub-components ``Development.Module`` and
+  ``Development.Embed`` for ``Development`` component.

Help/release/dev/FindRuby-variable-case.rst

@@ -0,0 +1,7 @@
+FindRuby-variable-case
+----------------------
+
+* The :module:`FindRuby` module input and output variables were all renamed
+  from ``RUBY_`` to ``Ruby_`` for consistency with other find modules.
+  Input variables of the old case will be honored if provided, and output
+  variables of the old case are always provided.

Help/release/dev/GoogleTest-DISCOVERY_MODE.rst

@@ -0,0 +1,7 @@
+GoogleTest-DISCOVERY_MODE
+-------------------------
+
+* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
+  gained a new ``DISCOVERY_MODE`` option to control when the test
+  discovery step is run.  It offers a new ``PRE_TEST`` setting to
+  run the discovery at test time instead of build time.

Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst

@@ -0,0 +1,6 @@
+GoogleTest-XML_OUTPUT_DIR
+-------------------------
+
+* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
+  gained a new optional parameter ``XML_OUTPUT_DIR``. When set the JUnit XML
+  test results are stored in that directory.

Help/release/dev/cmake-gui-env-platform-defaults.rst

@@ -0,0 +1,8 @@
+cmake-gui-env-platform-defaults
+-------------------------------
+
+* :manual:`cmake-gui(1)` now populates its generator selection
+  widget default value from the :envvar:`CMAKE_GENERATOR` environment
+  variable.  Additionally, environment variables
+  :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET`
+  are used to populate their respective widget defaults.

Help/release/dev/cmake_command-command.rst

@@ -0,0 +1,6 @@
+cmake_command
+-------------
+
+* The :command:`cmake_command()` command was added for meta-operations on
+  scripted or built-in commands, starting with a mode to ``INVOKE`` other
+  commands, and ``EVAL CODE`` to inplace evaluate a CMake script.

Help/release/dev/command-line-cat.rst

@@ -0,0 +1,5 @@
+Command-Line
+------------
+* :manual:`cmake(1)` gained a ``cat`` command line
+  option that can be used to concatenate files and print them
+  on standard output.

Help/release/dev/ctest_resource_spec_file-variable.rst

@@ -0,0 +1,6 @@
+ctest_resource_spec_file-variable
+---------------------------------
+
+* :manual:`ctest(1)` gained a new :variable:`CTEST_RESOURCE_SPEC_FILE`
+  variable, which can be used to specify a
+  :ref:`resource specification file <ctest-resource-specification-file>`.

Help/release/dev/ctest_stop_on_failure.rst

@@ -0,0 +1,8 @@
+ctest_stop_on_failure
+---------------------
+
+* :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
+  which can be used to stop running the tests once one has failed.
+
+* The :command:`ctest_test` command gained a ``STOP_ON_FAILURE`` option
+  which can be used to stop running the tests once one has failed.

Help/release/dev/cuda-architectures-empty.rst

@@ -0,0 +1,7 @@
+cuda-architectures-empty
+------------------------
+
+* :variable:`CMAKE_CUDA_ARCHITECTURES` is now initialized when
+  :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
+  Empty :prop_tgt:`CUDA_ARCHITECTURES` raises an error. See policy
+  :policy:`CMP0104`.

Help/release/dev/cuda-architectures.rst

@@ -0,0 +1,6 @@
+cuda-architectures
+------------------
+
+* Added :prop_tgt:`CUDA_ARCHITECTURES` target property for specifying CUDA
+  output architectures. Users are encouraged to use this instead of specifying
+  options manually, as this approach is compiler-agnostic.

Help/release/dev/curl-http2.rst

@@ -0,0 +1,8 @@
+curl-http2
+----------
+
+* When building CMake itself from source and not using a system-provided
+  libcurl, HTTP/2 support is now enabled for commands supporting
+  network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`,
+  :command:`file(UPLOAD)`, and :command:`ctest_submit`.
+  The precompiled binaries provided on ``cmake.org`` now support HTTP/2.

Help/release/dev/deprecate-documentation-module.rst

@@ -0,0 +1,6 @@
+deprecate-documentation-module
+------------------------------
+
+* The :module:`Documentation` module has been deprecated via
+  :policy:`CMP0106`. This module was essentially VTK code that CMake should
+  not be shipping anymore.

Help/release/dev/deprecate-policy-old.rst

@@ -0,0 +1,8 @@
+deprecate-policy-old
+--------------------
+
+* An explicit deprecation diagnostic was added for policy ``CMP0070``
+  and policy ``CMP0071`` (``CMP0069`` 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.

Help/release/dev/device-link-options.rst

@@ -0,0 +1,5 @@
+device-link-options
+-------------------
+
+* the :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
+  properties are now used for the device link step. See policy :policy:`CMP0105`.

Help/release/dev/execute_process.rst

@@ -0,0 +1,5 @@
+execute_process
+---------------
+
+* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
+  and ``ECHO_ERROR_VARIABLE`` options.

Help/release/dev/export-multiple-calls.rst

@@ -0,0 +1,5 @@
+export-multiple-calls
+---------------------
+
+* The :command:`export` command now raise an error if used multiple times with
+  same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.

Help/release/dev/file-upload-tls.rst

@@ -0,0 +1,5 @@
+file-upload-tls
+---------------
+
+* The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO``
+  options to control server certificate verification.

Help/release/dev/file_archive.rst

@@ -0,0 +1,7 @@
+file_archive
+------------
+
+* The :command:`file` command gained the ``ARCHIVE_{CREATE|EXTRACT}`` subcommands.
+
+  These subcommands will replicate the :manual:`cmake(1)` ``-E tar`` functionality in
+  CMake scripting code.

Help/release/dev/file_configure.rst

@@ -0,0 +1,6 @@
+file_configure
+--------------
+
+* The :command:`file(CONFIGURE)` subcommand was created in order replicate the
+  :command:`configure_file` functionality without resorting to a pre-existing
+  file on disk as input. The content is instead passed as a string.

Help/release/dev/findswig-components.rst

@@ -0,0 +1,5 @@
+findswig-components
+-------------------
+
+* The :module:`FindSWIG` module now accepts target languages as  ``COMPONENTS``
+  and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``.

Help/release/dev/framework-multi-config-postfix.rst

@@ -0,0 +1,7 @@
+framework-multi-config-postfix
+------------------------------
+
+* The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property
+  and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
+  variable were created to allow adding a postfix to the name of a
+  framework file name when using a multi-config generator.

Help/release/dev/genex-DEVICE_LINK-HOST_LINK.rst

@@ -0,0 +1,6 @@
+genex-DEVICE_LINK-HOST_LINK
+---------------------------
+
+* To manage device and host link steps, the ``$<DEVICE_LINK:...>`` and
+  ``$<HOST_LINK:...>``
+  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.

Help/release/dev/genex-LINK_LANGUAGE.rst

@@ -0,0 +1,5 @@
+genex-LINK_LANGUAGE
+===================
+
+* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>``
+  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.

Help/release/dev/list_natural_sort.rst

@@ -0,0 +1,5 @@
+list_natural_sort
+-----------------
+
+* The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort
+  option to sort using natural order (see ``strverscmp(3)`` manual).

Help/release/dev/ninja-compiler-PATH-windows.rst

@@ -0,0 +1,7 @@
+ninja-compiler-PATH-windows
+---------------------------
+
+* On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config`
+  generators, when a compiler is not explicitly specified, now select
+  the first compiler (of any name) found in directories listed by the
+  ``PATH`` environment variable.

Help/release/dev/nsis-dpi-aware.rst

@@ -0,0 +1,6 @@
+nsis-dpi-aware
+--------------
+
+* The :cpack_gen:`CPack NSIS Generator` gained a new variable
+  :variable:`CPACK_NSIS_MANIFEST_DPI_AWARE` to declare that the
+  installer is DPI-aware.

Help/release/dev/parallel-lzma-compression.rst

@@ -0,0 +1,6 @@
+parallel-lzma-compression
+-------------------------
+
+* The :cpack_gen:`CPack Archive Generator`'s ``TXZ`` format learned the
+  :variable:`CPACK_ARCHIVE_THREADS` variable to enable parallel compression.
+  Requires support in the ``liblzma`` used by CMake.

Help/release/dev/pch-warn-invalid.rst

@@ -0,0 +1,6 @@
+pch-warn-invalid
+----------------
+
+* The :variable:`CMAKE_PCH_WARN_INVALID` variable was added to initialize the
+  :prop_tgt:`PCH_WARN_INVALID` target property to allow the removal of the
+  precompiled header invalid warning.

Help/release/dev/profiling.rst

@@ -0,0 +1,9 @@
+cmake-profiling
+---------------
+
+* Add support for profiling of CMake scripts through the parameters
+  ``--profiling-output`` and ``--profiling-format``. These options can
+  be used by users to gain insight into the performance of their scripts.
+
+  The first supported output format is ``google-trace`` which is a format
+  supported by Google Chrome's ``about:tracing`` tab.

Help/release/dev/required_find_commands.rst

@@ -0,0 +1,6 @@
+required_find_commands
+----------------------
+
+* The :command:`find_program`, :command:`find_library`, :command:`find_path`
+  and :command:`find_file` commands gained a new ``REQUIRED`` option that will
+  stop processing with an error message if nothing is found.

Help/release/dev/string-hex.rst

@@ -0,0 +1,5 @@
+string-hex
+----------
+
+* The :command:`string` command learned a new ``HEX`` sub-command, which
+  converts strings into their hexadecimal representation.

Help/release/dev/useswig-fortran.rst

@@ -0,0 +1,7 @@
+useswig-fortran
+---------------
+
+* The :module:`UseSWIG` module now supports Fortran as a target language if
+  the ``SWIG_EXECUTABLE`` is SWIG-Fortran_.
+
+.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig

Help/release/dev/vs-non-built-file-item-metadata.rst

@@ -0,0 +1,10 @@
+vs-non-built-file-item-metadata
+-------------------------------
+
+* The :prop_tgt:`VS_SOURCE_SETTINGS_<tool>` target property was added
+  to tell :ref:`Visual Studio Generators` for VS 2010 and above to add
+  metadata to non-built source files using ``<tool>``.
+
+* The :prop_sf:`VS_SETTINGS` source file property was added to tell
+  :ref:`Visual Studio Generators` for VS 2010 and above to add
+  metadata to a non-built source file.

Help/release/dev/vs-sln-deploy.rst

@@ -0,0 +1,6 @@
+vs-sln-deploy
+-------------
+
+* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell
+  :ref:`Visual Studio Generators` for VS 2010 and above to mark a
+  target for deployment even when not building for Windows Phone/Store/CE.

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
 ========
 

Help/variable/CMAKE_CUDA_ARCHITECTURES.rst

@@ -0,0 +1,17 @@
+CMAKE_CUDA_ARCHITECTURES
+------------------------
+
+Default value for :prop_tgt:`CUDA_ARCHITECTURES` property of targets.
+
+This is initialized as follows depending on :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>`:
+
+- For ``Clang``: the oldest architecture that works.
+
+- For ``NVIDIA``: the default architecture chosen by the compiler.
+  See policy :policy:`CMP0104`.
+
+Users are encouraged to override this, as the default varies across compilers
+and compiler versions.
+
+This variable is used to initialize the :prop_tgt:`CUDA_ARCHITECTURES` property
+on all targets. See the target property for additional information.

Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst

@@ -0,0 +1,8 @@
+CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
+---------------------------------------------
+
+Default framework filename postfix under configuration ``<CONFIG>`` when
+using a multi-config generator.
+
+When a framework target is created its :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
+target property is initialized with the value of this variable if it is set.

Help/variable/CMAKE_PCH_WARN_INVALID.rst

@@ -0,0 +1,5 @@
+CMAKE_PCH_WARN_INVALID
+----------------------
+
+This variable is used to initialize the :prop_tgt:`PCH_WARN_INVALID`
+property of targets when they are created.

Help/variable/CTEST_RESOURCE_SPEC_FILE.rst

@@ -0,0 +1,5 @@
+CTEST_RESOURCE_SPEC_FILE
+------------------------
+
+Specify the CTest ``ResourceSpecFile`` setting in a :manual:`ctest(1)`
+dashboard client script.

Modules/CMakeASMCompiler.cmake.in

@@ -10,7 +10,9 @@ set(CMAKE_ASM@ASM_DIALECT@_COMPILER_LOADED 1)
 set(CMAKE_ASM@ASM_DIALECT@_COMPILER_ID "@_CMAKE_ASM_COMPILER_ID@")
 set(CMAKE_ASM@ASM_DIALECT@_COMPILER_VERSION "@_CMAKE_ASM_COMPILER_VERSION@")
 set(CMAKE_ASM@ASM_DIALECT@_COMPILER_ENV_VAR "@_CMAKE_ASM_COMPILER_ENV_VAR@")
+@_SET_CMAKE_ASM_COMPILER_ID_VENDOR_MATCH@
 @_SET_CMAKE_ASM_COMPILER_ARCHITECTURE_ID@
+@_SET_CMAKE_ASM_COMPILER_SYSROOT@
 
 set(CMAKE_ASM@ASM_DIALECT@_IGNORE_EXTENSIONS h;H;o;O;obj;OBJ;def;DEF;rc;RC)
 set(CMAKE_ASM@ASM_DIALECT@_LINKER_PREFERENCE 0)

Modules/CMakeASMInformation.cmake

@@ -76,12 +76,12 @@ endif()
 if(NOT CMAKE_ASM${ASM_DIALECT}_CREATE_STATIC_LIBRARY)
   set(CMAKE_ASM${ASM_DIALECT}_CREATE_STATIC_LIBRARY
       "<CMAKE_AR> cr <TARGET> <LINK_FLAGS> <OBJECTS> "
-      "<CMAKE_RANLIB> <TARGET> ")
+      "<CMAKE_RANLIB> <TARGET>")
 endif()
 
 if(NOT CMAKE_ASM${ASM_DIALECT}_LINK_EXECUTABLE)
   set(CMAKE_ASM${ASM_DIALECT}_LINK_EXECUTABLE
-    "<CMAKE_ASM${ASM_DIALECT}_COMPILER> <FLAGS> <CMAKE_ASM${ASM_DIALECT}_LINK_FLAGS> <LINK_FLAGS> <OBJECTS>  -o <TARGET> <LINK_LIBRARIES>")
+    "<CMAKE_ASM${ASM_DIALECT}_COMPILER> <FLAGS> <CMAKE_ASM${ASM_DIALECT}_LINK_FLAGS> <LINK_FLAGS> <OBJECTS> -o <TARGET> <LINK_LIBRARIES>")
 endif()
 
 if(NOT CMAKE_EXECUTABLE_RUNTIME_ASM${ASM_DIALECT}_FLAG)

Modules/CMakeASM_MASMInformation.cmake

@@ -8,7 +8,7 @@ set(ASM_DIALECT "_MASM")
 
 set(CMAKE_ASM${ASM_DIALECT}_SOURCE_FILE_EXTENSIONS asm)
 
-set(CMAKE_ASM${ASM_DIALECT}_COMPILE_OBJECT "<CMAKE_ASM${ASM_DIALECT}_COMPILER> <DEFINES> <INCLUDES> <FLAGS> /c  /Fo <OBJECT> <SOURCE>")
+set(CMAKE_ASM${ASM_DIALECT}_COMPILE_OBJECT "<CMAKE_ASM${ASM_DIALECT}_COMPILER> <DEFINES> <INCLUDES> <FLAGS> /c /Fo <OBJECT> <SOURCE>")
 
 # The ASM_MASM compiler id for this compiler is "MSVC", so fill out the runtime library table.
 set(CMAKE_ASM${ASM_DIALECT}_COMPILE_OPTIONS_MSVC_RUNTIME_LIBRARY_MultiThreaded         "")

Modules/CMakeASM_NASMInformation.cmake

@@ -8,19 +8,25 @@ set(CMAKE_ASM_NASM_SOURCE_FILE_EXTENSIONS nasm asm)
 
 if(NOT CMAKE_ASM_NASM_OBJECT_FORMAT)
   if(WIN32)
-    if(CMAKE_C_SIZEOF_DATA_PTR EQUAL 8)
+    if(DEFINED CMAKE_C_SIZEOF_DATA_PTR AND CMAKE_C_SIZEOF_DATA_PTR EQUAL 8)
+      set(CMAKE_ASM_NASM_OBJECT_FORMAT win64)
+    elseif(DEFINED CMAKE_CXX_SIZEOF_DATA_PTR AND CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8)
       set(CMAKE_ASM_NASM_OBJECT_FORMAT win64)
     else()
       set(CMAKE_ASM_NASM_OBJECT_FORMAT win32)
     endif()
   elseif(APPLE)
-    if(CMAKE_C_SIZEOF_DATA_PTR EQUAL 8)
+    if(DEFINED CMAKE_C_SIZEOF_DATA_PTR AND CMAKE_C_SIZEOF_DATA_PTR EQUAL 8)
+      set(CMAKE_ASM_NASM_OBJECT_FORMAT macho64)
+    elseif(DEFINED CMAKE_CXX_SIZEOF_DATA_PTR AND CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8)
       set(CMAKE_ASM_NASM_OBJECT_FORMAT macho64)
     else()
       set(CMAKE_ASM_NASM_OBJECT_FORMAT macho)
     endif()
   else()
-    if(CMAKE_C_SIZEOF_DATA_PTR EQUAL 8)
+    if(DEFINED CMAKE_C_SIZEOF_DATA_PTR AND CMAKE_C_SIZEOF_DATA_PTR EQUAL 8)
+      set(CMAKE_ASM_NASM_OBJECT_FORMAT elf64)
+    elseif(DEFINED CMAKE_CXX_SIZEOF_DATA_PTR AND CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8)
       set(CMAKE_ASM_NASM_OBJECT_FORMAT elf64)
     else()
       set(CMAKE_ASM_NASM_OBJECT_FORMAT elf)

Modules/CMakeCCompiler.cmake.in

@@ -15,6 +15,7 @@ set(CMAKE_C_SIMULATE_ID "@CMAKE_C_SIMULATE_ID@")
 set(CMAKE_C_COMPILER_FRONTEND_VARIANT "@CMAKE_C_COMPILER_FRONTEND_VARIANT@")
 set(CMAKE_C_SIMULATE_VERSION "@CMAKE_C_SIMULATE_VERSION@")
 @_SET_CMAKE_C_COMPILER_ARCHITECTURE_ID@
+@_SET_CMAKE_C_COMPILER_SYSROOT@
 @SET_MSVC_C_ARCHITECTURE_ID@
 @SET_CMAKE_XCODE_ARCHS@
 set(CMAKE_AR "@CMAKE_AR@")