Update upstream source from tag 'upstream/3.11.1'

Update to upstream version '3.11.1'
with Debian dir 7cdc88d881

Auxiliary/bash-completion/cmake

@@ -96,7 +96,7 @@ _cmake()
             _filedir
             return
             ;;
-        --build)
+        --build|--open)
             _filedir -d
             return
             ;;

Auxiliary/cmake-mode.el

@@ -352,7 +352,7 @@ and store the result as a list in LISTVAR."
 
 ;;;###autoload
 (defun cmake-help ()
-  "Queries for any of the four available help topics and prints out the approriate page."
+  "Queries for any of the four available help topics and prints out the appropriate page."
   (interactive)
   (let* ((default-entry (cmake-symbol-at-point))
          (command-list (cmake-get-list "command"))

Auxiliary/vim/cmake.vim.in

@@ -1,4 +1,3 @@
-" vim: set nowrap:
 " Vim syntax file
 " Program:      CMake - Cross-Platform Makefile Generator
 " Version:      @VERSION@
@@ -8,6 +7,7 @@
 "               Patrick Boettcher <patrick.boettcher@posteo.de>
 " Maintainer:   Dimitri Merejkowsky <d.merej@gmail.com>
 " Former Maintainer: Karthik Krishnan <karthik.krishnan@kitware.com>
+" Last Change:  @DATE@
 "
 " Licence:      The CMake license applies to this file. See
 "               https://cmake.org/licensing
@@ -100,4 +100,4 @@ let b:current_syntax = "cmake"
 let &cpo = s:keepcpo
 unlet s:keepcpo
 
-"EOF"
+" vim: set nowrap:

Auxiliary/vim/extract-upper-case.pl

@@ -2,6 +2,7 @@
 
 use strict;
 use warnings;
+use POSIX qw(strftime);
 
 #my $cmake = "/home/pboettch/devel/upstream/cmake/build/bin/cmake";
 my $cmake = "cmake";
@@ -129,6 +130,10 @@ while(<IN>)
 		} elsif ($1 eq "VERSION") {
 			$_ =~ s/\@VERSION\@/$version/;
 			print OUT $_;
+		} elsif ($1 eq "DATE") {
+			my $date = strftime "%Y %b %d", localtime;
+			$_ =~ s/\@DATE\@/$date/;
+			print OUT $_;
 		} else {
 			print "ERROR do not know how to replace $1\n";
 		}

Auxiliary/vim/indent/cmake.vim

@@ -1,9 +1,9 @@
 " Vim indent file
 " Language:     CMake (ft=cmake)
 " Author:       Andy Cedilnik <andy.cedilnik@kitware.com>
-" Maintainer:   Karthik Krishnan <karthik.krishnan@kitware.com>
+" Maintainer:   Dimitri Merejkowsky <d.merej@gmail.com>
-" Last Change:  $Date$
+" Former Maintainer: Karthik Krishnan <karthik.krishnan@kitware.com>
-" Version:      $Revision$
+" Last Change:  2017 Aug 30
 "
 " Licence:      The CMake license applies to this file. See
 "               https://cmake.org/licensing
@@ -14,6 +14,9 @@ if exists("b:did_indent")
 endif
 let b:did_indent = 1
 
+let s:keepcpo= &cpo
+set cpo&vim
+
 setlocal indentexpr=CMakeGetIndent(v:lnum)
 setlocal indentkeys+==ENDIF(,ENDFOREACH(,ENDMACRO(,ELSE(,ELSEIF(,ENDWHILE(
 
@@ -64,20 +67,23 @@ fun! CMakeGetIndent(lnum)
     let ind = ind
   else
     if previous_line =~? cmake_indent_begin_regex
-      let ind = ind + &sw
+      let ind = ind + shiftwidth()
     endif
     if previous_line =~? cmake_indent_open_regex
-      let ind = ind + &sw
+      let ind = ind + shiftwidth()
     endif
   endif
 
   " Subtract
   if this_line =~? cmake_indent_end_regex
-    let ind = ind - &sw
+    let ind = ind - shiftwidth()
   endif
   if previous_line =~? cmake_indent_close_regex
-    let ind = ind - &sw
+    let ind = ind - shiftwidth()
   endif
 
   return ind
 endfun
+
+let &cpo = s:keepcpo
+unlet s:keepcpo

CMakeLists.txt

@@ -2,7 +2,11 @@
 # file Copyright.txt or https://cmake.org/licensing for details.
 
 cmake_minimum_required(VERSION 3.1 FATAL_ERROR)
+set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
+set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
 project(CMake)
+unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX)
+unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
 
 # Make sure we can find internal find_package modules only used for
 # building CMake and not for shipping externally
@@ -60,14 +64,23 @@ if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
   if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
     set(CMAKE_CXX_STANDARD 98)
   else()
-    include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx14_cstdio.cmake)
+    if(NOT CMAKE_VERSION VERSION_LESS 3.8)
-    if(NOT CMake_CXX14_CSTDIO_BROKEN)
+      include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx17_check.cmake)
+    else()
+      set(CMake_CXX17_BROKEN 1)
+    endif()
+    if(NOT CMake_CXX17_BROKEN)
+      set(CMAKE_CXX_STANDARD 17)
+    else()
+      include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx14_check.cmake)
+      if(NOT CMake_CXX14_BROKEN)
         set(CMAKE_CXX_STANDARD 14)
       else()
         set(CMAKE_CXX_STANDARD 11)
       endif()
     endif()
   endif()
+endif()
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
   # include special compile flags for some compilers
   include(CompileFlags.cmake)
@@ -251,7 +264,12 @@ if(CMake_RUN_CLANG_TIDY)
   endif()
   set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_COMMAND}")
 
-  # provide definitions for targets that require a rebuild once .clang-tidy changes
+  # Create a preprocessor definition that depends on .clang-tidy content so
+  # the compile command will change when .clang-tidy changes.  This ensures
+  # that a subsequent build re-runs clang-tidy on all sources even if they
+  # do not otherwise need to be recompiled.  Nothing actually uses this
+  # definition.  We add it to targets on which we run clang-tidy just to
+  # get the build dependency on the .clang-tidy file.
   file(SHA1 ${CMAKE_CURRENT_SOURCE_DIR}/.clang-tidy clang_tidy_sha1)
   set(CLANG_TIDY_DEFINITIONS "CLANG_TIDY_SHA1=${clang_tidy_sha1}")
   unset(clang_tidy_sha1)
@@ -267,7 +285,7 @@ if(CMake_RUN_IWYU)
     message(FATAL_ERROR "CMake_RUN_IWYU is ON but include-what-you-use is not found!")
   endif()
   set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
-    "${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp")
+    "${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w")
 endif()
 
 
@@ -292,6 +310,8 @@ endmacro()
 # Simply to improve readability of the main script.
 #-----------------------------------------------------------------------
 macro (CMAKE_BUILD_UTILITIES)
+  find_package(Threads)
+
   #---------------------------------------------------------------------
   # Create the kwsys library for CMake.
   set(KWSYS_NAMESPACE cmsys)
@@ -526,7 +546,7 @@ macro (CMAKE_BUILD_UTILITIES)
   #---------------------------------------------------------------------
   # Build libuv library.
   if(CMAKE_USE_SYSTEM_LIBUV)
-    find_package(LibUV 1.0.0)
+    find_package(LibUV 1.10.0)
     if(NOT LIBUV_FOUND)
       message(FATAL_ERROR
         "CMAKE_USE_SYSTEM_LIBUV is ON but a libuv is not found!")

CTestCustom.cmake.in

@@ -102,12 +102,6 @@ if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")
     )
 endif ()
 
-if(NOT "@CMAKE_GENERATOR@" MATCHES "KDevelop")
-  list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
-    "Kdevelop"
-    )
-endif ()
-
 list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
   # Exclude kwsys files from coverage results. They are reported
   # (with better coverage results) on kwsys dashboards...

CompileFlags.cmake

@@ -17,6 +17,10 @@ if(MSVC OR _INTEL_WINDOWS)
 else()
 endif()
 
+if(MSVC)
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -stack:10000000")
+endif()
+
 #silence duplicate symbol warnings on AIX
 if(CMAKE_SYSTEM_NAME MATCHES "AIX")
   if(NOT CMAKE_COMPILER_IS_GNUCXX)

Copyright.txt

@@ -1,5 +1,5 @@
 CMake - Cross Platform Makefile Generator
-Copyright 2000-2017 Kitware, Inc. and Contributors
+Copyright 2000-2018 Kitware, Inc. and Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

Help/command/add_custom_command.rst

@@ -146,8 +146,10 @@ The options are:
   Specify the primary input source file to the command.  This is
   treated just like any value given to the ``DEPENDS`` option
   but also suggests to Visual Studio generators where to hang
-  the custom command.  At most one custom command may specify a
+  the custom command. Each source file may have at most one command
-  given source file as its main dependency.
+  specifying it as its main dependency. A compile command (i.e. for a
+  library or an executable) counts as an implicit main dependency which
+  gets silently overwritten by a custom command specification.
 
 ``OUTPUT``
   Specify the output files the command is expected to produce.

Help/command/add_executable.rst

@@ -7,14 +7,15 @@ Add an executable to the project using the specified source files.
 
   add_executable(<name> [WIN32] [MACOSX_BUNDLE]
                  [EXCLUDE_FROM_ALL]
-                 source1 [source2 ...])
+                 [source1] [source2 ...])
 
 Adds an executable target called ``<name>`` to be built from the source
-files listed in the command invocation.  The ``<name>`` corresponds to the
+files listed in the command invocation.  (The source files can be omitted
-logical target name and must be globally unique within a project.  The
+here if they are added later using :command:`target_sources`.)  The
-actual file name of the executable built is constructed based on
+``<name>`` corresponds to the logical target name and must be globally
-conventions of the native platform (such as ``<name>.exe`` or just
+unique within a project.  The actual file name of the executable built is
-``<name>``).
+constructed based on conventions of the native platform (such as
+``<name>.exe`` or just ``<name>``).
 
 By default the executable file will be created in the build tree
 directory corresponding to the source tree directory in which the
@@ -73,8 +74,9 @@ properties for more information.
 Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
 be used to refer to ``<target>`` in subsequent commands.  The ``<name>``
 does not appear in the generated buildsystem as a make target.  The
-``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an
+``<target>`` may not be a non-``GLOBAL``
-``ALIAS``.  ``ALIAS`` targets can be used as targets to read properties
+:ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
+``ALIAS`` targets can be used as targets to read properties
 from, executables for custom commands and custom targets.  They can also be
 tested for existence with the regular :command:`if(TARGET)` subcommand.
 The ``<name>`` may not be used to modify properties of ``<target>``, that

Help/command/add_library.rst

@@ -14,13 +14,14 @@ Normal Libraries
 
   add_library(<name> [STATIC | SHARED | MODULE]
               [EXCLUDE_FROM_ALL]
-              source1 [source2 ...])
+              [source1] [source2 ...])
 
 Adds a library target called ``<name>`` to be built from the source files
-listed in the command invocation.  The ``<name>`` corresponds to the
+listed in the command invocation.  (The source files can be omitted here
-logical target name and must be globally unique within a project.  The
+if they are added later using :command:`target_sources`.)  The ``<name>``
-actual file name of the library built is constructed based on
+corresponds to the logical target name and must be globally unique within
-conventions of the native platform (such as ``lib<name>.a`` or
+a project.  The actual file name of the library built is constructed based
+on conventions of the native platform (such as ``lib<name>.a`` or
 ``<name>.lib``).
 
 ``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
@@ -110,9 +111,9 @@ may contain only sources that compile, header files, and other files
 that would not affect linking of a normal library (e.g. ``.txt``).
 They may contain custom commands generating such sources, but not
 ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands.  Object libraries
-cannot be linked.  Some native build systems may not like targets that
+cannot be linked.  Some native build systems (such as Xcode) may not like
-have only object files, so consider adding at least one real source file
+targets that have only object files, so consider adding at least one real
-to any target that references ``$<TARGET_OBJECTS:objlib>``.
+source file to any target that references ``$<TARGET_OBJECTS:objlib>``.
 
 Alias Libraries
 ^^^^^^^^^^^^^^^
@@ -124,7 +125,8 @@ Alias Libraries
 Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
 used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
 not appear in the generated buildsystem as a make target.  The ``<target>``
-may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
+may not be a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an
+``ALIAS``.
 ``ALIAS`` targets can be used as linkable targets and as targets to
 read properties from.  They can also be tested for existence with the
 regular :command:`if(TARGET)` subcommand.  The ``<name>`` may not be used

Help/command/add_subdirectory.rst

@@ -30,7 +30,7 @@ project that is useful but not necessary, such as a set of examples.
 Typically the subdirectory should contain its own :command:`project`
 command invocation so that a full build system will be generated in the
 subdirectory (such as a VS IDE solution file).  Note that inter-target
-dependencies supercede this exclusion.  If a target built by the
+dependencies supersede this exclusion.  If a target built by the
 parent project depends on a target in the subdirectory, the dependee
 target will be included in the parent project build system to satisfy
 the dependency.

Help/command/cmake_parse_arguments.rst

@@ -62,7 +62,7 @@ as the real :command:`install` command:
 
 .. code-block:: cmake
 
-   function(MY_INSTALL)
+   macro(my_install)
        set(options OPTIONAL FAST)
        set(oneValueArgs DESTINATION RENAME)
        set(multiValueArgs TARGETS CONFIGURATIONS)

Help/command/enable_language.rst

@@ -10,7 +10,10 @@ Enable a language (CXX/C/Fortran/etc)
 This command enables support for the named language in CMake.  This is
 the same as the project command but does not create any of the extra
 variables that are created by the project command.  Example languages
-are CXX, C, Fortran.
+are ``CXX``, ``C``, ``CUDA``, ``Fortran``, and ``ASM``.
+
+If enabling ``ASM``, enable it last so that CMake can check whether
+compilers for other languages like ``C`` work for assembly too.
 
 This command must be called in file scope, not in a function call.
 Furthermore, it must be called in the highest directory common to all
@@ -19,4 +22,5 @@ indirectly through link dependencies.  It is simplest to enable all
 needed languages in the top-level directory of a project.
 
 The ``OPTIONAL`` keyword is a placeholder for future implementation and
-does not currently work.
+does not currently work. Instead you can use the :module:`CheckLanguage`
+module to verify support before enabling.

Help/command/execute_process.rst

@@ -90,8 +90,10 @@ Options:
    Use the ANSI codepage.
  ``OEM``
    Use the original equipment manufacturer (OEM) code page.
- ``UTF8``
+ ``UTF8`` or ``UTF-8``
-   Use the UTF-8 codepage.
+   Use the UTF-8 codepage. Prior to CMake 3.11.0, only ``UTF8`` was accepted
+   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.
 
 If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
 same pipe the precedence is not specified.

Help/command/file.rst

@@ -110,7 +110,7 @@ regular expressions, but much simpler.  If ``RELATIVE`` flag is
 specified, the results will be returned as relative paths to the given
 path.  The results will be ordered lexicographically.
 
-By default ``GLOB`` lists directories - directories are omited in result if
+By default ``GLOB`` lists directories - directories are omitted in result if
 ``LIST_DIRECTORIES`` is set to false.
 
 .. note::
@@ -232,6 +232,31 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 ``HTTPHEADER <HTTP-header>``
   HTTP header for operation. Suboption can be repeated several times.
 
+``NETRC <level>``
+  Specify whether the .netrc file is to be used for operation.  If this
+  option is not specified, the value of the ``CMAKE_NETRC`` variable
+  will be used instead.
+  Valid levels are:
+
+  ``IGNORED``
+    The .netrc file is ignored.
+    This is the default.
+  ``OPTIONAL``
+    The .netrc file is optional, and information in the URL is preferred.
+    The file will be scanned to find which ever information is not specified
+    in the URL.
+  ``REQUIRED``
+    The .netrc file is required, and information in the URL is ignored.
+
+``NETRC_FILE <file>``
+  Specify an alternative .netrc file to the one in your home directory,
+  if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
+  is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will
+  be used instead.
+
+If neither ``NETRC`` option is given CMake will check variables
+``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively.
+
 Additional options to ``DOWNLOAD`` are:
 
 ``EXPECTED_HASH ALGO=<value>``

Help/command/find_package.rst

@@ -176,7 +176,7 @@ claim compatibility with the version requested it is unspecified which
 one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
 is set no attempt is made to choose a highest or closest version number.
 
-To control the order in which ``find_package`` checks for compatibiliy use
+To control the order in which ``find_package`` checks for compatibility use
 the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
 :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
 For instance in order to select the highest version one can set::

Help/command/foreach.rst

@@ -26,14 +26,14 @@ list.
 Foreach can also iterate over a generated range of numbers.  There are
 three types of this iteration:
 
-* When specifying single number, the range will have elements 0 to
+* When specifying single number, the range will have elements [0, ... to
-  "total".
+  "total"] (inclusive).
 
 * When specifying two numbers, the range will have elements from the
-  first number to the second number.
+  first number to the second number (inclusive).
 
 * The third optional number is the increment used to iterate from the
-  first number to the second number.
+  first number to the second number (inclusive).
 
 ::
 

Help/command/install.rst

@@ -38,7 +38,21 @@ signatures that specify them.  The common options are:
 
 ``CONFIGURATIONS``
   Specify a list of build configurations for which the install rule
-  applies (Debug, Release, etc.).
+  applies (Debug, Release, etc.). Note that the values specified for
+  this option only apply to options listed AFTER the ``CONFIGURATIONS``
+  option. For example, to set separate install paths for the Debug and
+  Release configurations, do the following:
+
+  .. code-block:: cmake
+
+    install(TARGETS target
+            CONFIGURATIONS Debug
+            RUNTIME DESTINATION Debug/bin)
+    install(TARGETS target
+            CONFIGURATIONS Release
+            RUNTIME DESTINATION Release/bin)
+
+  Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``.
 
 ``COMPONENT``
   Specify an installation component name with which the install rule
@@ -346,8 +360,8 @@ specified that does not match that given to the targets associated with
 included in the export but a target to which it links is not included
 the behavior is unspecified.
 
-In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe
+In addition to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe
-used to specifiy an export to the android ndk build system.  The Android
+used to specify an export to the android ndk build system.  The Android
 NDK supports the use of prebuilt libraries, both static and shared. This
 allows cmake to build the libraries of a project and make them available
 to an ndk build system complete with transitive dependencies, include flags

Help/command/project.rst

@@ -46,11 +46,15 @@ variable will be set to its argument. The argument must be a string with short
 description of the project (only a few words).
 
 Optionally you can specify which languages your project supports.
-Example languages are ``C``, ``CXX`` (i.e.  C++), ``Fortran``, etc.
+Example languages include ``C``, ``CXX`` (i.e.  C++), ``CUDA``,
+``Fortran``, and ``ASM``.
 By default ``C`` and ``CXX`` are enabled if no language options are
 given.  Specify language ``NONE``, or use the ``LANGUAGES`` keyword
 and list no languages, to skip enabling any languages.
 
+If enabling ``ASM``, list it last so that CMake can check whether
+compilers for other languages like ``C`` work for assembly too.
+
 If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`,
 the file pointed to by that variable will be included as the last step of the
 project command.

Help/command/target_compile_definitions.rst

@@ -12,14 +12,15 @@ Add compile definitions to a target.
 Specify compile definitions to use when compiling a given ``<target>``.  The
 named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
-:ref:`Imported Target <Imported Targets>`.
+:ref:`ALIAS target <Alias Targets>`.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
 items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of
 ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
-:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``.  The
+:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``.
-following arguments specify compile definitions.  Repeated calls for the
+(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
+The following arguments specify compile definitions.  Repeated calls for the
 same ``<target>`` append items in the order called.
 
 Arguments to ``target_compile_definitions`` may use "generator expressions"

Help/command/target_compile_features.rst

@@ -18,12 +18,13 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the scope of the features.  ``PRIVATE`` and ``PUBLIC`` items will
 populate the :prop_tgt:`COMPILE_FEATURES` property of ``<target>``.
 ``PUBLIC`` and ``INTERFACE`` items will populate the
-:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``.  Repeated
+:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``.
-calls for the same ``<target>`` append items.
+(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
+Repeated calls for the same ``<target>`` append items.
 
 The named ``<target>`` must have been created by a command such as
-:command:`add_executable` or :command:`add_library` and must not be
+:command:`add_executable` or :command:`add_library` and must not be an
-an ``IMPORTED`` target.
+:ref:`ALIAS target <Alias Targets>`.
 
 Arguments to ``target_compile_features`` may use "generator expressions"
 with the syntax ``$<...>``.

Help/command/target_compile_options.rst

@@ -12,8 +12,10 @@ Add compile options to a target.
 Specify compile options to use when compiling a given target.  The
 named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
-:ref:`IMPORTED Target <Imported Targets>`.  If ``BEFORE`` is specified,
+:ref:`ALIAS target <Alias Targets>`.
-the content will be prepended to the property instead of being appended.
+
+If ``BEFORE`` is specified, the content will be prepended to the property
+instead of being appended.
 
 This command can be used to add any options, but
 alternative commands exist to add preprocessor definitions
@@ -27,8 +29,9 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
 items will populate the :prop_tgt:`COMPILE_OPTIONS` property of
 ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
-:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``.  The
+:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``.
-following arguments specify compile options.  Repeated calls for the same
+(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
+The following arguments specify compile options.  Repeated calls for the same
 ``<target>`` append items in the order called.
 
 Arguments to ``target_compile_options`` may use "generator expressions"

Help/command/target_include_directories.rst

@@ -12,7 +12,7 @@ Add include directories to a target.
 Specify include directories to use when compiling a given target.
 The named ``<target>`` must have been created by a command such
 as :command:`add_executable` or :command:`add_library` and must not be an
-:prop_tgt:`IMPORTED` target.
+:ref:`ALIAS target <Alias Targets>`.
 
 If ``BEFORE`` is specified, the content will be prepended to the property
 instead of being appended.
@@ -21,9 +21,9 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
 the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC`` items will
 populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``.
 ``PUBLIC`` and ``INTERFACE`` items will populate the
-:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.
-property of ``<target>``.  The following arguments specify include
+(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
-directories.
+The following arguments specify include directories.
 
 Specified include directories may be absolute paths or relative paths.
 Repeated calls for the same <target> append items in the order called.  If

Help/command/target_link_libraries.rst

@@ -19,7 +19,8 @@ All of them have the general form::
   target_link_libraries(<target> ... <item>... ...)
 
 The named ``<target>`` must have been created in the current directory by
-a command such as :command:`add_executable` or :command:`add_library`.
+a command such as :command:`add_executable` or :command:`add_library` and
+must not be an :ref:`ALIAS target <Alias Targets>`.
 Repeated calls for the same ``<target>`` append items in the order called.
 Each ``<item>`` may be:
 

Help/command/target_sources.rst

@@ -12,14 +12,15 @@ Add sources to a target.
 Specify sources to use when compiling a given target.  The
 named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
-:ref:`IMPORTED Target <Imported Targets>`.
+:ref:`ALIAS target <Alias Targets>`.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
 items will populate the :prop_tgt:`SOURCES` property of
 ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
-:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``.  The
+:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``.
-following arguments specify sources.  Repeated calls for the same
+(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.)
+The following arguments specify sources.  Repeated calls for the same
 ``<target>`` append items in the order called.
 
 Arguments to ``target_sources`` may use "generator expressions"

Help/dev/maint.rst

@@ -73,6 +73,13 @@ Merge the ``release-$ver`` branch to ``master``:
   git pull
   git merge --no-ff release-$ver
 
+Review new ancestry to ensure nothing unexpected was merged to either branch:
+
+.. code-block:: shell
+
+  git log --graph --boundary origin/master..master
+  git log --graph --boundary origin/release..release-$ver
+
 Publish both ``master`` and ``release`` simultaneously:
 
 .. code-block:: shell

Help/dev/testing.rst

@@ -16,7 +16,7 @@ welcome to provide testing machines in order to help keep support for their
 platforms working.
 
 The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
-nightly, continous, and experimental testing of CMake.  Use the following
+nightly, continuous, and experimental testing of CMake.  Use the following
 commands to set up a new integration testing client:
 
 .. code-block:: console

Help/generator/KDevelop3.rst

@@ -1,25 +0,0 @@
-KDevelop3
----------
-
-Generates KDevelop 3 project files.
-
-Project files for KDevelop 3 will be created in the top directory and
-in every subdirectory which features a CMakeLists.txt file containing
-a PROJECT() call.  If you change the settings using KDevelop cmake
-will try its best to keep your changes when regenerating the project
-files.  Additionally a hierarchy of UNIX makefiles is generated into
-the build tree.  Any standard UNIX-style make program can build the
-project through the default make target.  A "make install" target is
-also provided.
-
-This "extra" generator may be specified as:
-
-``KDevelop3 - Unix Makefiles``
- Generate with :generator:`Unix Makefiles`.
-
-``KDevelop3``
- Generate with :generator:`Unix Makefiles`.
-
- For historical reasons this extra generator may be specified
- directly as the main generator and it will be used as the
- extra generator with :generator:`Unix Makefiles` automatically.

Help/generator/Visual Studio 15 2017.rst

@@ -19,13 +19,17 @@ Instance Selection
 ^^^^^^^^^^^^^^^^^^
 
 VS 2017 supports multiple installations on the same machine.
-CMake queries the Visual Studio Installer to locate VS instances.
+The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
-If more than one instance is installed we do not define which one
+cache entry containing the absolute path to a Visual Studio instance.
-is chosen by default.  If the ``VS150COMNTOOLS`` environment variable
+If the value is not specified explicitly by the user or a toolchain file,
-is set and points to the ``Common7/Tools`` directory within one of
+CMake queries the Visual Studio Installer to locate VS instances, chooses
-the instances, that instance will be used.  The environment variable
+one, and sets the variable as a cache entry to hold the value persistently.
-must remain consistently set whenever CMake is re-run within a given
+
-build tree.
+When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment
+variable is set and points to the ``Common7/Tools`` directory within
+one of the instances, that instance will be used.  Otherwise, if more
+than one instance is installed we do not define which one is chosen
+by default.
 
 Toolset Selection
 ^^^^^^^^^^^^^^^^^

Help/manual/cmake-buildsystem.7.rst

@@ -831,12 +831,11 @@ Imported Targets
 
 An :prop_tgt:`IMPORTED` target represents a pre-existing dependency.  Usually
 such targets are defined by an upstream package and should be treated as
-immutable.  It is not possible to use an :prop_tgt:`IMPORTED` target in the
+immutable. After declaring an :prop_tgt:`IMPORTED` target one can adjust its
-left-hand-side of the :command:`target_compile_definitions`,
+target properties by using the customary commands such as
-:command:`target_include_directories`, :command:`target_compile_options` or
+:command:`target_compile_definitions`, :command:`target_include_directories`,
-:command:`target_link_libraries` commands, as that would be an attempt to
+:command:`target_compile_options` or :command:`target_link_libraries` just like
-modify it.  :prop_tgt:`IMPORTED` targets are designed to be used only in the
+with any other regular target.
-right-hand-side of those commands.
 
 :prop_tgt:`IMPORTED` targets may have the same usage requirement properties
 populated as binary targets, such as

Help/manual/cmake-compile-features.7.rst

@@ -335,7 +335,7 @@ versions specified for each:
 * ``Clang``: Clang compiler versions 2.9 through 3.4.
 * ``GNU``: GNU compiler versions 4.4 through 5.0.
 * ``MSVC``: Microsoft Visual Studio versions 2010 through 2017.
-* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.5.
+* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.6.
 * ``Intel``: Intel compiler versions 12.1 through 17.0.
 
 CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>`

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

@@ -97,22 +97,38 @@ Available logical expressions are:
   compile features and a list of supported compilers.
 ``$<COMPILE_LANGUAGE:lang>``
   ``1`` when the language used for compilation unit matches ``lang``,
-  otherwise ``0``.  This expression used to specify compile options for
+  otherwise ``0``.  This expression may be used to specify compile options,
-  source files of a particular language in a target. For example, to specify
+  compile definitions, and include directories for source files of a
-  the use of the ``-fno-exceptions`` compile option (compiler id checks
+  particular language in a target. For example:
-  elided):
 
   .. code-block:: cmake
 
-    add_executable(myapp main.cpp foo.c bar.cpp)
+    add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
     target_compile_options(myapp
       PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
     )
+    target_compile_definitions(myapp
+      PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
+              $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
+    )
+    target_include_directories(myapp
+      PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>
+    )
 
-  This generator expression has limited use because it is not possible to
+  This specifies the use of the ``-fno-exceptions`` compile option,
-  use it with the Visual Studio generators.  Portable buildsystems would
+  ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include
-  not use this expression, and would create separate libraries for each
+  directory for C++ only (compiler id checks elided).  It also specifies
-  source file language instead:
+  a ``COMPILING_CUDA`` compile definition for CUDA.
+
+  Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there
+  is no way to represent target-wide compile definitions or include directories
+  separately for ``C`` and ``CXX`` languages.
+  Also, with :ref:`Visual Studio Generators` there is no way to represent
+  target-wide flags separately for ``C`` and ``CXX`` languages.  Under these
+  generators, expressions for both C and C++ sources will be evaluated
+  using ``CXX`` if there are any C++ sources and otherwise using ``C``.
+  A workaround is to create separate libraries for each source file language
+  instead:
 
   .. code-block:: cmake
 
@@ -122,20 +138,6 @@ Available logical expressions are:
     add_executable(myapp main.cpp)
     target_link_libraries(myapp myapp_c myapp_cxx)
 
-  The ``Makefile`` and ``Ninja`` based generators can also use this
-  expression to specify compile-language specific compile definitions
-  and include directories:
-
-  .. code-block:: cmake
-
-    add_executable(myapp main.cpp foo.c bar.cpp)
-    target_compile_definitions(myapp
-      PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
-    )
-    target_include_directories(myapp
-      PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>
-    )
-
 Informational Expressions
 =========================
 

Help/manual/cmake-generators.7.rst

@@ -108,6 +108,5 @@ The following extra generators are known to CMake.
    /generator/CodeBlocks
    /generator/CodeLite
    /generator/Eclipse CDT4
-   /generator/KDevelop3
    /generator/Kate
    /generator/Sublime Text 2

Help/manual/cmake-modules.7.rst

@@ -80,6 +80,7 @@ All Modules
    /module/ExternalData
    /module/ExternalProject
    /module/FeatureSummary
+   /module/FetchContent
    /module/FindALSA
    /module/FindArmadillo
    /module/FindASPELL
@@ -129,6 +130,7 @@ All Modules
    /module/FindIcotool
    /module/FindICU
    /module/FindImageMagick
+   /module/FindIconv
    /module/FindIntl
    /module/FindITK
    /module/FindJasper

Help/manual/cmake-policies.7.rst

@@ -51,6 +51,14 @@ 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.11
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072>
+
 Policies Introduced by CMake 3.10
 =================================
 

Help/manual/cmake-properties.7.rst

@@ -121,6 +121,7 @@ Properties on Targets
    /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG
    /prop_tgt/ARCHIVE_OUTPUT_NAME
    /prop_tgt/AUTOGEN_BUILD_DIR
+   /prop_tgt/AUTOGEN_PARALLEL
    /prop_tgt/AUTOGEN_TARGET_DEPENDS
    /prop_tgt/AUTOMOC_COMPILER_PREDEFINES
    /prop_tgt/AUTOMOC_DEPEND_FILTERS
@@ -184,6 +185,7 @@ Properties on Targets
    /prop_tgt/HAS_CXX
    /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
    /prop_tgt/IMPORTED_CONFIGURATIONS
+   /prop_tgt/IMPORTED_GLOBAL
    /prop_tgt/IMPORTED_IMPLIB_CONFIG
    /prop_tgt/IMPORTED_IMPLIB
    /prop_tgt/IMPORTED_LIBNAME_CONFIG
@@ -368,10 +370,12 @@ Properties on Source Files
    /prop_sf/AUTORCC_OPTIONS
    /prop_sf/COMPILE_DEFINITIONS
    /prop_sf/COMPILE_FLAGS
+   /prop_sf/COMPILE_OPTIONS
    /prop_sf/EXTERNAL_OBJECT
    /prop_sf/Fortran_FORMAT
    /prop_sf/GENERATED
    /prop_sf/HEADER_FILE_ONLY
+   /prop_sf/INCLUDE_DIRECTORIES
    /prop_sf/KEEP_EXTENSION
    /prop_sf/LABELS
    /prop_sf/LANGUAGE
@@ -390,6 +394,8 @@ Properties on Source Files
    /prop_sf/VS_DEPLOYMENT_LOCATION
    /prop_sf/VS_INCLUDE_IN_VSIX
    /prop_sf/VS_RESOURCE_GENERATOR
+   /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS
+   /prop_sf/VS_SHADER_ENABLE_DEBUG
    /prop_sf/VS_SHADER_ENTRYPOINT
    /prop_sf/VS_SHADER_FLAGS
    /prop_sf/VS_SHADER_MODEL

Help/manual/cmake-qt.7.rst

@@ -96,7 +96,8 @@ following targets by setting the :variable:`CMAKE_AUTOMOC` variable.  The
 options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS`
 variable may be populated to pre-set the options for all following targets.
 
-Additional macro names to search for can be added to :prop_tgt:`AUTOMOC_MACRO_NAMES`.
+Additional macro names to search for can be added to
+:prop_tgt:`AUTOMOC_MACRO_NAMES`.
 
 Additional ``moc`` dependency file names can be extracted from source code
 by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
@@ -216,19 +217,16 @@ enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 Visual Studio Generators
 ========================
 
-When using the :manual:`Visual Studio generators <cmake-generators(7)>`
+When using the :manual:`Visual Studio generators <cmake-generators(7)>`,
-CMake tries to use a ``PRE_BUILD``
+CMake uses a ``PRE_BUILD`` :command:`custom command <add_custom_command>` for
-:command:`custom command <add_custom_command>` instead
+:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
-of a :command:`custom target <add_custom_target>` for autogen.
+If the :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing depends on files,
-``PRE_BUILD`` can't be used when the autogen target depends on files.
+a :command:`custom target <add_custom_target>` is used instead.
 This happens when
 
-- :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` is enabled and the origin target
+- The origin target depends on :prop_sf:`GENERATED` files which aren't excluded
-  depends on :prop_sf:`GENERATED` files which aren't excluded from autogen by
+  from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by :prop_sf:`SKIP_AUTOMOC`,
-  :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN`
+  :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071`
-  or :policy:`CMP0071`
-- :prop_tgt:`AUTORCC` is enabled and a ``.qrc`` file is listed in
-  the origin target sources
 - :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file
 
 qtmain.lib on Windows

Help/manual/cmake-server.7.rst

@@ -162,7 +162,7 @@ When the server is busy for a long time, it is polite to send back replies of
 type "progress" to the client. These will contain a "progressMessage" with a
 string describing the action currently taking place as well as
 "progressMinimum", "progressMaximum" and "progressCurrent" with integer values
-describing the range of progess.
+describing the range of progress.
 
 Messages of type "progress" will be followed by more "progress" messages or with
 a message of type "reply" or "error" that complete the request.
@@ -277,10 +277,6 @@ Giving the "major" version of the requested protocol version will make the serve
 use the latest minor version of that protocol. Use this if you do not explicitly
 need to depend on a specific minor version.
 
-If the build directory already contains a CMake cache, it is sufficient to set
-the "buildDirectory" attribute. To create a fresh build directory, additional
-attributes are required depending on the protocol version.
-
 Protocol version 1.0 requires the following attributes to be set:
 
   * "sourceDirectory" with a path to the sources
@@ -290,6 +286,10 @@ Protocol version 1.0 requires the following attributes to be set:
   * "platform" with the generator platform (if supported by the generator)
   * "toolset" with the generator toolset (if supported by the generator)
 
+Protocol version 1.2 makes all but the build directory optional, provided
+there is a valid cache in the build directory that contains all the other
+information already.
+
 Example::
 
   [== "CMake Server" ==[
@@ -458,6 +458,11 @@ Each project object can have the following keys:
 
 "name"
   contains the (sub-)projects name.
+"minimumCMakeVersion"
+  contains the minimum cmake version allowed for this project, null if the
+  project doesn't specify one.
+"hasInstallRule"
+  true if the project contains any install rules, false otherwise.
 "sourceDirectory"
   contains the current source directory
 "buildDirectory"
@@ -481,6 +486,12 @@ Each target object can have the following keys:
   contains the current source directory.
 "buildDirectory"
   contains the current build directory.
+"isGeneratorProvided"
+  true if the target is auto-created by a generator, false otherwise
+"hasInstallRule"
+  true if the target contains any install rules, false otherwise.
+"installPaths"
+  full path to the destination directories defined by target install rules.
 "artifacts"
   with a list of build artifacts. The list is sorted with the most
   important artifacts first (e.g. a .DLL file is listed before a
@@ -582,6 +593,51 @@ CMake will reply::
   ]== "CMake Server" ==]
 
 
+Type "ctestInfo"
+^^^^^^^^^^^^^^^^
+
+The "ctestInfo" request can be used after a project was "compute"d successfully.
+
+It will list the complete project test structure as it is known to cmake.
+
+The reply will contain a key "configurations", which will contain a list of
+configuration objects. Configuration objects are used to destinquish between
+different configurations the build directory might have enabled. While most
+generators only support one configuration, others might support several.
+
+Each configuration object can have the following keys:
+
+"name"
+  contains the name of the configuration. The name may be empty.
+"projects"
+  contains a list of project objects, one for each build project.
+
+Project objects define one (sub-)project defined in the cmake build system.
+
+Each project object can have the following keys:
+
+"name"
+  contains the (sub-)projects name.
+"ctestInfo"
+  contains a list of test objects.
+
+Each test object can have the following keys:
+
+"ctestName"
+  contains the name of the test.
+"ctestCommand"
+  contains the test command.
+"properties"
+  contains a list of test property objects.
+
+Each test property object can have the following keys:
+
+"key"
+  contains the test property key.
+"value"
+  contains the test property value.
+
+
 Type "cmakeInputs"
 ^^^^^^^^^^^^^^^^^^
 

Help/manual/cmake-variables.7.rst

@@ -42,6 +42,7 @@ Variables that Provide Information
    /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION
    /variable/CMAKE_FIND_PACKAGE_SORT_ORDER
    /variable/CMAKE_GENERATOR
+   /variable/CMAKE_GENERATOR_INSTANCE
    /variable/CMAKE_GENERATOR_PLATFORM
    /variable/CMAKE_GENERATOR_TOOLSET
    /variable/CMAKE_HOME_DIRECTORY
@@ -49,6 +50,7 @@ Variables that Provide Information
    /variable/CMAKE_IMPORT_LIBRARY_SUFFIX
    /variable/CMAKE_JOB_POOL_COMPILE
    /variable/CMAKE_JOB_POOL_LINK
+   /variable/CMAKE_JOB_POOLS
    /variable/CMAKE_LANG_COMPILER_AR
    /variable/CMAKE_LANG_COMPILER_RANLIB
    /variable/CMAKE_LINK_LIBRARY_SUFFIX
@@ -60,6 +62,8 @@ Variables that Provide Information
    /variable/CMAKE_MATCH_n
    /variable/CMAKE_MINIMUM_REQUIRED_VERSION
    /variable/CMAKE_MINOR_VERSION
+   /variable/CMAKE_NETRC
+   /variable/CMAKE_NETRC_FILE
    /variable/CMAKE_PARENT_LIST_FILE
    /variable/CMAKE_PATCH_VERSION
    /variable/CMAKE_PROJECT_DESCRIPTION
@@ -121,6 +125,7 @@ Variables that Change Behavior
    /variable/CMAKE_AUTOMOC_RELAXED_MODE
    /variable/CMAKE_BACKWARDS_COMPATIBILITY
    /variable/CMAKE_BUILD_TYPE
+   /variable/CMAKE_CODEBLOCKS_COMPILER_ID
    /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
    /variable/CMAKE_CODELITE_USE_TARGETS
    /variable/CMAKE_COLOR_MAKEFILE
@@ -156,6 +161,7 @@ Variables that Change Behavior
    /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
    /variable/CMAKE_INCLUDE_PATH
    /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
+   /variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
    /variable/CMAKE_INSTALL_MESSAGE
    /variable/CMAKE_INSTALL_PREFIX
    /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
@@ -185,6 +191,7 @@ Variables that Change Behavior
    /variable/CMAKE_USER_MAKE_RULES_OVERRIDE
    /variable/CMAKE_WARN_DEPRECATED
    /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
+   /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
 
 Variables that Describe the System
 ==================================
@@ -269,6 +276,7 @@ Variables that Control the Build
    /variable/CMAKE_ANDROID_STL_TYPE
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
+   /variable/CMAKE_AUTOGEN_PARALLEL
    /variable/CMAKE_AUTOMOC
    /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES
    /variable/CMAKE_AUTOMOC_DEPEND_FILTERS
@@ -285,6 +293,7 @@ Variables that Control the Build
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_CONFIG_POSTFIX
+   /variable/CMAKE_CUDA_SEPARABLE_COMPILATION
    /variable/CMAKE_DEBUG_POSTFIX
    /variable/CMAKE_ENABLE_EXPORTS
    /variable/CMAKE_EXE_LINKER_FLAGS
@@ -406,6 +415,8 @@ Variables for Languages
    /variable/CMAKE_LANG_CREATE_SHARED_MODULE
    /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY
    /variable/CMAKE_LANG_FLAGS
+   /variable/CMAKE_LANG_FLAGS_CONFIG
+   /variable/CMAKE_LANG_FLAGS_CONFIG_INIT
    /variable/CMAKE_LANG_FLAGS_DEBUG
    /variable/CMAKE_LANG_FLAGS_DEBUG_INIT
    /variable/CMAKE_LANG_FLAGS_INIT
@@ -415,6 +426,7 @@ Variables for Languages
    /variable/CMAKE_LANG_FLAGS_RELEASE_INIT
    /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
    /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
+   /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE
@@ -501,6 +513,7 @@ Variables for CTest
    /variable/CTEST_P4_COMMAND
    /variable/CTEST_P4_OPTIONS
    /variable/CTEST_P4_UPDATE_OPTIONS
+   /variable/CTEST_RUN_CURRENT_SCRIPT
    /variable/CTEST_SCP_COMMAND
    /variable/CTEST_SITE
    /variable/CTEST_SOURCE_DIRECTORY
@@ -525,6 +538,7 @@ Variables for CPack
    /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
    /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
    /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY
+   /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
    /variable/CPACK_INSTALL_SCRIPT
    /variable/CPACK_PACKAGING_INSTALL_PREFIX
    /variable/CPACK_SET_DESTDIR

Help/manual/cmake.1.rst

@@ -11,6 +11,7 @@ Synopsis
  cmake [<options>] (<path-to-source> | <path-to-existing-build>)
  cmake [(-D <var>=<value>)...] -P <cmake-script-file>
  cmake --build <dir> [<options>...] [-- <build-tool-options>...]
+ cmake --open <dir>
  cmake -E <command> [<options>...]
  cmake --find-package <options>...
 
@@ -51,6 +52,10 @@ Options
 ``--build <dir>``
  See `Build Tool Mode`_.
 
+``--open <dir>``
+ Open the generated project in the associated application.  This is
+ only supported by some generators.
+
 ``-N``
  View mode only.
 
@@ -332,7 +337,7 @@ Available commands are:
     ``paxr`` (restricted pax, default), and ``zip``.
 
 ``time <command> [<args>...]``
-  Run command and return elapsed time.
+  Run command and display elapsed time.
 
 ``touch <file>``
   Touch a file.

Help/manual/cpack.1.rst

@@ -62,6 +62,12 @@ Options
 
  Run cpack with debug output (for CPack developers).
 
+``--trace``
+ Put underlying cmake scripts in trace mode.
+
+``--trace-expand``
+ Put underlying cmake scripts in expanded trace mode.
+
 ``-P <package name>``
  override/define CPACK_PACKAGE_NAME
 

Help/manual/ctest.1.rst

@@ -3,12 +3,18 @@
 ctest(1)
 ********
 
+.. contents::
+
 Synopsis
 ========
 
 .. parsed-literal::
 
  ctest [<options>]
+ ctest <path-to-source> <path-to-build> --build-generator <generator>
+       [<options>...] [-- <build-options>...] [--test-command <test>]
+ ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
+       [-- <dashboard-options>...]
 
 Description
 ===========
@@ -55,17 +61,21 @@ Options
 ``-F``
  Enable failover.
 
- This option allows ctest to resume a test set execution that was
+ This option allows CTest to resume a test set execution that was
  previously interrupted.  If no interruption occurred, the ``-F`` option
  will have no effect.
 
 ``-j <jobs>, --parallel <jobs>``
  Run the tests in parallel using the given number of jobs.
 
- This option tells ctest to run the tests in parallel using given
+ This option tells CTest to run the tests in parallel using given
  number of jobs. This option can also be set by setting the
  environment variable ``CTEST_PARALLEL_LEVEL``.
 
+ This option can be used with the :prop_test:`PROCESSORS` test property.
+
+ See `Label and Subproject Summary`_.
+
 ``--test-load <level>``
  While running tests in parallel (e.g. with ``-j``), try not to start
  tests when they may cause the CPU load to pass above a given threshold.
@@ -74,7 +84,7 @@ Options
  ``TestLoad`` option of the `CTest Test Step`_.
 
 ``-Q,--quiet``
- Make ctest quiet.
+ Make CTest quiet.
 
  This option will suppress all the output.  The output log file will
  still be generated if the ``--output-log`` is specified.  Options such
@@ -84,37 +94,37 @@ Options
 ``-O <file>, --output-log <file>``
  Output to log file.
 
- This option tells ctest to write all its output to a log file.
+ This option tells CTest to write all its output to a log file.
 
 ``-N,--show-only``
  Disable actual execution of tests.
 
- This option tells ctest to list the tests that would be run but not
+ This option tells CTest to list the tests that would be run but not
  actually run them.  Useful in conjunction with the ``-R`` and ``-E``
  options.
 
 ``-L <regex>, --label-regex <regex>``
  Run tests with labels matching regular expression.
 
- This option tells ctest to run only the tests whose labels match the
+ This option tells CTest to run only the tests whose labels match the
  given regular expression.
 
 ``-R <regex>, --tests-regex <regex>``
  Run tests matching regular expression.
 
- This option tells ctest to run only the tests whose names match the
+ This option tells CTest to run only the tests whose names match the
  given regular expression.
 
 ``-E <regex>, --exclude-regex <regex>``
  Exclude tests matching regular expression.
 
- This option tells ctest to NOT run the tests whose names match the
+ This option tells CTest to NOT run the tests whose names match the
  given regular expression.
 
 ``-LE <regex>, --label-exclude <regex>``
  Exclude tests with labels matching regular expression.
 
- This option tells ctest to NOT run the tests whose labels match the
+ This option tells CTest to NOT run the tests whose labels match the
  given regular expression.
 
 ``-FA <regex>, --fixture-exclude-any <regex>``
@@ -137,11 +147,13 @@ Options
 ``-D <dashboard>, --dashboard <dashboard>``
  Execute dashboard test.
 
- This option tells ctest to act as a CDash client and perform a
+ This option tells CTest to act as a CDash client and perform a
  dashboard test.  All tests are <Mode><Test>, where Mode can be
  Experimental, Nightly, and Continuous, and Test can be Start,
  Update, Configure, Build, Test, Coverage, and Submit.
 
+ See `Dashboard Client`_.
+
 ``-D <var>:<type>=<value>``
  Define a variable for script mode.
 
@@ -153,35 +165,33 @@ Options
 ``-M <model>, --test-model <model>``
  Sets the model for a dashboard.
 
- This option tells ctest to act as a CDash client where the ``<model>``
+ This option tells CTest to act as a CDash client where the ``<model>``
  can be ``Experimental``, ``Nightly``, and ``Continuous``.
  Combining ``-M`` and ``-T`` is similar to ``-D``.
 
+ See `Dashboard Client`_.
+
 ``-T <action>, --test-action <action>``
  Sets the dashboard action to perform.
 
- This option tells ctest to act as a CDash client and perform some
+ This option tells CTest to act as a CDash client and perform some
  action such as ``start``, ``build``, ``test`` etc. See
  `Dashboard Client Steps`_ for the full list of actions.
  Combining ``-M`` and ``-T`` is similar to ``-D``.
 
-``--track <track>``
+ See `Dashboard Client`_.
- Specify the track to submit dashboard to
-
- Submit dashboard to specified track instead of default one.  By
- default, the dashboard is submitted to Nightly, Experimental, or
- Continuous track, but by specifying this option, the track can be
- arbitrary.
 
 ``-S <script>, --script <script>``
  Execute a dashboard for a configuration.
 
- This option tells ctest to load in a configuration script which sets
+ This option tells CTest to load in a configuration script which sets
  a number of parameters such as the binary and source directories.
- Then ctest will do what is required to create and run a dashboard.
+ Then CTest will do what is required to create and run a dashboard.
  This option basically sets up a dashboard and then runs ``ctest -D``
  with the appropriate options.
 
+ See `Dashboard Client`_.
+
 ``-SP <script>, --script-new-process <script>``
  Execute a dashboard for a configuration.
 
@@ -190,16 +200,12 @@ Options
  script may modify the environment and you do not want the modified
  environment to impact other ``-S`` scripts.
 
-``-A <file>, --add-notes <file>``
+ See `Dashboard Client`_.
- Add a notes file with submission.
-
- This option tells ctest to include a notes file when submitting
- dashboard.
 
 ``-I [Start,End,Stride,test#,test#|Test file], --tests-information``
  Run a specific number of tests by number.
 
- This option causes ctest to run tests starting at number Start,
+ This option causes CTest to run tests starting at number Start,
  ending at number End, and incrementing by Stride.  Any additional
  numbers after Stride are considered individual test numbers.  Start,
  End,or stride can be empty.  Optionally a file can be given that
@@ -214,11 +220,11 @@ Options
 ``--rerun-failed``
  Run only the tests that failed previously.
 
- This option tells ctest to perform only the tests that failed during
+ This option tells CTest to perform only the tests that failed during
- its previous run.  When this option is specified, ctest ignores all
+ its previous run.  When this option is specified, CTest ignores all
  other options intended to modify the list of tests to run (``-L``, ``-R``,
  ``-E``, ``-LE``, ``-I``, etc).  In the event that CTest runs and no tests
- fail, subsequent calls to ctest with the ``--rerun-failed`` option will run
+ fail, subsequent calls to CTest with the ``--rerun-failed`` option will run
  the set of tests that most recently failed (if any).
 
 ``--repeat-until-fail <n>``
@@ -236,7 +242,7 @@ Options
 ``--interactive-debug-mode [0|1]``
  Set the interactive mode to 0 or 1.
 
- This option causes ctest to run tests in either an interactive mode
+ This option causes CTest to run tests in either an interactive mode
  or a non-interactive mode.  On Windows this means that in
  non-interactive mode, all system debug pop up windows are blocked.
  In dashboard mode (Experimental, Nightly, Continuous), the default
@@ -246,36 +252,139 @@ Options
 ``--no-label-summary``
  Disable timing summary information for labels.
 
- This option tells ctest not to print summary information for each
+ This option tells CTest not to print summary information for each
  label associated with the tests run.  If there are no labels on the
  tests, nothing extra is printed.
 
+ See `Label and Subproject Summary`_.
+
 ``--no-subproject-summary``
  Disable timing summary information for subprojects.
 
- This option tells ctest not to print summary information for each
+ This option tells CTest not to print summary information for each
  subproject associated with the tests run.  If there are no subprojects on the
  tests, nothing extra is printed.
 
-``--build-and-test <path-to-source> <path-to-build>``
+ See `Label and Subproject Summary`_.
- Configure, build and run a test.
+
+``--build-and-test``
+See `Build and Test Mode`_.
+
+``--test-output-size-passed <size>``
+ Limit the output for passed tests to ``<size>`` bytes.
+
+``--test-output-size-failed <size>``
+ Limit the output for failed tests to ``<size>`` bytes.
+
+``--overwrite``
+ Overwrite CTest configuration option.
+
+ By default CTest uses configuration options from configuration file.
+ This option will overwrite the configuration option.
+
+``--force-new-ctest-process``
+ Run child CTest instances as new processes.
+
+ By default CTest will run child CTest instances within the same
+ process.  If this behavior is not desired, this argument will
+ enforce new processes for child CTest processes.
+
+``--schedule-random``
+ Use a random order for scheduling tests.
+
+ This option will run the tests in a random order.  It is commonly
+ used to detect implicit dependencies in a test suite.
+
+``--submit-index``
+ Legacy option for old Dart2 dashboard server feature.
+ Do not use.
+
+``--timeout <seconds>``
+ Set a global timeout on all tests.
+
+ This option will set a global timeout on all tests that do not
+ already have a timeout set on them.
+
+``--stop-time <time>``
+ Set a time at which all tests should stop running.
+
+ Set a real time of day at which all tests should timeout.  Example:
+ ``7:00:00 -0400``.  Any time format understood by the curl date parser
+ is accepted.  Local time is assumed if no timezone is specified.
+
+``--print-labels``
+ Print all available test labels.
+
+ This option will not run any tests, it will simply print the list of
+ all labels associated with the test set.
+
+.. include:: OPTIONS_HELP.txt
+
+.. _`Label and Subproject Summary`:
+
+Label and Subproject Summary
+============================
+
+CTest prints timing summary information for each label and subproject
+associated with the tests run. The label time summary will not include labels
+that are mapped to subprojects.
+
+When the :prop_test:`PROCESSORS` test property is set, CTest will display a
+weighted test timing result in label and subproject summaries. The time is
+reported with `sec*proc` instead of just `sec`.
+
+The weighted time summary reported for each label or subproject j is computed
+as::
+
+  Weighted Time Summary for Label/Subproject j =
+      sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])
 
- This option tells ctest to configure (i.e.  run cmake on), build,
+  for labels/subprojects j=1...total
- and or execute a test.  The configure and test steps are optional.
+
- The arguments to this command line are the source and binary
+where:
- directories.
+
- The ``--build-generator`` option *must* be provided to use
+* raw_test_time[j,i]: Wall-clock time for the ith test for the jth label or
- ``--build-and-test``.  If ``--test-command`` is specified then that will be
+  subproject
- run after the build is complete.  Other options that affect this
+* num_processors[j,i]: Value of the CTest PROCESSORS property for the ith test
- mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``,
+  for the jth label or subproject
- ``--build-two-config``, ``--build-exe-dir``,
+* num_tests[j]: Number of tests associated with the jth label or subproject
- ``--build-project``, ``--build-noclean`` and ``--build-options``.
+* total: Total number of labels or subprojects that have at least one test run
+
+Therefore, the weighted time summary for each label or subproject represents
+the amount of time that CTest gave to run the tests for each label or
+subproject and gives a good representation of the total expense of the tests
+for each label or subproject when compared to other labels or subprojects.
+
+For example, if "SubprojectA" showed "100 sec*proc" and "SubprojectB" showed
+"10 sec*proc", then CTest allocated approximately  10 times the CPU/core time
+to run the tests for "SubprojectA" than for "SubprojectB" (e.g. so if effort
+is going to be expended to reduce the cost of the test suite for the whole
+project, then reducing the cost of the test suite for "SubprojectA" would
+likely have a larger impact than effort to reduce the cost of the test suite
+for "SubprojectB").
+
+.. _`Build and Test Mode`:
+
+Build and Test Mode
+===================
+
+CTest provides a command-line signature to to configure (i.e.  run cmake on),
+build, and or execute a test::
+
+  ctest --build-and-test <path-to-source> <path-to-build>
+        --build-generator <generator> [<options>...] [-- <build-options>...]
+        [--test-command <test>]
+
+The configure and test steps are optional. The arguments to this command line
+are the source and binary directories. The ``--build-generator`` option *must*
+be provided to use ``--build-and-test``.  If ``--test-command`` is specified
+then that will be run after the build is complete.  Other options that affect
+this mode include:
 
 ``--build-target``
  Specify a specific target to build.
 
- This option goes with the ``--build-and-test`` option, if left out the
+ If left out the ``all`` target is built.
- ``all`` target is built.
 
 ``--build-nocmake``
  Run the build without running cmake first.
@@ -324,67 +433,47 @@ Options
 ``--test-command``
  The test to run with the ``--build-and-test`` option.
 
-``--test-output-size-passed <size>``
- Limit the output for passed tests to ``<size>`` bytes.
-
-``--test-output-size-failed <size>``
- Limit the output for failed tests to ``<size>`` bytes.
-
 ``--test-timeout``
- The time limit in seconds, internal use only.
+ The time limit in seconds
-
-``--tomorrow-tag``
- Nightly or experimental starts with next day tag.
-
- This is useful if the build will not finish in one day.
-
-``--ctest-config``
- The configuration file used to initialize CTest state when submitting dashboards.
 
- This option tells CTest to use different initialization file instead
+.. _`Dashboard Client`:
- of CTestConfiguration.tcl.  This way multiple initialization files
- can be used for example to submit to multiple dashboards.
-
-``--overwrite``
- Overwrite CTest configuration option.
 
- By default ctest uses configuration options from configuration file.
+Dashboard Client
- This option will overwrite the configuration option.
+================
 
-``--extra-submit <file>[;<file>]``
+CTest can operate as a client for the `CDash`_ software quality dashboard
- Submit extra files to the dashboard.
+application.  As a dashboard client, CTest performs a sequence of steps
+to configure, build, and test software, and then submits the results to
+a `CDash`_ server. The command-line signature used to submit to `CDash`_ is::
 
- This option will submit extra files to the dashboard.
+  ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
+        [-- <dashboard-options>...]
 
-``--force-new-ctest-process``
+Options for Dashboard Client include:
- Run child CTest instances as new processes.
 
- By default CTest will run child CTest instances within the same
+``--track <track>``
- process.  If this behavior is not desired, this argument will
+ Specify the track to submit dashboard to
- enforce new processes for child CTest processes.
 
-``--schedule-random``
+ Submit dashboard to specified track instead of default one.  By
- Use a random order for scheduling tests.
+ default, the dashboard is submitted to Nightly, Experimental, or
+ Continuous track, but by specifying this option, the track can be
+ arbitrary.
 
- This option will run the tests in a random order.  It is commonly
+``-A <file>, --add-notes <file>``
- used to detect implicit dependencies in a test suite.
+ Add a notes file with submission.
 
-``--submit-index``
+ This option tells CTest to include a notes file when submitting
- Legacy option for old Dart2 dashboard server feature.
+ dashboard.
- Do not use.
 
-``--timeout <seconds>``
+``--tomorrow-tag``
- Set a global timeout on all tests.
+ Nightly or experimental starts with next day tag.
 
- This option will set a global timeout on all tests that do not
+ This is useful if the build will not finish in one day.
- already have a timeout set on them.
 
-``--stop-time <time>``
+``--extra-submit <file>[;<file>]``
- Set a time at which all tests should stop running.
+ Submit extra files to the dashboard.
 
- Set a real time of day at which all tests should timeout.  Example:
+ This option will submit extra files to the dashboard.
- ``7:00:00 -0400``.  Any time format understood by the curl date parser
- is accepted.  Local time is assumed if no timezone is specified.
 
 ``--http1.0``
  Submit using HTTP 1.0.
@@ -399,26 +488,6 @@ Options
  this to maintain compatibility with an older version of CDash which
  doesn't support compressed test output.
 
-``--print-labels``
- Print all available test labels.
-
- This option will not run any tests, it will simply print the list of
- all labels associated with the test set.
-
-.. include:: OPTIONS_HELP.txt
-
-.. _`Dashboard Client`:
-
-Dashboard Client
-================
-
-CTest can operate as a client for the `CDash`_ software quality dashboard
-application.  As a dashboard client, CTest performs a sequence of steps
-to configure, build, and test software, and then submits the results to
-a `CDash`_ server.
-
-.. _`CDash`: http://cdash.org/
-
 Dashboard Client Steps
 ----------------------
 
@@ -731,7 +800,6 @@ Configuration settings to specify the version control tool include:
   * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY`
 
 
-
 Additional configuration settings include:
 
 ``NightlyStartTime``
@@ -773,6 +841,7 @@ Configuration settings include:
   * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS`
   * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS``
 
+  See `Label and Subproject Summary`_.
 
 .. _`CTest Build Step`:
 
@@ -804,6 +873,8 @@ Configuration settings include:
   * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS`
   * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS``
 
+  See `Label and Subproject Summary`_.
+
 ``MakeCommand``
   Command-line to launch the software build process.
   It will be executed in the location specified by the
@@ -847,6 +918,7 @@ Configuration settings include:
   * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS`
   * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS``
 
+  See `Label and Subproject Summary`_.
 
 ``TestLoad``
   While running tests in parallel (e.g. with ``-j``), try not to start
@@ -1082,3 +1154,5 @@ See Also
 ========
 
 .. include:: LINKS.txt
+
+.. _`CDash`: http://cdash.org/

Help/module/FetchContent.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../Modules/FetchContent.cmake

Help/module/FindIconv.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../Modules/FindIconv.cmake

Help/policy/CMP0037.rst

@@ -11,10 +11,15 @@ diagnostics expect target names to match a restricted pattern.
 
 Target names may contain upper and lower case letters, numbers, the underscore
 character (_), dot(.), plus(+) and minus(-).  As a special case, ALIAS
-targets and IMPORTED targets may contain two consequtive colons.
+targets and IMPORTED targets may contain two consecutive colons.
 
 Target names reserved by one or more CMake generators are not allowed.
-Among others these include "all", "help" and "test".
+Among others these include "all", "clean", "help", and "install".
+
+Target names associated with optional features, such as "test" and "package",
+may also be reserved.  CMake 3.10 and below always reserve them.  CMake 3.11
+and above reserve them only when the corresponding feature is enabled
+(e.g. by including the :module:`CTest` or :module:`CPack` modules).
 
 The OLD behavior for this policy is to allow creating targets with
 reserved names or which do not match the validity pattern.

Help/policy/CMP0072.rst

@@ -0,0 +1,26 @@
+CMP0072
+-------
+
+:module:`FindOpenGL` prefers GLVND by default when available.
+
+The :module:`FindOpenGL` module provides an ``OpenGL::GL`` target and an
+``OPENGL_LIBRARIES`` variable for projects to use for legacy GL interfaces.
+When both a legacy GL library (e.g. ``libGL.so``) and GLVND libraries
+for OpenGL and GLX (e.g. ``libOpenGL.so`` and ``libGLX.so``) are available,
+the module must choose between them.  It documents an ``OpenGL_GL_PREFERENCE``
+variable that can be used to specify an explicit preference.  When no such
+preference is set, the module must choose a default preference.
+
+CMake 3.11 and above prefer to choose GLVND libraries.  This policy provides
+compatibility with projects that expect the legacy GL library to be used.
+
+The ``OLD`` behavior for this policy is to set ``OpenGL_GL_PREFERENCE`` to
+``LEGACY``.  The ``NEW`` behavior for this policy is to set
+``OpenGL_GL_PREFERENCE`` to ``GLVND``.
+
+This policy was introduced in CMake version 3.11.  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_gbl/DEBUG_CONFIGURATIONS.rst

@@ -4,11 +4,10 @@ DEBUG_CONFIGURATIONS
 Specify which configurations are for debugging.
 
 The value must be a semi-colon separated list of configuration names.
-Currently this property is used only by the target_link_libraries
+Currently this property is used only by the :command:`target_link_libraries`
-command (see its documentation for details).  Additional uses may be
+command.  Additional uses may be defined in the future.
-defined in the future.
 
 This property must be set at the top level of the project and before
-the first target_link_libraries command invocation.  If any entry in
+the first :command:`target_link_libraries` command invocation.  If any entry in
 the list does not match a valid configuration for the project the
 behavior is undefined.

Help/prop_gbl/JOB_POOLS.rst

@@ -19,5 +19,8 @@ Defined pools could be used globally by setting
 or per target by setting the target properties
 :prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`.
 
+If not set, this property uses the value of the :variable:`CMAKE_JOB_POOLS`
+variable.
+
 Build targets provided by CMake that are meant for individual interactive
 use, such as ``install``, are placed in the ``console`` pool automatically.

Help/prop_sf/COMPILE_DEFINITIONS.rst

@@ -17,3 +17,13 @@ by the native build tool.  Xcode does not support per-configuration
 definitions on source files.
 
 .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt
+
+Contents of ``COMPILE_DEFINITIONS`` may use "generator expressions"
+with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+manual for available expressions.  However, :generator:`Xcode`
+does not support per-config per-source settings, so expressions
+that depend on the build configuration are not allowed with that
+generator.
+
+Generator expressions should be preferred instead of setting the alternative per-configuration
+property.

Help/prop_sf/COMPILE_FLAGS.rst

@@ -3,9 +3,9 @@ COMPILE_FLAGS
 
 Additional flags to be added when compiling this source file.
 
-These flags will be added to the list of compile flags when this
+The ``COMPILE_FLAGS`` property sets additional compiler flags used to build
-source file builds.  Use :prop_sf:`COMPILE_DEFINITIONS` to pass
+source files.  Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional
-additional preprocessor definitions.
+preprocessor definitions.
 
 Contents of ``COMPILE_FLAGS`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`

Help/prop_sf/COMPILE_OPTIONS.rst

@@ -0,0 +1,17 @@
+COMPILE_OPTIONS
+---------------
+
+List of additional options to pass to the compiler.
+
+This property holds a :ref:`;-list <CMake Language Lists>` of options
+and will be added to the list of compile flags when this
+source file builds.  Use :prop_sf:`COMPILE_DEFINITIONS` to pass
+additional preprocessor definitions and :prop_sf:`INCLUDE_DIRECTORIES` to pass
+additional include directories.
+
+Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
+syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
+for available expressions.  However, :generator:`Xcode`
+does not support per-config per-source settings, so expressions
+that depend on the build configuration are not allowed with that
+generator.

Help/prop_sf/GENERATED.rst

@@ -1,8 +1,23 @@
 GENERATED
 ---------
 
-Is this source file generated as part of the build process.
+Is this source file generated as part of the build or CMake process.
 
-If a source file is generated by the build process CMake will handle
+Tells the internal CMake engine that a source file is generated by an outside
-it differently in terms of dependency checking etc.  Otherwise having
+process such as another build step, or the execution of CMake itself. This
-a non-existent source file could create problems.
+information is then used to exempt the file from any existence or validity
+checks. Generated files are created by the execution of commands such as
+:command:`add_custom_command` and :command:`file(GENERATE)`.
+
+When a generated file created by an :command:`add_custom_command` command
+is explicitly listed as a source file for any target in the same
+directory scope (which usually means the same ``CMakeLists.txt`` file),
+CMake will automatically create a dependency to make sure the file is
+generated before building that target.
+
+Generated sources may be hidden in some IDE tools, while in others they might
+be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC`
+or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`,
+:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target
+properties may influence where the generated sources are grouped in the project's
+file lists.

Help/prop_sf/INCLUDE_DIRECTORIES.rst

@@ -0,0 +1,18 @@
+INCLUDE_DIRECTORIES
+-------------------
+
+List of preprocessor include file search directories.
+
+This property holds a :ref:`;-list <CMake Language Lists>` of paths
+and will be added to the list of include directories when this
+source file builds. These directories will take precedence over directories
+defined at target level except for :generator:`Xcode` generator due to technical
+limitations.
+
+Relative paths should not be added to this property directly.
+
+Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with
+the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
+for available expressions.  However, :generator:`Xcode` does not support
+per-config per-source settings, so expressions that depend on the build
+configuration are not allowed with that generator.

Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst

@@ -0,0 +1,6 @@
+VS_SHADER_DISABLE_OPTIMIZATIONS
+-------------------------------
+
+Disable compiler optimizations for an ``.hlsl`` source file.  This adds the
+``-Od`` flag to the command line for the FxCompiler tool.  Specify the value
+``true`` for this property to disable compiler optimizations.

Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst

@@ -0,0 +1,6 @@
+VS_SHADER_ENABLE_DEBUG
+----------------------
+
+Enable debugging information for an ``.hlsl`` source file.  This adds the
+``-Zi`` flag to the command line for the FxCompiler tool.  Specify the value
+``true`` to generate debugging information for the compiled shader.

Help/prop_tgt/AUTOGEN_PARALLEL.rst

@@ -0,0 +1,21 @@
+AUTOGEN_PARALLEL
+----------------
+
+Number of parallel ``moc`` or ``uic`` processes to start when using
+:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
+
+The custom `<origin>_autogen` target starts a number of threads of which
+each one parses a source file and on demand starts a ``moc`` or ``uic``
+process.  :prop_tgt:`AUTOGEN_PARALLEL` controls how many parallel threads
+(and therefore ``moc`` or ``uic`` processes) are started.
+
+- An empty (or unset) value or the string ``AUTO`` sets the number of
+  threads/processes to the number of physical CPUs on the host system.
+- A positive non zero integer value sets the exact thread/process count.
+- Otherwise a single thread/process is started.
+
+By default :prop_tgt:`AUTOGEN_PARALLEL` is initialized from
+:variable:`CMAKE_AUTOGEN_PARALLEL`.
+
+See the :manual:`cmake-qt(7)` manual for more information on using CMake
+with Qt.

Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst

@@ -3,15 +3,29 @@ AUTOGEN_TARGET_DEPENDS
 
 Target dependencies of the corresponding ``_autogen`` target.
 
-Targets which have their :prop_tgt:`AUTOMOC` target ``ON`` have a
+Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property
-corresponding ``_autogen`` target which is used to autogenerate generate moc
+``ON`` have a corresponding ``_autogen`` target which is used to auto generate
-files.  As this ``_autogen`` target is created at generate-time, it is not
+``moc`` and ``uic`` files.  As this ``_autogen`` target is created at
-possible to define dependencies of it, such as to create inputs for the ``moc``
+generate-time, it is not possible to define dependencies of it,
-executable.
+such as to create inputs for the ``moc`` or ``uic`` executable.
 
-The ``AUTOGEN_TARGET_DEPENDS`` target property can be set instead to a list of
+The :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property can be set instead to a
-dependencies for the ``_autogen`` target.  The buildsystem will be generated to
+list of dependencies of the ``_autogen`` target.  Dependencies can be target
-depend on its contents.
+names or file names.
 
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
+
+Use cases
+^^^^^^^^^
+
+If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either
+
+- a :prop_sf:`GENERATED` non C++ file (e.g. a :prop_sf:`GENERATED` ``.json``
+  or ``.ui`` file) or
+- a :prop_sf:`GENERATED` C++ file that isn't recognized by :prop_tgt:`AUTOMOC`
+  and :prop_tgt:`AUTOUIC` because it's skipped by :prop_sf:`SKIP_AUTOMOC`,
+  :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or
+- a file that isn't in the target's sources
+
+it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`.

Help/prop_tgt/AUTOMOC.rst

@@ -71,7 +71,8 @@ automoc targets together in an IDE, e.g.  in MSVS.
 The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group
 files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g.  in MSVS.
 
-Additional macro names to search for can be added to :prop_tgt:`AUTOMOC_MACRO_NAMES`.
+Additional macro names to search for can be added to
+:prop_tgt:`AUTOMOC_MACRO_NAMES`.
 
 Additional ``moc`` dependency file names can be extracted from source code
 by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`.
@@ -82,5 +83,8 @@ which is controlled by :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`.
 Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by
 enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 
+The number of parallel ``moc`` processes to start can be modified by
+setting :prop_tgt:`AUTOGEN_PARALLEL`.
+
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.

Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst

@@ -1,21 +1,27 @@
 AUTOMOC_DEPEND_FILTERS
 ----------------------
 
-Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from
+Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from a
-source code as additional dependencies for the ``moc`` file.
+source file that are registered as additional dependencies for the
-
+``moc`` file of the source file.
-This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON``
-for this target.
 
 Filters are defined as ``KEYWORD;REGULAR_EXPRESSION`` pairs. First the file
 content is searched for ``KEYWORD``. If it is found at least once, then file
 names are extracted by successively searching for ``REGULAR_EXPRESSION`` and
 taking the first match group.
 
-Consider a filter extracts the file name ``DEP`` from the content of a file
+The file name found in the first match group is searched for
-``FOO``. If ``DEP`` changes, then the ``moc`` file for ``FOO`` gets rebuilt.
+
-The file ``DEP`` is searched for first in the vicinity
+- first in the vicinity of the source file
-of ``FOO`` and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
+- and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
+
+If any of the extracted files changes, then the ``moc`` file for the source
+file gets rebuilt even when the source file itself doesn't change.
+
+If any of the extracted files is :prop_sf:`GENERATED` or if it is not in the
+target's sources, then it might be necessary to add it to the
+``_autogen`` target  dependencies.
+See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference.
 
 By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from
 :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default.
@@ -24,22 +30,75 @@ See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.
 
 
-Example
+Example 1
-^^^^^^^
+^^^^^^^^^
 
-Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we
+A header file ``my_class.hpp`` uses a custom macro ``JSON_FILE_MACRO`` which
-want the ``moc`` file to depend on the macro`s file name argument::
+is defined in an other header ``macros.hpp``.
+We want the ``moc`` file of ``my_class.hpp`` to depend on the file name
+argument of ``JSON_FILE_MACRO``::
 
+  // my_class.hpp
   class My_Class : public QObject
   {
     Q_OBJECT
-    OBJ_JSON_FILE ( "DEP.json" )
+    JSON_FILE_MACRO ( "info.json" )
+  ...
+  };
+
+In ``CMakeLists.txt`` we add a filter to
+:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` like this::
+
+  list( APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
+    "JSON_FILE_MACRO"
+    "[\n][ \t]*JSON_FILE_MACRO[ \t]*\\([ \t]*\"([^\"]+)\""
+  )
+
+We assume ``info.json`` is a plain (not :prop_sf:`GENERATED`) file that is
+listed in the target's source.  Therefore we do not need to add it to
+:prop_tgt:`AUTOGEN_TARGET_DEPENDS`.
+
+Example 2
+^^^^^^^^^
+
+In the target ``my_target`` a header file ``complex_class.hpp`` uses a
+custom macro ``JSON_BASED_CLASS`` which is defined in an other header
+``macros.hpp``::
+
+  // macros.hpp
   ...
+  #define JSON_BASED_CLASS(name, json) \
+  class name : public QObject \
+  { \
+    Q_OBJECT \
+    Q_PLUGIN_METADATA(IID "demo" FILE json) \
+    name() {} \
   };
+  ...
+
+::
 
-Then we might use :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` to
+  // complex_class.hpp
-define a filter like this::
+  #pragma once
+  JSON_BASED_CLASS(Complex_Class, "meta.json")
+  // end of file
 
-  set(CMAKE_AUTOMOC_DEPEND_FILTERS
+Since ``complex_class.hpp`` doesn't contain a ``Q_OBJECT`` macro it would be
-    "OBJ_JSON_FILE" "[\n][ \t]*OBJ_JSON_FILE[ \t]*\\([ \t]*\"([^\"]+)\""
+ignored by :prop_tgt:`AUTOMOC`.  We change this by adding ``JSON_BASED_CLASS``
+to :variable:`CMAKE_AUTOMOC_MACRO_NAMES`::
+
+  list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "JSON_BASED_CLASS")
+
+We want the ``moc`` file of ``complex_class.hpp`` to depend on
+``meta.json``.  So we add a filter to
+:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`::
+
+  list(APPEND CMAKE_AUTOMOC_DEPEND_FILTERS
+    "JSON_BASED_CLASS"
+    "[\n^][ \t]*JSON_BASED_CLASS[ \t]*\\([^,]*,[ \t]*\"([^\"]+)\""
   )
+
+Additionally we assume ``meta.json`` is :prop_sf:`GENERATED` which is
+why we have to add it to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`::
+
+  set_property(TARGET my_target APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "meta.json")

Help/prop_tgt/AUTORCC.rst

@@ -13,6 +13,11 @@ as target sources at build time and invoke ``rcc`` accordingly.
 This property is initialized by the value of the :variable:`CMAKE_AUTORCC`
 variable if it is set when a target is created.
 
+By default :prop_tgt:`AUTORCC` is processed inside a
+:command:`custom command <add_custom_command>`.
+If the ``.qrc`` file is :prop_sf:`GENERATED` though, a
+:command:`custom target <add_custom_target>` is used instead.
+
 Additional command line options for rcc can be set via the
 :prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file.
 

Help/prop_tgt/AUTOUIC.rst

@@ -33,5 +33,8 @@ autouic targets together in an IDE, e.g. in MSVS.
 Source files can be excluded from :prop_tgt:`AUTOUIC` processing by
 enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 
+The number of parallel ``uic`` processes to start can be modified by
+setting :prop_tgt:`AUTOGEN_PARALLEL`.
+
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.

Help/prop_tgt/COMPILE_FLAGS.rst

@@ -8,4 +8,4 @@ build sources within the target.  Use :prop_tgt:`COMPILE_DEFINITIONS`
 to pass additional preprocessor definitions.
 
 This property is deprecated.  Use the :prop_tgt:`COMPILE_OPTIONS`
-property or the command:`target_compile_options` command instead.
+property or the :command:`target_compile_options` command instead.

Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst

@@ -11,3 +11,7 @@ For instance:
 .. code-block:: cmake
 
   set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON)
+
+This property is initialized by the value of the
+:variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable if it is set when a
+target is created.

Help/prop_tgt/IMPORTED_GLOBAL.rst

@@ -0,0 +1,22 @@
+IMPORTED_GLOBAL
+---------------
+
+Indication of whether an :ref:`IMPORTED target <Imported Targets>` is
+globally visible.
+
+The boolean value of this property is True for targets created with the
+``IMPORTED`` ``GLOBAL`` options to :command:`add_executable()` or
+:command:`add_library()`. It is always False for targets built within the
+project.
+
+For targets created with the ``IMPORTED`` option to
+:command:`add_executable()` or :command:`add_library()` but without the
+additional option ``GLOBAL`` this is False, too. However, setting this
+property for such a locally ``IMPORTED`` target to True promotes that
+target to global scope. This promotion can only be done in the same
+directory where that ``IMPORTED`` target was created in the first place.
+
+Once an imported target has been made global, it cannot be changed back to
+non-global. Therefore, if a project sets this property, it may only
+provide a value of True. CMake will issue an error if the project tries to
+set the property to a non-True value, even if the value was already False.

Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst

@@ -2,7 +2,7 @@
 ------------------------
 
 This property is implemented only when ``<LANG>`` is ``C``, ``CXX``,
-or ``CUDA``.
+``Fortran``, or ``CUDA``.
 
 Specify a :ref:`;-list <CMake Language Lists>` containing a command line
 for a compiler launching tool. The :ref:`Makefile Generators` and the

Help/prop_tgt/LINK_FLAGS.rst

@@ -4,5 +4,6 @@ LINK_FLAGS
 Additional flags to use when linking this target.
 
 The LINK_FLAGS property can be used to add extra flags to the link
-step of a target.  LINK_FLAGS_<CONFIG> will add to the configuration
+step of a target.  :prop_tgt:`LINK_FLAGS_<CONFIG>` will add to the
-<CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO.
+configuration ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``,
+``MINSIZEREL``, ``RELWITHDEBINFO``, ...

Help/prop_tgt/OUTPUT_NAME.rst

@@ -5,7 +5,8 @@ Output name for target files.
 
 This sets the base name for output files created for an executable or
 library target.  If not set, the logical target name is used by
-default.
+default during generation. The value is not set by default during
+configuration.
 
 Contents of ``OUTPUT_NAME`` and the variants listed below may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.

Help/release/3.10.rst

@@ -139,7 +139,8 @@ Modules
   This is robust against unusual ways of labeling tests, provides much better
   support for advanced features such as parameterized tests, and does not
   require re-running CMake to discover added or removed tests within a test
-  executable.
+  executable.  Note that a breaking change was made in CMake 3.10.3 to address
+  an ambiguity of the ``TIMEOUT`` keyword (see :ref:`Release Notes 3.10.3`).
 
 * The :module:`InstallRequiredSystemLibraries` module gained support
   for installing Intel compiler runtimes.
@@ -267,3 +268,17 @@ Changes made since CMake 3.10.0 include the following.
 * The :manual:`cmake-server(7)` ``codemodel`` response ``crossReferences``
   field added by 3.10.0 has been dropped due to excessive memory usage.
   Another approach will be needed to provide backtrace information.
+
+.. _`Release Notes 3.10.3`:
+
+3.10.3
+------
+
+* CMake 3.10.1 added a ``TIMEOUT`` option to :command:`gtest_discover_tests`
+  from the :module:`GoogleTest` module.  That keyword clashed with the
+  ``TIMEOUT`` test property, which is one of the common properties that
+  would be set with the command's ``PROPERTIES`` keyword, usually leading
+  to legal but unintended behavior.  The keyword was changed to
+  ``DISCOVERY_TIMEOUT`` in CMake 3.10.3 to address this problem.  The
+  ambiguous behavior of the :command:`gtest_discover_tests` command's
+  ``TIMEOUT`` keyword in 3.10.1 and 3.10.2 has not been preserved.

Help/release/3.11.rst

@@ -0,0 +1,285 @@
+CMake 3.11 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.10 include the following.
+
+New Features
+============
+
+Platforms
+---------
+
+* TI C/C++ compilers are now supported by the :generator:`Ninja` generator.
+
+Generators
+----------
+
+* The :generator:`CodeBlocks` extra generator learned to check a
+  :variable:`CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom
+  compiler identification value to place in the project file.
+
+* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
+  to add compiler launcher tools along with the compiler for the ``Fortran``
+  language (``C``, ``CXX``, and ``CUDA`` were supported previously).
+  See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
+  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
+
+* :ref:`Visual Studio Generators` learned to support the ``COMPILE_LANGUAGE``
+  :manual:`generator expression <cmake-generator-expressions(7)>` in
+  target-wide :prop_tgt:`COMPILE_DEFINITIONS`,
+  :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_OPTIONS`, and
+  :command:`file(GENERATE)`.  See generator expression documentation
+  for caveats.
+
+* The :generator:`Xcode` generator learned to support the ``COMPILE_LANGUAGE``
+  :manual:`generator expression <cmake-generator-expressions(7)>` in
+  target-wide :prop_tgt:`COMPILE_DEFINITIONS` and
+  :prop_tgt:`INCLUDE_DIRECTORIES`.  It previously supported only
+  :prop_tgt:`COMPILE_OPTIONS` and :command:`file(GENERATE)`.
+  See generator expression documentation for caveats.
+
+Commands
+--------
+
+* :command:`add_library` and :command:`add_executable` commands can now be
+  called without any sources and will not complain as long as sources are
+  added later via the :command:`target_sources` command.
+
+* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands
+  gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a
+  ``.netrc`` file.
+
+* The :command:`target_compile_definitions` command learned to set the
+  :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on
+  :ref:`Imported Targets`.
+
+* The :command:`target_compile_features` command learned to set the
+  :prop_tgt:`INTERFACE_COMPILE_FEATURES` property on :ref:`Imported Targets`.
+
+* The :command:`target_compile_options` command learned to set the
+  :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property on :ref:`Imported Targets`.
+
+* The :command:`target_include_directories` command learned to set the
+  :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property on
+  :ref:`Imported Targets`.
+
+* The :command:`target_sources` command learned to set the
+  :prop_tgt:`INTERFACE_SOURCES` property on :ref:`Imported Targets`.
+
+* The :command:`target_link_libraries` command learned to set the
+  :prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`.
+
+Variables
+---------
+
+* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced
+  to hold the selected instance of the generator's corresponding
+  native tools if multiple are available.  This is used by the
+  :generator:`Visual Studio 15 2017` generator to hold the
+  selected instance of Visual Studio persistently.
+
+* A :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
+  to enable setting of default permissions for directories created implicitly
+  during installation of files by :command:`install` and
+  :command:`file(INSTALL)`, e.g. during ``make install``.
+
+* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for
+  the :prop_gbl:`JOB_POOLS` property. This enables control over build
+  parallelism with command line configuration parameters when using the Ninja
+  generator.
+
+* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables
+  were added to specify use of a ``.netrc`` file by the
+  :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and
+  the :module:`ExternalProject` module.
+
+* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to
+  initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property
+  on targets when they are created.
+
+Properties
+----------
+
+* The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+* A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list
+  of options to pass to the compiler.
+
+* An :prop_tgt:`IMPORTED_GLOBAL` target property was added to indicate
+  whether an :ref:`IMPORTED target <Imported Targets>` is globally visible.
+  It is automatically set to a true value for targets created with the
+  ``GLOBAL`` option to :command:`add_library` or :command:`add_executable`.
+  Additionally, project code may now *promote* a local imported target
+  to be globally visible by setting this property to ``TRUE``.
+
+* An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify
+  list of preprocessor include file search directories.
+
+* Source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` and
+  :prop_sf:`VS_SHADER_ENABLE_DEBUG` have been added to specify more
+  details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.
+
+Modules
+-------
+
+* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES`
+  command gained a ``LANGUAGE`` option to specify whether to check using the
+  ``C`` or ``CXX`` compiler.
+
+* The :module:`CMakePackageConfigHelpers` module
+  :command:`write_basic_package_version_file` command learned a new
+  ``SameMinorVersion`` mode for the ``COMPATIBILITY`` argument.
+
+* The :module:`ExternalProject` module learned to substitute ``<DOWNLOAD_DIR>``
+  in comments, commands, working directory and byproducts.
+
+* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE``
+  options to specify use of a ``.netrc`` file.
+
+* A new :module:`FetchContent` module was added which supports populating
+  content at configure time using any of the download/update methods
+  supported by :command:`ExternalProject_Add`.  This allows the content
+  to be used immediately during the configure stage, such as with
+  :command:`add_subdirectory`, etc.  Hierarchical project structures are
+  well supported, allowing parent projects to override the content details
+  of child projects and ensuring content is not populated multiple times
+  throughout the whole project tree.
+
+* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
+  `FLAME`_ ``blis`` and ``libflame``.
+
+* The :module:`FindDoxygen` module :command:`doxygen_add_docs` function
+  now supports a new ``DOXYGEN_VERBATIM_VARS`` list variable.  Any
+  ``DOXYGEN_...`` variable contained in that list will bypass the automatic
+  quoting logic, leaving its contents untouched when transferring them to the
+  output ``Doxyfile``.
+
+* A :module:`FindIconv` module was added to locate iconv support.
+
+* The :module:`GenerateExportHeader` module ``GENERATE_EXPORT_HEADER`` command
+  gained an ``INCLUDE_GUARD_NAME`` option to change the name of the include
+  guard symbol written to the generated export header.
+  Additionally, it now adds a comment after the closing ``#endif`` on the
+  generated export header's include guard.
+
+* The :module:`UseJava` module ``add_jar`` command gained a
+  ``GENERATE_NATIVE_HEADERS`` option to generate native header files
+  using ``javac -h`` for ``javac`` 1.8 or above.  This supersedes
+  ``create_javah``, which no longer works with JDK 1.10 and above due
+  to removal of the ``javah`` tool by `JEP 313`_.
+
+.. _`FLAME`: https://github.com/flame
+.. _`JEP 313`: http://openjdk.java.net/jeps/313
+
+Autogen
+-------
+
+* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, CMake now starts
+  multiple parallel ``moc`` or ``uic`` processes to reduce the build time.
+  A new :variable:`CMAKE_AUTOGEN_PARALLEL` variable and
+  :prop_tgt:`AUTOGEN_PARALLEL` target property may be set to specify the
+  number of parallel ``moc`` or ``uic`` processes to start.  The default
+  is derived from the number of CPUs on the host.
+
+CTest
+-----
+
+* The :command:`ctest_start` command no longer sets
+  :variable:`CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is
+  called from inside a function. Instead, it sets an internal variable in
+  CTest. However, setting :variable:`CTEST_RUN_CURRENT_SCRIPT` to 0 at the
+  global scope still prevents the script from being re-run at the end.
+
+CPack
+-----
+
+* :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options.
+
+* The :module:`CPackIFW` module gained new
+  :variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control
+  if the target directory should not be deleted when uninstalling.
+
+* The :module:`CPackRPM` module learned to enable enforcing of execute
+  privileges on programs and shared libraries.
+  See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable.
+
+* A :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
+  which serves the same purpose during packaging (e.g. ``make package``) as the
+  :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during
+  installation (e.g. ``make install``).
+
+Other
+-----
+
+* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are
+  created with the ``GLOBAL`` option to :command:`add_library`.
+
+* :ref:`Interface Libraries` may now have custom properties set on them if
+  they start with either an underscore (``_``) or a lowercase ASCII character.
+  The original intention was to only allow properties which made sense for
+  ``INTERFACE`` libraries, but it also blocked usage of custom properties.
+
+* The :manual:`cmake(1)` ``--open <dir>`` command-line option was added
+  to open generated IDE projects like Visual Studio solutions or Xcode
+  projects.
+
+Deprecated and Removed Features
+===============================
+
+* An explicit deprecation diagnostic was added for policies ``CMP0037``
+  through ``CMP0054`` (``CMP0036`` 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.
+
+* The ``KDevelop3`` generator has been removed.
+
+Other Changes
+=============
+
+* Policy :policy:`CMP0037` no longer reserves target names associated
+  with optional features, such as ``test`` and ``package``, unless
+  the corresponding feature is enabled.
+
+* The :module:`FindOpenGL` module now prefers GLVND libraries if available.
+  See policy :policy:`CMP0072`.
+
+* The minimum deployment target set in the
+  :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only
+  applied for macOS regardless of the selected SDK.  It is now properly
+  set for the target platform selected by :variable:`CMAKE_OSX_SYSROOT`.
+  For example, if the sysroot variable specifies an iOS SDK then the
+  value in ``CMAKE_OSX_DEPLOYMENT_TARGET`` is interpreted as minimum
+  iOS version.
+
+* The :generator:`Xcode` generator behavior of generating one project
+  file per :command:`project()` command may now be controlled with the
+  :variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable.
+  This could be useful to speed up the CMake generation step for
+  large projects and to work-around a bug in the ``ZERO_CHECK`` logic.
+
+* Since the ``CMakeCache.txt`` format does not support newlines in values,
+  values containing newlines are now truncated before writing to the file.
+  In addition, a warning comment is written to the cache file, and a warning
+  message is displayed to the user on the console.
+
+Updates
+=======
+
+Changes made since CMake 3.11.0 include the following.
+
+3.11.1
+------
+
+* The :module:`CheckIncludeFile` module ``check_include_file`` macro,
+  :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro,
+  and :module:`CheckIncludeFiles` module ``check_include_files`` macro
+  were taught to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable in
+  CMake 3.11.0.  This has been reverted due to changing behavior of
+  checks for existing projects.  It may be restored in the future
+  with a policy for compatibility.

Help/release/3.4.rst

@@ -66,7 +66,7 @@ Variables
 Properties
 ----------
 
-* :ref:`Visual Studio Generators` learned to support additonal
+* :ref:`Visual Studio Generators` learned to support additional
   target properties to customize projects for NVIDIA Nsight
   Tegra Visual Studio Edition:
 

Help/release/3.6.rst

@@ -111,7 +111,7 @@ Modules
 
 * The :module:`ExternalProject` module learned to initialize Git submodules
   recursively and also to initialize new submodules on updates.  Use the
-  ``GIT_SUBMODULES`` option to restrict which submodules are initalized and
+  ``GIT_SUBMODULES`` option to restrict which submodules are initialized and
   updated.
 
 * The :module:`ExternalProject` module leared the ``DOWNLOAD_NO_EXTRACT 1``

Help/release/3.7.rst

@@ -237,7 +237,7 @@ CPack
 
 * The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
   :command:`cpack_ifw_configure_component_group` commands gained a new
-  ``USER_INTERFACES`` option to add a list of additonal pages to the IFW
+  ``USER_INTERFACES`` option to add a list of additional pages to the IFW
   installer.
 
 * The :module:`CPackRPM` module learned to generate debuginfo

Help/release/index.rst

@@ -13,6 +13,7 @@ Releases
 .. toctree::
    :maxdepth: 1
 
+   3.11 <3.11>
    3.10 <3.10>
    3.9 <3.9>
    3.8 <3.8>

Help/variable/CMAKE_AUTOGEN_PARALLEL.rst

@@ -0,0 +1,10 @@
+CMAKE_AUTOGEN_PARALLEL
+----------------------
+
+Number of parallel ``moc`` or ``uic`` processes to start when using
+:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
+
+This variable is used to initialize the :prop_tgt:`AUTOGEN_PARALLEL` property
+on all the targets.  See that target property for additional information.
+
+By default :variable:`CMAKE_AUTOGEN_PARALLEL` is unset.

Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst

@@ -12,7 +12,7 @@ information.
 The default value is ``Q_OBJECT;Q_GADGET;Q_NAMESPACE``.
 
 Example
--------
+^^^^^^^
 Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc``
 processed as well::
 

Help/variable/CMAKE_BUILD_TYPE.rst

@@ -5,7 +5,7 @@ Specifies the build type on single-configuration generators.
 
 This statically specifies what build type (configuration) will be
 built in this build tree.  Possible values are empty, ``Debug``, ``Release``,
-``RelWithDebInfo`` and ``MinSizeRel``.  This variable is only meaningful to
+``RelWithDebInfo``, ``MinSizeRel``, ...  This variable is only meaningful to
 single-configuration generators (such as :ref:`Makefile Generators` and
 :generator:`Ninja`) i.e.  those which choose a single configuration when CMake
 runs to generate a build tree as opposed to multi-configuration generators
@@ -13,7 +13,7 @@ which offer selection of the build configuration within the generated build
 environment.  There are many per-config properties and variables
 (usually following clean ``SOME_VAR_<CONFIG>`` order conventions), such as
 ``CMAKE_C_FLAGS_<CONFIG>``, specified as uppercase:
-``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]``.  For example,
+``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL|...]``.  For example,
 in a build tree configured to build type ``Debug``, CMake will see to
 having :variable:`CMAKE_C_FLAGS_DEBUG <CMAKE_<LANG>_FLAGS_DEBUG>` settings get
 added to the :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` settings.  See

Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst

@@ -0,0 +1,13 @@
+CMAKE_CODEBLOCKS_COMPILER_ID
+----------------------------
+
+Change the compiler id in the generated CodeBlocks project files.
+
+CodeBlocks uses its own compiler id string which differs from
+:variable:`CMAKE_<LANG>_COMPILER_ID`.  If this variable is left empty,
+CMake tries to recognize the CodeBlocks compiler id automatically.
+Otherwise the specified string is used in the CodeBlocks project file.
+See the CodeBlocks documentation for valid compiler id strings.
+
+Other IDEs like QtCreator that also use the CodeBlocks generator may ignore
+this setting.

Help/variable/CMAKE_CROSSCOMPILING.rst

@@ -1,8 +1,26 @@
 CMAKE_CROSSCOMPILING
 --------------------
 
-Is CMake currently cross compiling.
+Intended to indicate whether CMake is cross compiling, but note limitations
+discussed below.
 
-This variable will be set to true by CMake if CMake is cross
+This variable will be set to true by CMake if the :variable:`CMAKE_SYSTEM_NAME`
-compiling.  Specifically if the build platform is different from the
+variable has been set manually (i.e. in a toolchain file or as a cache entry
-target platform.
+from the :manual:`cmake <cmake(1)>` command line). In most cases, manually
+setting :variable:`CMAKE_SYSTEM_NAME` will only be done when cross compiling,
+since it will otherwise be given the same value as
+:variable:`CMAKE_HOST_SYSTEM_NAME` if not manually set, which is correct for
+the non-cross-compiling case. In the event that :variable:`CMAKE_SYSTEM_NAME`
+is manually set to the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`, then
+``CMAKE_CROSSCOMPILING`` will still be set to true.
+
+Another case to be aware of is that builds targeting Apple platforms other than
+macOS are handled differently to other cross compiling scenarios. Rather than
+relying on :variable:`CMAKE_SYSTEM_NAME` to select the target platform, Apple
+device builds use :variable:`CMAKE_OSX_SYSROOT` to select the appropriate SDK,
+which indirectly determines the target platform. Furthermore, when using the
+Xcode generator, developers can switch between device and simulator builds at
+build time rather than having a single choice at configure time, so the concept
+of whether the build is cross compiling or not is more complex. Therefore, the
+use of ``CMAKE_CROSSCOMPILING`` is not recommended for projects targeting Apple
+devices.

Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst

@@ -0,0 +1,6 @@
+CMAKE_CUDA_SEPARABLE_COMPILATION
+--------------------------------
+
+Default value for :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property.
+This variable is used to initialize the property on each target as it is
+created.

Help/variable/CMAKE_EXTRA_GENERATOR.rst

@@ -4,7 +4,7 @@ CMAKE_EXTRA_GENERATOR
 The extra generator used to build the project.  See
 :manual:`cmake-generators(7)`.
 
-When using the Eclipse, CodeBlocks or KDevelop generators, CMake
+When using the Eclipse, CodeBlocks, CodeLite, Kate or Sublime generators, CMake
 generates Makefiles (:variable:`CMAKE_GENERATOR`) and additionally project
 files for the respective IDE.  This IDE project file generator is stored in
 ``CMAKE_EXTRA_GENERATOR`` (e.g.  ``Eclipse CDT4``).

Help/variable/CMAKE_GENERATOR_INSTANCE.rst

@@ -0,0 +1,24 @@
+CMAKE_GENERATOR_INSTANCE
+------------------------
+
+Generator-specific instance specification provided by user.
+
+Some CMake generators support selection of an instance of the native build
+system when multiple instances are available.  If the user specifies an
+instance (e.g. by setting this cache entry), or after a default instance is
+chosen when a build tree is first configured, the value will be available in
+this variable.
+
+The value of this variable should never be modified by project code.
+A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
+variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry.
+Once a given build tree has been initialized with a particular value
+for this variable, changing the value has undefined behavior.
+
+Instance specification is supported only on specific generators:
+
+* For the :generator:`Visual Studio 15 2017` generator (and above)
+  this specifies the absolute path to the VS installation directory
+  of the selected VS instance.
+
+See native build system documentation for allowed instance values.

Help/variable/CMAKE_INCLUDE_CURRENT_DIR.rst

@@ -1,7 +1,7 @@
 CMAKE_INCLUDE_CURRENT_DIR
 -------------------------
 
-Automatically add the current source- and build directories to the include path.
+Automatically add the current source and build directories to the include path.
 
 If this variable is enabled, CMake automatically adds
 :variable:`CMAKE_CURRENT_SOURCE_DIR` and :variable:`CMAKE_CURRENT_BINARY_DIR`

Help/variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE.rst

@@ -1,7 +1,7 @@
 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
 --------------------------------------
 
-Automatically add the current source- and build directories to the
+Automatically add the current source and build directories to the
 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property.
 
 If this variable is enabled, CMake automatically adds for each shared

Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst

@@ -0,0 +1,29 @@
+CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
+-------------------------------------------
+
+Default permissions for directories created implicitly during installation
+of files by :command:`install` and :command:`file(INSTALL)`.
+
+If ``make install`` is invoked and directories are implicitly created they
+get permissions set by :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`
+variable or platform specific default permissions if the variable is not set.
+
+Implicitly created directories are created if they are not explicitly installed
+by :command:`install` command but are needed to install a file on a certain
+path. Example of such locations are directories created due to the setting of
+:variable:`CMAKE_INSTALL_PREFIX`.
+
+Expected content of the :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`
+variable is a list of permissions that can be used by :command:`install` command
+`PERMISSIONS` section.
+
+Example usage:
+
+::
+
+ set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS
+      OWNER_READ
+      OWNER_WRITE
+      OWNER_EXECUTE
+      GROUP_READ
+    )

Help/variable/CMAKE_JOB_POOLS.rst

@@ -0,0 +1,6 @@
+CMAKE_JOB_POOLS
+---------------
+
+If the :prop_gbl:`JOB_POOLS` global property is not set, the value
+of this variable is used in its place.  See :prop_gbl:`JOB_POOLS`
+for additional information.

Help/variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN.rst

@@ -6,7 +6,7 @@ The external toolchain for cross-compiling, if supported.
 Some compiler toolchains do not ship their own auxiliary utilities such as
 archivers and linkers.  The compiler driver may support a command-line argument
 to specify the location of such tools.
-``CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN`` may be set to a path to a path to
+``CMAKE_<LANG>_COMPILER_EXTERNAL_TOOLCHAIN`` may be set to a path to
 the external toolchain and will be passed to the compiler driver if supported.
 
 This variable may only be set in a toolchain file specified by

Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst

@@ -3,4 +3,5 @@ CMAKE_<LANG>_COMPILER_LAUNCHER
 
 Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property.
 This variable is used to initialize the property on each target as it is
-created.  This is done only when ``<LANG>`` is ``C``, ``CXX``, or ``CUDA``.
+created.  This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``,
+or ``CUDA``.

Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst

@@ -0,0 +1,4 @@
+CMAKE_<LANG>_FLAGS_<CONFIG>
+---------------------------
+
+Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration.

Help/variable/CMAKE_LANG_FLAGS_CONFIG_INIT.rst

@@ -0,0 +1,10 @@
+CMAKE_<LANG>_FLAGS_<CONFIG>_INIT
+--------------------------------
+
+Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
+entry the first time a build tree is configured for language ``<LANG>``.
+This variable is meant to be set by a :variable:`toolchain file
+<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
+the value based on the environment and target platform.
+
+See also :variable:`CMAKE_<LANG>_FLAGS_INIT`.

Help/variable/CMAKE_LANG_FLAGS_DEBUG.rst

@@ -1,6 +1,5 @@
 CMAKE_<LANG>_FLAGS_DEBUG
 ------------------------
 
-Flags for ``Debug`` build type or configuration.
+This variable is the ``Debug`` variant of the
-
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable.
-``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Debug``.

Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst

@@ -1,10 +1,5 @@
 CMAKE_<LANG>_FLAGS_DEBUG_INIT
 -----------------------------
 
-Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_DEBUG` cache
+This variable is the ``Debug`` variant of the
-entry the first time a build tree is configured for language ``<LANG>``.
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable.
-This variable is meant to be set by a :variable:`toolchain file
-<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
-the value based on the environment and target platform.
-
-See also :variable:`CMAKE_<LANG>_FLAGS_INIT`.

Help/variable/CMAKE_LANG_FLAGS_INIT.rst

@@ -7,9 +7,5 @@ This variable is meant to be set by a :variable:`toolchain file
 <CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
 the value based on the environment and target platform.
 
-See also the configuration-specific variables:
+See also the configuration-specific
-
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable.
-* :variable:`CMAKE_<LANG>_FLAGS_DEBUG_INIT`
-* :variable:`CMAKE_<LANG>_FLAGS_RELEASE_INIT`
-* :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT`
-* :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT`

Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL.rst

@@ -1,7 +1,5 @@
 CMAKE_<LANG>_FLAGS_MINSIZEREL
 -----------------------------
 
-Flags for ``MinSizeRel`` build type or configuration.
+This variable is the ``MinSizeRel`` variant of the
-
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable.
-``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``MinSizeRel``
-(short for minimum size release).

Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst

@@ -1,10 +1,5 @@
 CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT
 ----------------------------------
 
-Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL`
+This variable is the ``MinSizeRel`` variant of the
-cache entry the first time a build tree is configured for language ``<LANG>``.
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable.
-This variable is meant to be set by a :variable:`toolchain file
-<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
-the value based on the environment and target platform.
-
-See also :variable:`CMAKE_<LANG>_FLAGS_INIT`.

Help/variable/CMAKE_LANG_FLAGS_RELEASE.rst

@@ -1,6 +1,5 @@
 CMAKE_<LANG>_FLAGS_RELEASE
 --------------------------
 
-Flags for ``Release`` build type or configuration.
+This variable is the ``Release`` variant of the
-
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable.
-``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``Release``.

Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst

@@ -1,10 +1,5 @@
 CMAKE_<LANG>_FLAGS_RELEASE_INIT
 -------------------------------
 
-Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELEASE`
+This variable is the ``Release`` variant of the
-cache entry the first time a build tree is configured for language ``<LANG>``.
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable.
-This variable is meant to be set by a :variable:`toolchain file
-<CMAKE_TOOLCHAIN_FILE>`.  CMake may prepend or append content to
-the value based on the environment and target platform.
-
-See also :variable:`CMAKE_<LANG>_FLAGS_INIT`.

Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO.rst

@@ -1,7 +1,5 @@
 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
 ---------------------------------
 
-Flags for ``RelWithDebInfo`` type or configuration.
+This variable is the ``RelWithDebInfo`` variant of the
-
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable.
-``<LANG>`` flags used when :variable:`CMAKE_BUILD_TYPE` is ``RelWithDebInfo``
-(short for Release With Debug Information).