CMake origin/3.3.0 merged.

Auxiliary/bash-completion/cmake

@@ -3,7 +3,14 @@
 _cmake()
 {
     local cur prev words cword split=false
-    _init_completion -n := || return
+    if type -t _init_completion >/dev/null; then
+        _init_completion -n = || return
+    else
+        # manual initialization for older bash completion versions
+        COMPREPLY=()
+        cur="${COMP_WORDS[COMP_CWORD]}"
+        prev="${COMP_WORDS[COMP_CWORD-1]}"
+    fi
 
     # Workaround for options like -DCMAKE_BUILD_TYPE=Release
     local prefix=

Auxiliary/bash-completion/cpack

@@ -3,7 +3,14 @@
 _cpack()
 {
     local cur prev words cword
-    _init_completion -n = || return
+    if type -t _init_completion >/dev/null; then
+        _init_completion -n = || return
+    else
+        # manual initialization for older bash completion versions
+        COMPREPLY=()
+        cur="${COMP_WORDS[COMP_CWORD]}"
+        prev="${COMP_WORDS[COMP_CWORD-1]}"
+    fi
 
     case "$prev" in
         -G)

Auxiliary/bash-completion/ctest

@@ -3,7 +3,14 @@
 _ctest()
 {
     local cur prev words cword
-    _init_completion -n = || return
+    if type -t _init_completion >/dev/null; then
+        _init_completion -n = || return
+    else
+        # manual initialization for older bash completion versions
+        COMPREPLY=()
+        cur="${COMP_WORDS[COMP_CWORD]}"
+        prev="${COMP_WORDS[COMP_CWORD-1]}"
+    fi
 
     case "$prev" in
         -C|--build-config)

CMakeCPackOptions.cmake.in

@@ -38,6 +38,10 @@ if(CPACK_GENERATOR MATCHES "IFW")
   @_CPACK_IFW_PACKAGE_ICON@
   set(CPACK_IFW_PACKAGE_WINDOW_ICON
     "@CMake_SOURCE_DIR@/Source/QtDialog/CMakeSetup128.png")
+  set(CPACK_IFW_PACKAGE_CONTROL_SCRIPT
+    "@CMake_SOURCE_DIR@/Source/QtIFW/controlscript.qs")
+  # Uninstaller configuration
+  set(CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME "cmake-maintenance")
   # Package configuration group
   set(CPACK_IFW_PACKAGE_GROUP CMake)
   # Group configuration
@@ -87,4 +91,34 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
   if(patch MATCHES "^[0-9]+$" AND patch LESS 65535)
     set(CPACK_PACKAGE_VERSION "${CPACK_PACKAGE_VERSION}.${patch}")
   endif()
+
+  set(CPACK_WIX_PROPERTY_ARPURLINFOABOUT "http://www.cmake.org")
+
+  set(CPACK_WIX_PROPERTY_ARPCONTACT "@CPACK_PACKAGE_CONTACT@")
+
+  set(CPACK_WIX_PROPERTY_ARPCOMMENTS
+    "CMake is a cross-platform, open-source build system."
+  )
+
+  set(CPACK_WIX_PRODUCT_ICON
+    "@CMake_SOURCE_DIR@/Utilities/Release/CMakeLogo.ico"
+  )
+
+  set_property(INSTALL "@CMAKE_DOC_DIR@/html/index.html" PROPERTY
+    CPACK_START_MENU_SHORTCUTS "CMake Documentation"
+  )
+
+  set_property(INSTALL "cmake.org.html" PROPERTY
+    CPACK_START_MENU_SHORTCUTS "CMake Web Site"
+  )
+
+  set(CPACK_WIX_LIGHT_EXTRA_FLAGS "-dcl:high")
+
+  set(CPACK_WIX_UI_BANNER
+    "@CMake_SOURCE_DIR@/Utilities/Release/cpack_wix_ui_banner.jpg"
+  )
+
+  set(CPACK_WIX_UI_DIALOG
+    "@CMake_SOURCE_DIR@/Utilities/Release/cpack_wix_ui_dialog.jpg"
+  )
 endif()

CMakeLists.txt

@@ -37,11 +37,19 @@ if("${CMake_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
 endif()
 
 # Use most-recent available language dialects with GNU and Clang
-if(NOT DEFINED CMAKE_C_STANDARD)
+if(NOT DEFINED CMAKE_C_STANDARD AND NOT CMake_NO_C_STANDARD)
   set(CMAKE_C_STANDARD 11)
 endif()
-if(NOT DEFINED CMAKE_CXX_STANDARD)
+if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
-  set(CMAKE_CXX_STANDARD 14)
+  include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx14_cstdio.cmake)
+  if(NOT CMake_CXX14_CSTDIO_BROKEN)
+    set(CMAKE_CXX_STANDARD 14)
+  else()
+    set(CMAKE_CXX_STANDARD 11)
+  endif()
+endif()
+if(NOT CMake_TEST_EXTERNAL_CMAKE)
+  include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx11_unordered_map.cmake)
 endif()
 
 # option to set the internal encoding of CMake to UTF-8
@@ -543,10 +551,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
         "${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}")
       set(CMAKE_BUNDLE_LOCATION "${CMAKE_INSTALL_PREFIX}")
       # make sure CMAKE_INSTALL_PREFIX ends in /
-      string(LENGTH "${CMAKE_INSTALL_PREFIX}" LEN)
+      if(NOT CMAKE_INSTALL_PREFIX MATCHES "/$")
-      math(EXPR LEN "${LEN} -1" )
-      string(SUBSTRING "${CMAKE_INSTALL_PREFIX}" ${LEN} 1 ENDCH)
-      if(NOT "${ENDCH}" STREQUAL "/")
         set(CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}/")
       endif()
       set(CMAKE_INSTALL_PREFIX

CTestCustom.cmake.in

@@ -33,8 +33,11 @@ set(CTEST_CUSTOM_WARNING_EXCEPTION
   "warning .980: wrong number of actual arguments to intrinsic function .std::basic_"
   "LINK : warning LNK4089: all references to.*ADVAPI32.dll.*discarded by /OPT:REF"
   "LINK : warning LNK4089: all references to.*PSAPI.DLL.*discarded by /OPT:REF"
+  "LINK : warning LNK4089: all references to.*RPCRT4.dll.*discarded by /OPT:REF"
   "LINK : warning LNK4089: all references to.*SHELL32.dll.*discarded by /OPT:REF"
   "LINK : warning LNK4089: all references to.*USER32.dll.*discarded by /OPT:REF"
+  "LINK : warning LNK4089: all references to.*ole32.dll.*discarded by /OPT:REF"
+  "Warning.*: .*/Utilities/KWIML/test/test_INT_format.h.* # Redundant preprocessing concatenation"
   "Warning: library was too large for page size.*"
   "Warning: public.*_archive_.*in module.*archive_*clashes with prior module.*archive_.*"
   "Warning: public.*BZ2_bz.*in module.*bzlib.*clashes with prior module.*bzlib.*"
@@ -53,6 +56,9 @@ set(CTEST_CUSTOM_WARNING_EXCEPTION
   "CMakeSetupManifest.xml.*manifest authoring warning.*Unrecognized Element"
   "cc-3968 CC: WARNING File.*" # "implicit" truncation by static_cast
   "ld: warning: directory not found for option .-(F|L)"
+  "ld: warning .*/libgcc.a archive's cputype"
+  "ld: warning: ignoring file .*/libgcc.a, file was built for archive which is not the architecture being linked"
+  "ld: warning: in .*/libgcc.a, file is not of required architecture"
   "warning.*This version of Mac OS X is unsupported"
   "clang.*: warning: argument unused during compilation: .-g"
   "note: in expansion of macro" # diagnostic context note
@@ -62,6 +68,18 @@ set(CTEST_CUSTOM_WARNING_EXCEPTION
   # Ignore clang's summary warning, assuming prior text has matched some
   # other warning expression:
   "[0-9,]+ warnings? generated."
+
+# scanbuild exceptions
+  "char_traits.h:.*: warning: Null pointer argument in call to string length function"
+  "stl_construct.h:.*: warning: Forming reference to null pointer"
+  ".*stl_uninitialized.h:75:19: warning: Forming reference to null pointer.*"
+  ".*stl_vector.h:.*: warning: Returning null reference.*"
+  "warning: Value stored to 'yymsg' is never read"
+  "warning: Value stored to 'yytoken' is never read"
+  "index_encoder.c.241.2. warning: Value stored to .out_start. is never read"
+  "index.c.*warning: Access to field.*results in a dereference of a null pointer.*loaded from variable.*"
+  "cm_sha2.*warning: Value stored to.*is never read"
+  "testProcess.*warning: Dereference of null pointer .loaded from variable .invalidAddress.."
   )
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")

Help/command/FIND_XXX.txt

@@ -53,6 +53,10 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows:
 .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
    <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH
 
+.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
+   <prefix>/|XXX_SUBDIR| for each <prefix>/[s]bin in PATH, and
+   <entry>/|XXX_SUBDIR| for other entries in PATH
+
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
    <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
 

Help/command/add_custom_command.rst

@@ -79,6 +79,9 @@ The options are:
   If ``COMMAND`` specifies an executable target (created by the
   :command:`add_executable` command) it will automatically be replaced
   by the location of the executable created at build time.
+  (Use the ``TARGET_FILE``
+  :manual:`generator expression <cmake-generator-expressions(7)>` to
+  reference an executable later in the command line.)
   Additionally a target-level dependency will be added so that the
   executable target will be built before any target using this custom
   command.  However this does NOT add a file-level dependency that

Help/command/add_dependencies.rst

@@ -7,13 +7,17 @@ Add a dependency between top-level targets.
 
   add_dependencies(<target> [<target-dependency>]...)
 
-Make a top-level <target> depend on other top-level targets to ensure
+Make a top-level ``<target>`` depend on other top-level targets to
-that they build before <target> does.  A top-level target is one
+ensure that they build before ``<target>`` does.  A top-level target
-created by ADD_EXECUTABLE, ADD_LIBRARY, or ADD_CUSTOM_TARGET.
+is one created by one of the :command:`add_executable`,
-Dependencies added to an IMPORTED target are followed transitively in
+:command:`add_library`, or :command:`add_custom_target` commands
-its place since the target itself does not build.
+(but not targets generated by CMake like ``install``).
 
-See the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND for
+Dependencies added to an :ref:`imported target <Imported Targets>`
-adding file-level dependencies in custom rules.  See the
+or an :ref:`interface library <Interface Libraries>` are followed
-OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add file-level
+transitively in its place since the target itself does not build.
-dependencies to object files.
+
+See the ``DEPENDS`` option of :command:`add_custom_target` and
+:command:`add_custom_command` commands for adding file-level
+dependencies in custom rules.  See the :prop_sf:`OBJECT_DEPENDS`
+source file property to add file-level dependencies to object files.

Help/command/build_command.rst

@@ -19,7 +19,8 @@ Sets the given ``<variable>`` to a command-line string of the form::
 where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
 tool, and ``<config>`` and ``<target>`` are the values provided to the
 ``CONFIGURATION`` and ``TARGET`` options, if any.  The trailing ``-- -i``
-option is added for Makefile generators.
+option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061`
+is not set to ``NEW``.
 
 When invoked, this ``cmake --build`` command line will launch the
 underlying build system tool.
@@ -32,7 +33,7 @@ This second signature is deprecated, but still available for backwards
 compatibility.  Use the first signature instead.
 
 It sets the given ``<cachevariable>`` to a command-line string as
-above but without the ``--config`` or ``--target`` options.
+above but without the ``--target`` option.
 The ``<makecommand>`` is ignored but should be the full path to
 msdev, devenv, nmake, make or one of the end user build tools
 for legacy invocations.

Help/command/cmake_minimum_required.rst

@@ -28,3 +28,14 @@ which enables compatibility features for CMake 2.4 and lower.
 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
 higher.  It should be specified so CMake versions 2.4 and lower fail
 with an error instead of just a warning.
+
+.. note::
+  Call the ``cmake_minimum_required()`` command at the beginning of
+  the top-level ``CMakeLists.txt`` file even before calling the
+  :command:`project` command.  It is important to establish version
+  and policy settings before invoking other commands whose behavior
+  they may affect.  See also policy :policy:`CMP0000`.
+
+  Calling ``cmake_minimum_required()`` inside a :command:`function`
+  limits some effects to the function scope when invoked.  Such calls
+  should not be made with the intention of having global effects.

Help/command/cmake_policy.rst

@@ -53,6 +53,8 @@ policy warning by setting the policy state to ``OLD``.  Alternatively
 one may fix the project to work with the new behavior and set the
 policy state to ``NEW``.
 
+.. include:: ../policy/DEPRECATED.txt
+
 Checking Policy Settings
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/command/ctest_build.rst

@@ -1,29 +1,73 @@
 ctest_build
 -----------
 
-Build the project.
+Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]
+  ctest_build([BUILD <build-dir>] [APPEND]
-              [APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val])
+              [CONFIGURATION <config>]
+              [FLAGS <flags>]
+              [PROJECT_NAME <project-name>]
+              [TARGET <target-name>]
+              [NUMBER_ERRORS <num-err-var>]
+              [NUMBER_WARNINGS <num-warn-var>]
+              [RETURN_VALUE <result-var>]
+              )
 
-Builds the given build directory and stores results in Build.xml.  If
+Build the project and store results in ``Build.xml``
-no BUILD is given, the CTEST_BINARY_DIRECTORY variable is used.
+for submission with the :command:`ctest_submit` command.
 
-The TARGET variable can be used to specify a build target.  If none is
+The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
-specified, the "all" target will be built.
+specify the build command line.  Otherwise the build command line is
+computed automatically based on the options given.
 
-The RETURN_VALUE option specifies a variable in which to store the
+The options are:
-return value of the native build tool.  The NUMBER_ERRORS and
-NUMBER_WARNINGS options specify variables in which to store the number
-of build errors and warnings detected.
 
-The APPEND option marks results for append to those previously
+``BUILD <build-dir>``
-submitted to a dashboard server since the last ctest_start.  Append
+  Specify the top-level build directory.  If not given, the
-semantics are defined by the dashboard server in use.
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
 
-If set, the contents of the variable CTEST_BUILD_FLAGS are passed as
+``APPEND``
-additional arguments to the underlying build command. This can e.g. be
+  Mark results for append to those previously submitted to a
-used to trigger a parallel build using the -j option of make. See
+  dashboard server since the last :command:`ctest_start` call.
-:module:`ProcessorCount` for an example.
+  Append semantics are defined by the dashboard server in use.
+
+``CONFIGURATION <config>``
+  Specify the build configuration (e.g. ``Debug``).  If not
+  specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
+  Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
+  command will be used, if any.
+
+``FLAGS <flags>``
+  Pass additional arguments to the underlying build command.
+  If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
+  This can, e.g., be used to trigger a parallel build using the
+  ``-j`` option of make. See the :module:`ProcessorCount` module
+  for an example.
+
+``PROJECT_NAME <project-name>``
+  Set the name of the project to build.  This should correspond
+  to the top-level call to the :command:`project` command.
+  If not specified the ``CTEST_PROJECT_NAME`` variable will be checked.
+
+``TARGET <target-name>``
+  Specify the name of a target to build.  If not specified the
+  ``CTEST_BUILD_TARGET`` variable will be checked.  Otherwise the
+  default target will be built.  This is the "all" target
+  (called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
+
+``NUMBER_ERRORS <num-err-var>``
+  Store the number of build errors detected in the given variable.
+
+``NUMBER_WARNINGS <num-warn-var>``
+  Store the number of build warnings detected in the given variable.
+
+``RETURN_VALUE <result-var>``
+  Store the return value of the native build tool in the given variable.
+
+``QUIET``
+  Suppress any CTest-specific non-error output that would have been
+  printed to the console otherwise.  The summary of warnings / errors,
+  as well as the output from the native build tool is unaffected by
+  this option.

Help/command/ctest_configure.rst

@@ -1,21 +1,39 @@
 ctest_configure
 ---------------
 
-Configure the project build tree.
+Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND]
+  ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
-                  [OPTIONS options] [RETURN_VALUE res])
+                  [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET])
 
-Configures the given build directory and stores results in
+Configure the project build tree and record results in ``Configure.xml``
-Configure.xml.  If no BUILD is given, the CTEST_BINARY_DIRECTORY
+for submission with the :command:`ctest_submit` command.
-variable is used.  If no SOURCE is given, the CTEST_SOURCE_DIRECTORY
-variable is used.  The OPTIONS argument specifies command line
-arguments to pass to the configuration tool.  The RETURN_VALUE option
-specifies a variable in which to store the return value of the native
-build tool.
 
-The APPEND option marks results for append to those previously
+The options are:
-submitted to a dashboard server since the last ctest_start.  Append
+
-semantics are defined by the dashboard server in use.
+``BUILD <build-dir>``
+  Specify the top-level build directory.  If not given, the
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
+
+``SOURCE <source-dir>``
+  Specify the source directory.  If not given, the
+  :variable:`CTEST_SOURCE_DIRECTORY` variable is used.
+
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
+
+``OPTIONS <options>``
+  Specify command-line arguments to pass to the configuration tool.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable the return value of the native
+  configuration tool.
+
+``QUIET``
+  Suppress any CTest-specific non-error messages that would have
+  otherwise been printed to the console.  Output from the underlying
+  configure command is not affected.

Help/command/ctest_coverage.rst

@@ -1,20 +1,39 @@
 ctest_coverage
 --------------
 
-Collect coverage tool results.
+Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]
+  ctest_coverage([BUILD <build-dir>] [APPEND]
-                 [LABELS label1 [label2 [...]]])
+                 [LABELS <label>...]
+                 [RETURN_VALUE <result-var>]
+                 [QUIET]
+                 )
 
-Perform the coverage of the given build directory and stores results
+Collect coverage tool results and stores them in ``Coverage.xml``
-in Coverage.xml.  The second argument is a variable that will hold
+for submission with the :command:`ctest_submit` command.
-value.
 
-The LABELS option filters the coverage report to include only source
+The options are:
-files labeled with at least one of the labels specified.
 
-The APPEND option marks results for append to those previously
+``BUILD <build-dir>``
-submitted to a dashboard server since the last ctest_start.  Append
+  Specify the top-level build directory.  If not given, the
-semantics are defined by the dashboard server in use.
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
+
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
+
+``LABELS``
+  Filter the coverage report to include only source files labeled
+  with at least one of the labels specified.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable ``0`` if coverage tools
+  ran without error and non-zero otherwise.
+
+``QUIET``
+  Suppress any CTest-specific non-error output that would have been
+  printed to the console otherwise.  The summary indicating how many
+  lines of code were covered is unaffected by this option.

Help/command/ctest_memcheck.rst

@@ -1,28 +1,28 @@
 ctest_memcheck
 --------------
 
-Run tests with a dynamic analysis tool.
+Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND]
+  ctest_memcheck([BUILD <build-dir>] [APPEND]
-             [START start number] [END end number]
+                 [START <start-number>]
-             [STRIDE stride number] [EXCLUDE exclude regex ]
+                 [END <end-number>]
-             [INCLUDE include regex]
+                 [STRIDE <stride-number>]
-             [EXCLUDE_LABEL exclude regex]
+                 [EXCLUDE <exclude-regex>]
-             [INCLUDE_LABEL label regex]
+                 [INCLUDE <include-regex>]
-             [PARALLEL_LEVEL level] )
+                 [EXCLUDE_LABEL <label-exclude-regex>]
+                 [INCLUDE_LABEL <label-include-regex>]
+                 [PARALLEL_LEVEL <level>]
+                 [SCHEDULE_RANDOM <ON|OFF>]
+                 [STOP_TIME <time-of-day>]
+                 [RETURN_VALUE <result-var>]
+                 [QUIET]
+                 )
 
-Tests the given build directory and stores results in MemCheck.xml.
-The second argument is a variable that will hold value.  Optionally,
-you can specify the starting test number START, the ending test number
-END, the number of tests to skip between each test STRIDE, a regular
-expression for tests to run INCLUDE, or a regular expression for tests
-not to run EXCLUDE.  EXCLUDE_LABEL and INCLUDE_LABEL are regular
-expressions for tests to be included or excluded by the test property
-LABEL.  PARALLEL_LEVEL should be set to a positive number representing
-the number of tests to be run in parallel.
 
-The APPEND option marks results for append to those previously
+Run tests with a dynamic analysis tool and store results in
-submitted to a dashboard server since the last ctest_start.  Append
+``MemCheck.xml`` for submission with the :command:`ctest_submit`
-semantics are defined by the dashboard server in use.
+command.
+
+The options are the same as those for the :command:`ctest_test` command.

Help/command/ctest_start.rst

@@ -5,7 +5,7 @@ Starts the testing for a given model
 
 ::
 
-  ctest_start(Model [TRACK <track>] [APPEND] [source [binary]])
+  ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET])
 
 Starts the testing for a given model.  The command should be called
 after the binary directory is initialized.  If the 'source' and
@@ -14,7 +14,8 @@ after the binary directory is initialized.  If the 'source' and
 If the track is
 specified, the submissions will go to the specified track.  If APPEND
 is used, the existing TAG is used rather than creating a new one based
-on the current time stamp.
+on the current time stamp.  If QUIET is used, CTest will suppress any
+non-error messages that it otherwise would have printed to the console.
 
 If the :variable:`CTEST_CHECKOUT_COMMAND` variable
 (or the :variable:`CTEST_CVS_CHECKOUT` variable)

Help/command/ctest_submit.rst

@@ -1,42 +1,55 @@
 ctest_submit
 ------------
 
-Submit results to a dashboard server.
+Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_submit([PARTS ...] [FILES ...]
+  ctest_submit([PARTS <part>...] [FILES <file>...]
-               [RETRY_COUNT count]
+               [RETRY_COUNT <count>]
-               [RETRY_DELAY delay]
+               [RETRY_DELAY <delay>]
-               [RETURN_VALUE res]
+               [RETURN_VALUE <result-var>]
+               [QUIET]
                )
 
-By default all available parts are submitted if no PARTS or FILES are
+Submit results to a dashboard server.
-specified.  The PARTS option lists a subset of parts to be submitted.
+By default all available parts are submitted.
-Valid part names are:
 
-::
+The options are:
 
-  Start      = nothing
+``PARTS <part>...``
-  Update     = ctest_update results, in Update.xml
+  Specify a subset of parts to submit.  Valid part names are::
-  Configure  = ctest_configure results, in Configure.xml
-  Build      = ctest_build results, in Build.xml
-  Test       = ctest_test results, in Test.xml
-  Coverage   = ctest_coverage results, in Coverage.xml
-  MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
-  Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
-  ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
-  Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
-  Submit     = nothing
 
-The FILES option explicitly lists specific files to be submitted.
+    Start      = nothing
-Each individual file must exist at the time of the call.
+    Update     = ctest_update results, in Update.xml
+    Configure  = ctest_configure results, in Configure.xml
+    Build      = ctest_build results, in Build.xml
+    Test       = ctest_test results, in Test.xml
+    Coverage   = ctest_coverage results, in Coverage.xml
+    MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
+    Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
+    ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
+    Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
+    Submit     = nothing
 
-The RETRY_DELAY option specifies how long in seconds to wait after a
+``FILES <file>...``
-timed-out submission before attempting to re-submit.
+  Specify an explicit list of specific files to be submitted.
+  Each individual file must exist at the time of the call.
 
-The RETRY_COUNT option specifies how many times to retry a timed-out
+``RETRY_COUNT <count>``
-submission.
+  Specify how many times to retry a timed-out submission.
+
+``RETRY_DELAY <delay>``
+  Specify how long (in seconds) to wait after a timed-out submission
+  before attempting to re-submit.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable ``0`` for success and
+  non-zero on failure.
+
+``QUIET``
+  Suppress all non-error messages that would have otherwise been
+  printed to the console.
 
 Submit to CDash Upload API
 ^^^^^^^^^^^^^^^^^^^^^^^^^^

Help/command/ctest_test.rst

@@ -1,33 +1,79 @@
 ctest_test
 ----------
 
-Run tests in the project build tree.
+Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_test([BUILD build_dir] [APPEND]
+  ctest_test([BUILD <build-dir>] [APPEND]
-             [START start number] [END end number]
+             [START <start-number>]
-             [STRIDE stride number] [EXCLUDE exclude regex ]
+             [END <end-number>]
-             [INCLUDE include regex] [RETURN_VALUE res]
+             [STRIDE <stride-number>]
-             [EXCLUDE_LABEL exclude regex]
+             [EXCLUDE <exclude-regex>]
-             [INCLUDE_LABEL label regex]
+             [INCLUDE <include-regex>]
-             [PARALLEL_LEVEL level]
+             [EXCLUDE_LABEL <label-exclude-regex>]
-             [SCHEDULE_RANDOM on]
+             [INCLUDE_LABEL <label-include-regex>]
-             [STOP_TIME time of day])
+             [PARALLEL_LEVEL <level>]
+             [SCHEDULE_RANDOM <ON|OFF>]
+             [STOP_TIME <time-of-day>]
+             [RETURN_VALUE <result-var>]
+             [QUIET]
+             )
 
-Tests the given build directory and stores results in Test.xml.  The
+Run tests in the project build tree and store results in
-second argument is a variable that will hold value.  Optionally, you
+``Test.xml`` for submission with the :command:`ctest_submit` command.
-can specify the starting test number START, the ending test number
-END, the number of tests to skip between each test STRIDE, a regular
-expression for tests to run INCLUDE, or a regular expression for tests
-to not run EXCLUDE.  EXCLUDE_LABEL and INCLUDE_LABEL are regular
-expression for test to be included or excluded by the test property
-LABEL.  PARALLEL_LEVEL should be set to a positive number representing
-the number of tests to be run in parallel.  SCHEDULE_RANDOM will
-launch tests in a random order, and is typically used to detect
-implicit test dependencies.  STOP_TIME is the time of day at which the
-tests should all stop running.
 
-The APPEND option marks results for append to those previously
+The options are:
-submitted to a dashboard server since the last ctest_start.  Append
+
-semantics are defined by the dashboard server in use.
+``BUILD <build-dir>``
+  Specify the top-level build directory.  If not given, the
+  :variable:`CTEST_BINARY_DIRECTORY` variable is used.
+
+``APPEND``
+  Mark results for append to those previously submitted to a
+  dashboard server since the last :command:`ctest_start` call.
+  Append semantics are defined by the dashboard server in use.
+
+``START <start-number>``
+  Specify the beginning of a range of test numbers.
+
+``END <end-number>``
+  Specify the end of a range of test numbers.
+
+``STRIDE <stride-number>``
+  Specify the stride by which to step acorss a range of test numbers.
+
+``EXCLUDE <exclude-regex>``
+  Specify a regular expression matching test names to exclude.
+
+``INCLUDE <include-regex>``
+  Specify a regular expression matching test names to include.
+  Tests not matching this expression are excluded.
+
+``EXCLUDE_LABEL <label-exclude-regex>``
+  Specify a regular expression matching test labels to exclude.
+
+``INCLUDE_LABEL <label-include-regex>``
+  Specify a regular expression matching test labels to include.
+  Tests not matching this expression are excluded.
+
+``PARALLEL_LEVEL <level>``
+  Specify a positive number representing the number of tests to
+  be run in parallel.
+
+``SCHEDULE_RANDOM <ON|OFF>``
+  Launch tests in a random order.  This may be useful for detecting
+  implicit test dependencies.
+
+``STOP_TIME <time-of-day>``
+  Specify a time of day at which the tests should all stop running.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable ``0`` if all tests passed.
+  Store non-zero if anything went wrong.
+
+``QUIET``
+  Suppress any CTest-specific non-error messages that would have otherwise
+  been printed to the console.  Output from the underlying test command is not
+  affected.  Summary info detailing the percentage of passing tests is also
+  unaffected by the ``QUIET`` option.

Help/command/ctest_update.rst

@@ -1,13 +1,27 @@
 ctest_update
 ------------
 
-Update the work tree from version control.
+Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_update([SOURCE source] [RETURN_VALUE res])
+  ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET])
 
-Updates the given source directory and stores results in Update.xml.
+Update the source tree from version control and record results in
-If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used.
+``Update.xml`` for submission with the :command:`ctest_submit` command.
-The RETURN_VALUE option specifies a variable in which to store the
+
-result, which is the number of files updated or -1 on error.
+The options are:
+
+``SOURCE <source-dir>``
+  Specify the source directory.  If not given, the
+  :variable:`CTEST_SOURCE_DIRECTORY` variable is used.
+
+``RETURN_VALUE <result-var>``
+  Store in the ``<result-var>`` variable the number of files
+  updated or ``-1`` on error.
+
+``QUIET``
+  Tell CTest to suppress most non-error messages that it would
+  have otherwise printed to the console.  CTest will still report
+  the new revision of the repository and any conflicting files
+  that were found.

Help/command/ctest_upload.rst

@@ -1,11 +1,18 @@
 ctest_upload
 ------------
 
-Upload files to a dashboard server.
+Upload files to a dashboard server as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_upload(FILES ...)
+  ctest_upload(FILES <file>... [QUIET])
 
-Pass a list of files to be sent along with the build results to the
+The options are:
-dashboard server.
+
+``FILES <file>...``
+  Specify a list of files to be sent along with the build results to the
+  dashboard server.
+
+``QUIET``
+  Suppress any CTest-specific non-error output that would have been
+  printed to the console otherwise.

Help/command/execute_process.rst

@@ -57,7 +57,8 @@ OUTPUT_VARIABLE, ERROR_VARIABLE
 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
  The file named will be attached to the standard input of the first
  process, standard output of the last process, or standard error of
- all processes, respectively.
+ all processes, respectively.  If the same file is named for both
+ output and error then it will be used for both.
 
 OUTPUT_QUIET, ERROR_QUIET
  The standard output or standard error results will be quietly ignored.

Help/command/file.rst

@@ -92,9 +92,12 @@ store it in a ``<variable>``.
 
 ::
 
-  file(GLOB <variable> [RELATIVE <path>] [<globbing-expressions>...])
+  file(GLOB <variable>
-  file(GLOB_RECURSE <variable> [RELATIVE <path>]
+       [LIST_DIRECTORIES true|false] [RELATIVE <path>]
-       [FOLLOW_SYMLINKS] [<globbing-expressions>...])
+       [<globbing-expressions>...])
+  file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
+       [LIST_DIRECTORIES true|false] [RELATIVE <path>]
+       [<globbing-expressions>...])
 
 Generate a list of files that match the ``<globbing-expressions>`` and
 store it into the ``<variable>``.  Globbing expressions are similar to
@@ -102,6 +105,9 @@ regular expressions, but much simpler.  If ``RELATIVE`` flag is
 specified, the results will be returned as relative paths to the given
 path.
 
+By default ``GLOB`` lists directories - directories are omited in result if
+``LIST_DIRECTORIES`` is set to false.
+
 .. note::
   We do not recommend using GLOB to collect a list of source files from
   your source tree.  If no CMakeLists.txt file changes when a source is
@@ -119,6 +125,11 @@ matched directory and match the files.  Subdirectories that are symlinks
 are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
 :policy:`CMP0009` is not set to ``NEW``.
 
+By default ``GLOB_RECURSE`` omits directories from result list - setting
+``LIST_DIRECTORIES`` to true adds directories to result list.
+If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
+``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
+
 Examples of recursive globbing include::
 
   /dir/*.py  - match all python files in /dir and subdirectories
@@ -302,8 +313,12 @@ preserves input file timestamps, and optimizes out a file if it exists
 at the destination with the same timestamp.  Copying preserves input
 permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
 are given (default is ``USE_SOURCE_PERMISSIONS``).
+
 See the :command:`install(DIRECTORY)` command for documentation of
-permissions, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options.
+permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
+``EXCLUDE`` options.  Copying directories preserves the structure
+of their content even if options are used to select a subset of
+files.
 
 The ``INSTALL`` signature differs slightly from ``COPY``: it prints
 status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),

Help/command/find_file.rst

@@ -13,7 +13,10 @@ find_file
 .. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
 .. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
+   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+   |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
+   and the directories in PATH itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and

Help/command/find_library.rst

@@ -13,7 +13,10 @@ find_library
 .. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH
 .. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and LIB
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in LIB,
+   <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+   |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
+   and the directories in PATH itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
@@ -31,6 +34,12 @@ default will consider one name at a time and search every directory
 for it.  The NAMES_PER_DIR option tells this command to consider one
 directory at a time and search for all names in it.
 
+Each library name given to the ``NAMES`` option is first considered
+as a library file name and then considered with platform-specific
+prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``).  Therefore one
+may specify library file names such as ``libfoo.a`` directly.
+This can be used to locate static libraries on UNIX-like systems.
+
 If the library found is a framework, then VAR will be set to the full
 path to the framework <fullPath>/A.framework.  When a full path to a
 framework is used as a library, CMake will use a -framework A, and a

Help/command/find_package.rst

@@ -68,7 +68,7 @@ The complete Config mode command signature is::
                [NO_CMAKE_PATH]
                [NO_SYSTEM_ENVIRONMENT_PATH]
                [NO_CMAKE_PACKAGE_REGISTRY]
-               [NO_CMAKE_BUILDS_PATH]
+               [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
                [NO_CMAKE_SYSTEM_PATH]
                [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
                [CMAKE_FIND_ROOT_PATH_BOTH |
@@ -265,20 +265,14 @@ enabled.
 
      PATH
 
-5. Search project build trees recently configured in a :manual:`cmake-gui(1)`.
+5. Search paths stored in the CMake :ref:`User Package Registry`.
-   This can be skipped if ``NO_CMAKE_BUILDS_PATH`` is passed.  It is intended
-   for the case when a user is building multiple dependent projects one
-   after another.
-   (This step is implemented only on Windows.)
-
-6. Search paths stored in the CMake :ref:`User Package Registry`.
    This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
    setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
    to ``TRUE``.
    See the :manual:`cmake-packages(7)` manual for details on the user
    package registry.
 
-7. Search cmake variables defined in the Platform files for the
+6. Search cmake variables defined in the Platform files for the
    current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
    passed::
 
@@ -286,14 +280,14 @@ enabled.
      CMAKE_SYSTEM_FRAMEWORK_PATH
      CMAKE_SYSTEM_APPBUNDLE_PATH
 
-8. Search paths stored in the CMake :ref:`System Package Registry`.
+7. Search paths stored in the CMake :ref:`System Package Registry`.
    This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
    or by setting the
    :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
    See the :manual:`cmake-packages(7)` manual for details on the system
    package registry.
 
-9. Search paths specified by the ``PATHS`` option.  These are typically
+8. Search paths specified by the ``PATHS`` option.  These are typically
    hard-coded guesses.
 
 .. |FIND_XXX| replace:: find_package

Help/command/find_path.rst

@@ -13,7 +13,10 @@ find_path
 .. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
 .. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
+   <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+   |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
+   and the directories in PATH itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and

Help/command/function.rst

@@ -1,9 +1,7 @@
 function
 --------
 
-Start recording a function for later invocation as a command.
+Start recording a function for later invocation as a command::
-
-::
 
   function(<name> [arg1 [arg2 [arg3 ...]]])
     COMMAND1(ARGS ...)
@@ -11,21 +9,28 @@ Start recording a function for later invocation as a command.
     ...
   endfunction(<name>)
 
-Define a function named <name> that takes arguments named arg1 arg2
+Define a function named ``<name>`` that takes arguments named ``arg1``,
-arg3 (...).  Commands listed after function, but before the matching
+``arg2``, ``arg3``, (...).
-endfunction, are not invoked until the function is invoked.  When it
+Commands listed after function, but before the matching
-is invoked, the commands recorded in the function are first modified
+:command:`endfunction()`, are not invoked until the function is invoked.
-by replacing formal parameters (${arg1}) with the arguments passed,
+When it is invoked, the commands recorded in the function are first
-and then invoked as normal commands.  In addition to referencing the
+modified by replacing formal parameters (``${arg1}``) with the arguments
-formal parameters you can reference the variable ARGC which will be
+passed, and then invoked as normal commands.
-set to the number of arguments passed into the function as well as
+In addition to referencing the formal parameters you can reference the
-ARGV0 ARGV1 ARGV2 ...  which will have the actual values of the
+``ARGC`` variable which will be set to the number of arguments passed
-arguments passed in.  This facilitates creating functions with
+into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ...  which
-optional arguments.  Additionally ARGV holds the list of all arguments
+will have the actual values of the arguments passed in.
-given to the function and ARGN holds the list of arguments past the
+This facilitates creating functions with optional arguments.
-last expected argument.
+Additionally ``ARGV`` holds the list of all arguments given to the
+function and ``ARGN`` holds the list of arguments past the last expected
+argument.
+Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined
+behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
+to ensure that ``ARGV#`` was passed to the function as an extra
+argument.
 
-A function opens a new scope: see set(var PARENT_SCOPE) for details.
+A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
+details.
 
-See the cmake_policy() command documentation for the behavior of
+See the :command:`cmake_policy()` command documentation for the behavior
-policies inside functions.
+of policies inside functions.

Help/command/if.rst

@@ -134,6 +134,9 @@ Possible expressions are:
  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``).
 
+``if(<variable|string> IN_LIST <variable>)``
+ True if the given element is contained in the named list variable.
+
 ``if(DEFINED <variable>)``
  True if the given variable is defined.  It does not matter if the
  variable is true or false just if it has been set.  (Note macro

Help/command/install.rst

@@ -159,6 +159,10 @@ file itself, call ``install(EXPORT)``, documented below.
 Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
 set to ``TRUE`` has undefined behavior.
 
+The install destination given to the target install ``DESTINATION`` may
+use "generator expressions" with the syntax ``$<...>``.  See the
+:manual:`cmake-generator-expressions(7)` manual for available expressions.
+
 Installing Files
 ^^^^^^^^^^^^^^^^
 

Help/command/macro.rst

@@ -1,9 +1,7 @@
 macro
 -----
 
-Start recording a macro for later invocation as a command.
+Start recording a macro for later invocation as a command::
-
-::
 
   macro(<name> [arg1 [arg2 [arg3 ...]]])
     COMMAND1(ARGS ...)
@@ -11,22 +9,28 @@ Start recording a macro for later invocation as a command.
     ...
   endmacro(<name>)
 
-Define a macro named <name> that takes arguments named arg1 arg2 arg3
+Define a macro named ``<name>`` that takes arguments named ``arg1``,
-(...).  Commands listed after macro, but before the matching endmacro,
+``arg2``, ``arg3``, (...).
-are not invoked until the macro is invoked.  When it is invoked, the
+Commands listed after macro, but before the matching
-commands recorded in the macro are first modified by replacing formal
+:command:`endmacro()`, are not invoked until the macro is invoked.
-parameters (``${arg1}``) with the arguments passed, and then invoked as
+When it is invoked, the commands recorded in the macro are first
-normal commands.  In addition to referencing the formal parameters you
+modified by replacing formal parameters (``${arg1}``) with the arguments
-can reference the values ``${ARGC}`` which will be set to the number of
+passed, and then invoked as normal commands.
-arguments passed into the function as well as ``${ARGV0}`` ``${ARGV1}``
+In addition to referencing the formal parameters you can reference the
-``${ARGV2}`` ...  which will have the actual values of the arguments
+values ``${ARGC}`` which will be set to the number of arguments passed
-passed in.  This facilitates creating macros with optional arguments.
+into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
+...  which will have the actual values of the arguments passed in.
+This facilitates creating macros with optional arguments.
 Additionally ``${ARGV}`` holds the list of all arguments given to the
 macro and ``${ARGN}`` holds the list of arguments past the last expected
 argument.
+Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
+behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
+way to ensure that ``${ARGV#}`` was passed to the function as an extra
+argument.
 
-See the cmake_policy() command documentation for the behavior of
+See the :command:`cmake_policy()` command documentation for the behavior
-policies inside macros.
+of policies inside macros.
 
 Macro Argument Caveats
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -37,10 +41,15 @@ replacements much like the C preprocessor would do with a macro.
 Therefore you will NOT be able to use commands like::
 
  if(ARGV1) # ARGV1 is not a variable
+ if(DEFINED ARGV2) # ARGV2 is not a variable
+ if(ARGC GREATER 2) # ARGC is not a variable
  foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
 
-In the first case you can use ``if(${ARGV1})``, in the second case, you can
+In the first case, you can use ``if(${ARGV1})``.
-use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments.
+In the second and third case, the proper way to check if an optional
+variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
+In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
+will skip empty arguments.
 If you need to include them, you can use::
 
  set(list_var "${ARGN}")

Help/command/project.rst

@@ -55,3 +55,10 @@ literal, direct call to the :command:`project` command; loading one
 through the :command:`include` command is not sufficient.  If no such
 call exists CMake will implicitly add one to the top that enables the
 default languages (``C`` and ``CXX``).
+
+.. note::
+  Call the :command:`cmake_minimum_required` command at the beginning
+  of the top-level ``CMakeLists.txt`` file even before calling the
+  ``project()`` command.  It is important to establish version and
+  policy settings before invoking other commands whose behavior they
+  may affect.  See also policy :policy:`CMP0000`.

Help/command/set.rst

@@ -1,116 +1,89 @@
 set
 ---
 
-Set a CMake, cache or environment variable to a given value.
+Set a normal, cache, or environment variable to a given value.
+See the :ref:`cmake-language(7) variables <CMake Language Variables>`
+documentation for the scopes and interaction of normal variables
+and cache entries.
+
+Signatures of this command that specify a ``<value>...`` placeholder
+expect zero or more arguments.  Multiple arguments will be joined as
+a :ref:`;-list <CMake Language Lists>` to form the actual variable
+value to be set.  Zero arguments will cause normal variables to be
+unset.  See the :command:`unset` command to unset variables explicitly.
+
+Set Normal Variable
+^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  set(<variable> <value>
+  set(<variable> <value>... [PARENT_SCOPE])
-      [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
 
-Within CMake sets <variable> to the value <value>.  <value> is
+Set the given ``<variable>`` in the current function or directory scope.
-expanded before <variable> is set to it.  Normally, set will set a
+
-regular CMake variable.  If CACHE is present, then the <variable> is
+If the ``PARENT_SCOPE`` option is given the variable will be set in
-put in the cache instead, unless it is already in the cache.  See
+the scope above the current scope.  Each new directory or function
-section 'Variable types in CMake' below for details of regular and
+creates a new scope.  This command will set the value of a variable
-cache variables and their interactions.  If CACHE is used, <type> and
+into the parent directory or calling function (whichever is applicable
-<docstring> are required.  <type> is used by the CMake GUI to choose a
+to the case at hand).
-widget with which the user sets a value.  The value for <type> may be
+
-one of
+Set Cache Entry
+^^^^^^^^^^^^^^^
 
 ::
 
-  FILEPATH = File chooser dialog.
+  set(<variable> <value>... CACHE <type> <docstring> [FORCE])
-  PATH     = Directory chooser dialog.
-  STRING   = Arbitrary string.
-  BOOL     = Boolean ON/OFF checkbox.
-  INTERNAL = No GUI entry (used for persistent variables).
 
-If <type> is INTERNAL, the cache variable is marked as internal, and
+Set the given cache ``<variable>`` (cache entry).  Since cache entries
-will not be shown to the user in tools like cmake-gui.  This is
+are meant to provide user-settable values this does not overwrite
-intended for values that should be persisted in the cache, but which
+existing cache entries by default.  Use the ``FORCE`` option to
-users should not normally change.  INTERNAL implies FORCE.
+overwrite existing entries.
 
-Normally, set(...CACHE...) creates cache variables, but does not
+The ``<type>`` must be specified as one of:
-modify them.  If FORCE is specified, the value of the cache variable
-is set, even if the variable is already in the cache.  This should
-normally be avoided, as it will remove any changes to the cache
-variable's value by the user.
 
-If PARENT_SCOPE is present, the variable will be set in the scope
+``BOOL``
-above the current scope.  Each new directory or function creates a new
+  Boolean ``ON/OFF`` value.  :manual:`cmake-gui(1)` offers a checkbox.
-scope.  This command will set the value of a variable into the parent
-directory or calling function (whichever is applicable to the case at
-hand).  PARENT_SCOPE cannot be combined with CACHE.
 
-If <value> is not specified then the variable is removed instead of
+``FILEPATH``
-set.  See also: the unset() command.
+  Path to a file on disk.  :manual:`cmake-gui(1)` offers a file dialog.
+
+``PATH``
+  Path to a directory on disk.  :manual:`cmake-gui(1)` offers a file dialog.
+
+``STRING``
+  A line of text.  :manual:`cmake-gui(1)` offers a text field or a
+  drop-down selection if the :prop_cache:`STRINGS` cache entry
+  property is set.
+
+``INTERNAL``
+  A line of text.  :manual:`cmake-gui(1)` does not show internal entries.
+  They may be used to store variables persistently across runs.
+  Use of this type implies ``FORCE``.
+
+The ``<docstring>`` must be specified as a line of text providing
+a quick summary of the option for presentation to :manual:`cmake-gui(1)`
+users.
+
+If the cache entry does not exist prior to the call or the ``FORCE``
+option is given then the cache entry will be set to the given value.
+Furthermore, any normal variable binding in the current scope will
+be removed to expose the newly cached value to any immediately
+following evaluation.
+
+It is possible for the cache entry to exist prior to the call but
+have no type set if it was created on the :manual:`cmake(1)` command
+line by a user through the ``-D<var>=<value>`` option without
+specifying a type.  In this case the ``set`` command will add the
+type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
+and the ``<value>`` provided on the command line is a relative path,
+then the ``set`` command will treat the path as relative to the
+current working directory and convert it to an absolute path.
+
+Set Environment Variable
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  set(<variable> <value1> ... <valueN>)
+  set(ENV{<variable>} <value>...)
 
-In this case <variable> is set to a semicolon separated list of
+Set the current process environment ``<variable>`` to the given value.
-values.
-
-<variable> can be an environment variable such as:
-
-::
-
-  set( ENV{PATH} /home/martink )
-
-in which case the environment variable will be set.
-
-*** Variable types in CMake ***
-
-In CMake there are two types of variables: normal variables and cache
-variables.  Normal variables are meant for the internal use of the
-script (just like variables in most programming languages); they are
-not persisted across CMake runs.  Cache variables (unless set with
-INTERNAL) are mostly intended for configuration settings where the
-first CMake run determines a suitable default value, which the user
-can then override, by editing the cache with tools such as ccmake or
-cmake-gui.  Cache variables are stored in the CMake cache file, and
-are persisted across CMake runs.
-
-Both types can exist at the same time with the same name but different
-values.  When ${FOO} is evaluated, CMake first looks for a normal
-variable 'FOO' in scope and uses it if set.  If and only if no normal
-variable exists then it falls back to the cache variable 'FOO'.
-
-Some examples:
-
-The code 'set(FOO "x")' sets the normal variable 'FOO'.  It does not
-touch the cache, but it will hide any existing cache value 'FOO'.
-
-The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
-ignoring any normal variable of the same name.  If 'FOO' is in the
-cache then nothing happens to either the normal variable or the cache
-variable.  If 'FOO' is not in the cache, then it is added to the
-cache.
-
-Finally, whenever a cache variable is added or modified by a command,
-CMake also *removes* the normal variable of the same name from the
-current scope so that an immediately following evaluation of it will
-expose the newly cached value.
-
-Normally projects should avoid using normal and cache variables of the
-same name, as this interaction can be hard to follow.  However, in
-some situations it can be useful.  One example (used by some
-projects):
-
-A project has a subproject in its source tree.  The child project has
-its own CMakeLists.txt, which is included from the parent
-CMakeLists.txt using add_subdirectory().  Now, if the parent and the
-child project provide the same option (for example a compiler option),
-the parent gets the first chance to add a user-editable option to the
-cache.  Normally, the child would then use the same value that the
-parent uses.  However, it may be necessary to hard-code the value for
-the child project's option while still allowing the user to edit the
-value used by the parent project.  The parent project can achieve this
-simply by setting a normal variable with the same name as the option
-in a scope sufficient to hide the option's cache variable from the
-child completely.  The parent has already set the cache variable, so
-the child's set(...CACHE...) will do nothing, and evaluating the
-option variable will use the value from the normal variable, which
-hides the cache variable.

Help/command/set_directory_properties.rst

@@ -7,9 +7,6 @@ Set a property of the directory.
 
   set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
 
-Set a property for the current directory and subdirectories.  If the
+Set a property for the current directory and subdirectories. See
-property is not found, CMake will report an error.  The properties
+:ref:`Directory Properties` for the list of properties known
-include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
+to CMake.
-INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
-ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be cleaned as
-a part of "make clean" stage.

Help/command/set_source_files_properties.rst

@@ -10,6 +10,6 @@ Source files can have properties that affect how they are built.
                               [prop2 value2 [...]])
 
 Set properties associated with source files using a key/value paired
-list.  See properties documentation for those known to CMake.
+list.  See :ref:`Source File Properties` for the list of properties known
-Unrecognized properties are ignored.  Source file properties are
+to CMake.  Source file properties are visible only to targets added
-visible only to targets added in the same directory (CMakeLists.txt).
+in the same directory (CMakeLists.txt).

Help/command/set_tests_properties.rst

@@ -8,29 +8,7 @@ Set a property of the tests.
   set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
 
 Set a property for the tests.  If the test is not found, CMake
-will report an error.  Generator expressions will be expanded the same
+will report an error.
-as supported by the test's add_test call.  The properties include:
+:manual:`Generator expressions <cmake-generator-expressions(7)>` will be
-
+expanded the same as supported by the test's :command:`add_test` call.  See
-WILL_FAIL: If set to true, this will invert the pass/fail flag of the
+:ref:`Test Properties` for the list of properties known to CMake.
-test.
-
-PASS_REGULAR_EXPRESSION: If set, the test output will be checked
-against the specified regular expressions and at least one of the
-regular expressions has to match, otherwise the test will fail.
-
-::
-
-  Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
-
-FAIL_REGULAR_EXPRESSION: If set, if the output will match to one of
-specified regular expressions, the test will fail.
-
-::
-
-  Example: FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
-
-Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect a list
-of regular expressions.
-
-TIMEOUT: Setting this will limit the test runtime to the number of
-seconds specified.

Help/command/target_compile_definitions.rst

@@ -9,7 +9,7 @@ Add compile definitions to a target.
     <INTERFACE|PUBLIC|PRIVATE> [items1...]
     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
 
-Specify compile definitions to use when compiling a given <target.  The
+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>`.

Help/command/target_compile_features.rst

@@ -29,4 +29,4 @@ Arguments to ``target_compile_features`` may use "generator expressions"
 with the syntax ``$<...>``.
 See the :manual:`cmake-generator-expressions(7)` manual for available
 expressions.  See the :manual:`cmake-compile-features(7)` manual for
-information on compile features.
+information on compile features and a list of supported compilers.

Help/command/target_compile_options.rst

@@ -20,8 +20,8 @@ alternative commands exist to add preprocessor definitions
 (:command:`target_compile_definitions` and :command:`add_definitions`) or
 include directories (:command:`target_include_directories` and
 :command:`include_directories`).  See documentation of the
-:prop_tgt:`directory <COMPILE_OPTIONS>` and
+:prop_dir:`directory <COMPILE_OPTIONS>` and
-:prop_tgt:` target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
+:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``

Help/command/target_include_directories.rst

@@ -55,5 +55,8 @@ installation prefix.  For example:
     $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
   )
 
+Creating Relocatable Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
 .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

Help/command/target_link_libraries.rst

@@ -1,38 +1,113 @@
 target_link_libraries
 ---------------------
 
-Link a target to given libraries.
+.. only:: html
+
+   .. contents::
+
+Specify libraries or flags to use when linking a given target and/or
+its dependents.  :ref:`Usage requirements <Target Usage Requirements>`
+from linked library targets will be propagated.  Usage requirements
+of a target's dependencies affect compilation of its own sources.
+
+Overview
+^^^^^^^^
+
+This command has several signatures as detailed in subsections below.
+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`.
+Repeated calls for the same ``<target>`` append items in the order called.
+Each ``<item>`` may be:
+
+* **A library target name**: The generated link line will have the
+  full path to the linkable library file associated with the target.
+  The buildsystem will have a dependency to re-link ``<target>`` if
+  the library file changes.
+
+  The named target must be created by :command:`add_library` within
+  the project or as an :ref:`IMPORTED library <Imported Targets>`.
+  If it is created within the project an ordering dependency will
+  automatically be added in the build system to make sure the named
+  library target is up-to-date before the ``<target>`` links.
+
+  If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME`
+  target property set, CMake may ask the linker to search for
+  the library instead of using the full path
+  (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``).
+
+* **A full path to a library file**: The generated link line will
+  normally preserve the full path to the file. The buildsystem will
+  have a dependency to re-link ``<target>`` if the library file changes.
+
+  There are some cases where CMake may ask the linker to search for
+  the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such
+  as when a shared library is detected to have no ``SONAME`` field.
+  See policy :policy:`CMP0060` for discussion of another case.
+
+  If the library file is in a Mac OSX framework, the ``Headers`` directory
+  of the framework will also be processed as a
+  :ref:`usage requirement <Target Usage Requirements>`.  This has the same
+  effect as passing the framework directory as an include directory.
+
+* **A plain library name**: The generated link line will ask the linker
+  to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``).
+
+* **A link flag**: Item names starting with ``-``, but not ``-l`` or
+  ``-framework``, are treated as linker flags.  Note that such flags will
+  be treated like any other library link item for purposes of transitive
+  dependencies, so they are generally safe to specify only as private link
+  items that will not propagate to dependents.
+
+* A ``debug``, ``optimized``, or ``general`` keyword immediately followed
+  by another ``<item>``.  The item following such a keyword will be used
+  only for the corresponding build configuration.  The ``debug`` keyword
+  corresponds to the ``Debug`` configuration (or to configurations named
+  in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
+  The ``optimized`` keyword corresponds to all other configurations.  The
+  ``general`` keyword corresponds to all configurations, and is purely
+  optional.  Higher granularity may be achieved for per-configuration
+  rules by creating and linking to
+  :ref:`IMPORTED library targets <Imported Targets>`.
+
+Items containing ``::``, such as ``Foo::Bar``, are assumed to be
+:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library
+target names and will cause an error if no such target exists.
+See policy :policy:`CMP0028`.
+
+Arguments to ``target_link_libraries`` may use "generator expressions"
+with the syntax ``$<...>``.  Note however, that generator expressions
+will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
+See the :manual:`cmake-generator-expressions(7)` manual for available
+expressions.  See the :manual:`cmake-buildsystem(7)` manual for more on
+defining buildsystem properties.
+
+Libraries for a Target and/or its Dependents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  target_link_libraries(<target> [item1 [item2 [...]]]
+  target_link_libraries(<target>
-                        [[debug|optimized|general] <item>] ...)
+                        <PRIVATE|PUBLIC|INTERFACE> <item>...
+                       [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
 
-Specify libraries or flags to use when linking a given target.  The
+The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
-named ``<target>`` must have been created in the current directory by a
+specify both the link dependencies and the link interface in one command.
-command such as :command:`add_executable` or :command:`add_library`.  The
+Libraries and targets following ``PUBLIC`` are linked to, and are made
-remaining arguments specify library names or flags.  Repeated calls for
+part of the link interface.  Libraries and targets following ``PRIVATE``
-the same ``<target>`` append items in the order called.
+are linked to, but are not made part of the link interface.  Libraries
+following ``INTERFACE`` are appended to the link interface and are not
+used for linking ``<target>``.
 
-If a library name matches that of another target in the project a
+Libraries for both a Target and its Dependents
-dependency will automatically be added in the build system to make sure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-the library being linked is up-to-date before the target links. Item names
-starting with ``-``, but not ``-l`` or ``-framework``, are treated as
-linker flags.  Note that such flags will be treated like any other library
-link item for purposes of transitive dependencies, so they are generally
-safe to specify only as private link items that will not propagate to
-dependents of ``<target>``.
 
-A ``debug``, ``optimized``, or ``general`` keyword indicates that the
+::
-library immediately following it is to be used only for the
+
-corresponding build configuration.  The ``debug`` keyword corresponds to
+  target_link_libraries(<target> <item>...)
-the Debug configuration (or to configurations named in the
-:prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).  The
-``optimized`` keyword corresponds to all other configurations.  The
-``general`` keyword corresponds to all configurations, and is purely
-optional (assumed if omitted).  Higher granularity may be achieved for
-per-configuration rules by creating and linking to
-:ref:`IMPORTED library targets <Imported Targets>`.
 
 Library dependencies are transitive by default with this signature.
 When this target is linked into another target then the libraries
@@ -45,40 +120,34 @@ by setting the property directly.  When :policy:`CMP0022` is not set to
 of this command may set the property making any libraries linked
 exclusively by this signature private.
 
-CMake will also propagate :ref:`usage requirements <Target Usage Requirements>`
+Libraries for a Target and/or its Dependents (Legacy)
-from linked library targets.  Usage requirements of dependencies affect
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-compilation of sources in the ``<target>``.
-
-.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
-.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
-
-If an ``<item>`` is a library in a Mac OX framework, the ``Headers``
-directory of the framework will also be processed as a
-:ref:`usage requirement <Target Usage Requirements>`.  This has the same
-effect as passing the framework directory as an include directory.
-
---------------------------------------------------------------------------
 
 ::
 
   target_link_libraries(<target>
-                      <PRIVATE|PUBLIC|INTERFACE> <lib> ...
+                        <LINK_PRIVATE|LINK_PUBLIC> <lib>...
-                      [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
+                       [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
 
-The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
+The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
-specify both the link dependencies and the link interface in one command.
+the link dependencies and the link interface in one command.
-Libraries and targets following ``PUBLIC`` are linked to, and are made
-part of the link interface.  Libraries and targets following ``PRIVATE``
-are linked to, but are not made part of the link interface.  Libraries
-following ``INTERFACE`` are appended to the link interface and are not
-used for linking ``<target>``.
 
---------------------------------------------------------------------------
+This signature is for compatibility only.  Prefer the ``PUBLIC`` or
+``PRIVATE`` keywords instead.
+
+Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
+made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`.  If policy
+:policy:`CMP0022` is not ``NEW``, they are also made part of the
+:prop_tgt:`LINK_INTERFACE_LIBRARIES`.  Libraries and targets following
+``LINK_PRIVATE`` are linked to, but are not made part of the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
+
+Libraries for Dependents Only (Legacy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
+  target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
-                        [[debug|optimized|general] <lib>] ...)
 
 The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
 :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
@@ -102,28 +171,8 @@ is not ``NEW``, they are also appended to the
 ``general`` (or without any keyword) are treated as if specified for both
 ``debug`` and ``optimized``.
 
---------------------------------------------------------------------------
+Cyclic Dependencies of Static Libraries
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-::
-
-  target_link_libraries(<target>
-                        <LINK_PRIVATE|LINK_PUBLIC>
-                          [[debug|optimized|general] <lib>] ...
-                        [<LINK_PRIVATE|LINK_PUBLIC>
-                          [[debug|optimized|general] <lib>] ...])
-
-The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
-the link dependencies and the link interface in one command.
-
-This signature is for compatibility only.  Prefer the ``PUBLIC`` or
-``PRIVATE`` keywords instead.
-
-Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
-made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`.  If policy
-:policy:`CMP0022` is not ``NEW``, they are also made part of the
-:prop_tgt:`LINK_INTERFACE_LIBRARIES`.  Libraries and targets following
-``LINK_PRIVATE`` are linked to, but are not made part of the
-:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
 
 The library dependency graph is normally acyclic (a DAG), but in the case
 of mutually-dependent ``STATIC`` libraries CMake allows the graph to
@@ -142,14 +191,14 @@ For example, the code
 
 links ``main`` to ``A B A B``.  While one repetition is usually
 sufficient, pathological object file and symbol arrangements can require
-more.  One may handle such cases by manually repeating the component in
+more.  One may handle such cases by using the
-the last ``target_link_libraries`` call.  However, if two archives are
+:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually
-really so interdependent they should probably be combined into a single
+repeating the component in the last ``target_link_libraries`` call.
-archive.
+However, if two archives are really so interdependent they should probably
+be combined into a single archive, perhaps by using :ref:`Object Libraries`.
 
-Arguments to target_link_libraries may use "generator expressions"
+Creating Relocatable Packages
-with the syntax ``$<...>``.  Note however, that generator expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
+
-See the :manual:`cmake-generator-expressions(7)` manual for available
+.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
-expressions.  See the :manual:`cmake-buildsystem(7)` manual for more on
+.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
-defining buildsystem properties.

Help/command/target_sources.rst

@@ -22,10 +22,6 @@ items will populate the :prop_tgt:`SOURCES` property of
 following arguments specify sources.  Repeated calls for the same
 ``<target>`` append items in the order called.
 
-Targets with :prop_tgt:`INTERFACE_SOURCES` may not be exported with the
-:command:`export` or :command:`install(EXPORT)` commands. This limitation may be
-lifted in a future version of CMake.
-
 Arguments to ``target_sources`` may use "generator expressions"
 with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`

Help/command/try_run.rst

@@ -73,7 +73,8 @@ When cross compiling, the executable compiled in the first step
 usually cannot be run on the build host.  The ``try_run`` command checks
 the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in
 cross-compiling mode.  If that is the case, it will still try to compile
-the executable, but it will not try to run the executable.  Instead it
+the executable, but it will not try to run the executable unless the
+:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable is set.  Instead it
 will create cache variables which must be filled by the user or by
 presetting them in some CMake script file to the values the executable
 would have produced if it had been run on its actual target platform.

Help/generator/Green Hills MULTI.rst

@@ -0,0 +1,16 @@
+Green Hills MULTI
+-----------------
+
+Generates Green Hills MULTI project files (experimental, work-in-progress).
+
+Customizations are available through the following cache variables:
+
+* ``GHS_BSP_NAME``
+* ``GHS_CUSTOMIZATION``
+* ``GHS_GPJ_MACROS``
+* ``GHS_OS_DIR``
+
+.. note::
+  This generator is deemed experimental as of CMake |release|
+  and is still a work in progress.  Future versions of CMake
+  may make breaking changes as the generator matures.

Help/generator/Ninja.rst

@@ -1,7 +1,7 @@
 Ninja
 -----
 
-Generates build.ninja files (experimental).
+Generates build.ninja files.
 
 A build.ninja file is generated into the build tree.  Recent versions
 of the ninja program can build the project through the "all" target.

Help/generator/Visual Studio 6.rst

@@ -1,4 +1,10 @@
 Visual Studio 6
 ---------------
 
-Generates Visual Studio 6 project files.
+Deprected.  Generates Visual Studio 6 project files.
+
+.. note::
+  This generator is deprecated and will be removed
+  in a future version of CMake.  It will still be
+  possible to build with VS 6 tools using the
+  :generator:`NMake Makefiles` generator.

Help/generator/Visual Studio 7.rst

@@ -1,4 +1,10 @@
 Visual Studio 7
 ---------------
 
-Generates Visual Studio .NET 2002 project files.
+Deprected.  Generates Visual Studio .NET 2002 project files.
+
+.. note::
+  This generator is deprecated and will be removed
+  in a future version of CMake.  It will still be
+  possible to build with VS 7.0 tools using the
+  :generator:`NMake Makefiles` generator.

Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

@@ -1,30 +1,18 @@
 
 Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
-|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
+|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
-That would hard-code into installed packages the include directory paths
+directories of dependencies.  That would hard-code into installed packages
-for dependencies **as found on the machine the package was made on**.
+the include directory paths for dependencies
+**as found on the machine the package was made on**.
 
 The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
-suitable for specifying the required include directories of the target itself,
+suitable for specifying the required include directories for headers
-not its dependencies.
+provided with the target itself, not those provided by the transitive
+dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
+property.  Those dependencies should themselves be targets that specify
+their own header locations in |INTERFACE_PROPERTY_LINK|.
 
-That is, code like this is incorrect for targets which will be used to
+See the :ref:`Creating Relocatable Packages` section of the
-generate :manual:`cmake-packages(7)`:
+:manual:`cmake-packages(7)` manual for discussion of additional care
-
+that must be taken when specifying usage requirements while creating
-.. code-block:: cmake
+packages for redistribution.
-
-  target_include_directories(mylib INTERFACE
-    $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
-  )
-
-Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
-which have their own |INTERFACE_PROPERTY_LINK| populated
-appropriately.  Those :ref:`IMPORTED targets <Imported Targets>` may then be
-used with the :command:`target_link_libraries` command for ``mylib``.
-
-That way, when a consumer uses the installed package, the
-consumer will run the appropriate :command:`find_package` command to find
-the dependencies on their own machine and populate the
-:ref:`IMPORTED targets <Imported Targets>` with appropriate paths.  See
-:ref:`Creating Packages` for more.  Note that many modules currently shipped
-with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.

Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt

@@ -1,23 +1,10 @@
 
 Note that it is not advisable to populate the
-|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
+|INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies.
-That would hard-code into installed packages the include directory paths
+That would hard-code into installed packages the library file paths
 for dependencies **as found on the machine the package was made on**.
 
-That is, code like this is incorrect for targets which will be used to
+See the :ref:`Creating Relocatable Packages` section of the
-generate :manual:`cmake-packages(7)`:
+:manual:`cmake-packages(7)` manual for discussion of additional care
-
+that must be taken when specifying usage requirements while creating
-.. code-block:: cmake
+packages for redistribution.
-
-  target_link_libraries(mylib INTERFACE
-    ${Boost_LIBRARIES};${OtherDep_LIBRARIES}
-  )
-
-Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
-which have their own :prop_tgt:`IMPORTED_LOCATION` populated
-appropriately.  That way, when a consumer uses the installed package, the
-consumer will run the appropriate :command:`find_package` command to find
-the dependencies on their own machine and populate the
-:ref:`IMPORTED targets <Imported Targets>` with appropriate paths.  See
-:ref:`Creating Packages` for more.  Note that many modules currently shipped
-with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.

Help/manual/OPTIONS_BUILD.txt

@@ -10,7 +10,7 @@
  containing SET commands that use the CACHE option, not a
  cache-format file.
 
-``-D <var>:<type>=<value>``
+``-D <var>:<type>=<value>, -D <var>=<value>``
  Create a cmake cache entry.
 
  When cmake is first run in an empty build tree, it creates a
@@ -19,6 +19,17 @@
  takes priority over the project's default value.  The option may be
  repeated for as many cache entries as desired.
 
+ If the ``:<type>`` portion is given it must be one of the types
+ specified by the :command:`set` command documentation for its
+ ``CACHE`` signature.
+ If the ``:<type>`` portion is omitted the entry will be created
+ with no type if it does not exist with a type already.  If a
+ command in the project sets the type to ``PATH`` or ``FILEPATH``
+ then the ``<value>`` will be converted to an absolute path.
+
+ This option may also be given as a single argument:
+ ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``.
+
 ``-U <globbing_expr>``
  Remove matching entries from CMake cache.
 
@@ -35,7 +46,7 @@
  CMake may support multiple native build systems on certain
  platforms.  A generator is responsible for generating a particular
  build system.  Possible generator names are specified in the
- Generators section.
+ :manual:`cmake-generators(7)` manual.
 
 ``-T <toolset-name>``
  Specify toolset name if supported by generator.

Help/manual/cmake-buildsystem.7.rst

@@ -143,6 +143,11 @@ use particular :prop_tgt:`COMPILE_OPTIONS` or
 the properties must be **requirements**, not merely recommendations or
 convenience.
 
+See the :ref:`Creating Relocatable Packages` section of the
+:manual:`cmake-packages(7)` manual for discussion of additional care
+that must be taken when specifying usage requirements while creating
+packages for redistribution.
+
 Target Properties
 -----------------
 
@@ -627,7 +632,7 @@ may be enabled, with an equivalent effect to:
 
 .. code-block:: cmake
 
-  set_property(TARGET tgt APPEND PROPERTY
+  set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
   )
 
@@ -690,8 +695,10 @@ edge of linking ``exe1`` is determined by the same
 :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
 contains a cycle.  :manual:`cmake(1)` issues a diagnostic in this case.
 
-Output Files
+.. _`Output Artifacts`:
-------------
+
+Output Artifacts
+----------------
 
 The buildsystem targets created by the :command:`add_library` and
 :command:`add_executable` commands create rules to create binary outputs.
@@ -703,6 +710,71 @@ name and location of generated binaries.  These expressions do not work
 for ``OBJECT`` libraries however, as there is no single file generated
 by such libraries which is relevant to the expressions.
 
+There are three kinds of output artifacts that may be build by targets
+as detailed in the following sections.  Their classification differs
+between DLL platforms and non-DLL platforms.  All Windows-based
+systems including Cygwin are DLL platforms.
+
+.. _`Runtime Output Artifacts`:
+
+Runtime Output Artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A *runtime* output artifact of a buildsystem target may be:
+
+* The executable file (e.g. ``.exe``) of an executable target
+  created by the :command:`add_executable` command.
+
+* On DLL platforms: the executable file (e.g. ``.dll``) of a shared
+  library target created by the :command:`add_library` command
+  with the ``SHARED`` option.
+
+The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
+target properties may be used to control runtime output artifact locations
+and names in the build tree.
+
+.. _`Library Output Artifacts`:
+
+Library Output Artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A *library* output artifact of a buildsystem target may be:
+
+* The loadable module file (e.g. ``.dll`` or ``.so``) of a module
+  library target created by the :command:`add_library` command
+  with the ``MODULE`` option.
+
+* On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``)
+  of a shared shared library target created by the :command:`add_library`
+  command with the ``SHARED`` option.
+
+The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`
+target properties may be used to control library output artifact locations
+and names in the build tree.
+
+.. _`Archive Output Artifacts`:
+
+Archive Output Artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+An *archive* output artifact of a buildsystem target may be:
+
+* The static library file (e.g. ``.lib`` or ``.a``) of a static
+  library target created by the :command:`add_library` command
+  with the ``STATIC`` option.
+
+* On DLL platforms: the import library file (e.g. ``.lib``) of a shared
+  library target created by the :command:`add_library` command
+  with the ``SHARED`` option.
+
+* On DLL platforms: the import library file (e.g. ``.lib``) of an
+  executable target created by the :command:`add_executable` command
+  when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
+
+The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
+target properties may be used to control archive output artifact locations
+and names in the build tree.
+
 Directory-Scoped Commands
 -------------------------
 
@@ -814,9 +886,9 @@ It may specify usage requirements such as
 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
 :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
-:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`,
 :prop_tgt:`INTERFACE_SOURCES`,
-:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
+and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
 Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
 :command:`target_compile_definitions`, :command:`target_compile_options`,
 :command:`target_sources`, and :command:`target_link_libraries` commands

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

@@ -278,7 +278,7 @@ properties:
   add_library(foo INTERFACE)
   set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
   set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
-  target_link_libraries(foo
+  target_include_directories(foo
     INTERFACE
       "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
       "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
@@ -295,3 +295,17 @@ the feature-appropriate include directory
 
   add_executable(consumer_no consumer_no.cpp)
   target_link_libraries(consumer_no foo)
+
+Supported Compilers
+===================
+
+CMake is currently aware of the :prop_tgt:`language standards <CXX_STANDARD>`
+and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from
+the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
+versions specified for each:
+
+* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2.
+* ``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 2015.
+* ``SunPro``: Oracle SolarisStudio version 12.4.

Help/manual/cmake-developer.7.rst

@@ -28,34 +28,6 @@ Some implementations have a ``std::auto_ptr`` which can not be used as a
 return value from a function. ``std::auto_ptr`` may not be used. Use
 ``cmsys::auto_ptr`` instead.
 
-Template Parameter Defaults
----------------------------
-
-On ancient compilers, C++ template must use template parameters in function
-arguments.  If no parameter of that type is needed, the common workaround is
-to add a defaulted pointer to the type to the templated function. However,
-this does not work with other ancient compilers:
-
-.. code-block:: c++
-
-  template<typename PropertyType>
-  PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
-                                PropertyType* = 0) // Wrong
-    {
-
-    }
-
-.. code-block:: c++
-
-  template<typename PropertyType>
-  PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
-                                PropertyType*) // Ok
-    {
-
-    }
-
-and invoke it with the value ``0`` explicitly in all cases.
-
 size_t
 ------
 
@@ -633,6 +605,7 @@ have a .cmake file in this directory NOT show up in the modules
 documentation, simply leave out the ``Help/module/<module-name>.rst``
 file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
 
+.. _`Find Modules`:
 
 Find Modules
 ------------
@@ -894,7 +867,6 @@ look.
   find_path(Foo_INCLUDE_DIR
     NAMES foo.h
     PATHS ${PC_Foo_INCLUDE_DIRS}
-    # if you need to put #include <Foo/foo.h> in your code, add:
     PATH_SUFFIXES Foo
   )
   find_library(Foo_LIBRARY

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

@@ -40,10 +40,6 @@ otherwise expands to nothing.
 
 Available logical expressions are:
 
-``$<0:...>``
-  Empty string (ignores ``...``)
-``$<1:...>``
-  Content of ``...``
 ``$<BOOL:...>``
   ``1`` if the ``...`` is true, else ``0``
 ``$<AND:?[,?]...>``
@@ -92,7 +88,47 @@ Available logical expressions are:
   increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD`
   for the 'head' target, an error is reported.  See the
   :manual:`cmake-compile-features(7)` manual for information on
-  compile features.
+  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
+  source files of a particular language in a target. For example, to specify
+  the use of the ``-fno-exceptions`` compile option (compiler id checks
+  elided):
+
+  .. code-block:: cmake
+
+    add_executable(myapp main.cpp foo.c bar.cpp)
+    target_compile_options(myapp
+      PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
+    )
+
+  This generator expression has limited use because it is not possible to
+  use it with the Visual Studio generators.  Portable buildsystems would
+  not use this expression, and would create separate libraries for each
+  source file language instead:
+
+  .. code-block:: cmake
+
+    add_library(myapp_c foo.c)
+    add_library(myapp_cxx foo.c)
+    target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
+    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
 =========================
@@ -174,6 +210,10 @@ Available informational expressions are:
 ``$<INSTALL_PREFIX>``
   Content of the install prefix when the target is exported via
   :command:`install(EXPORT)` and empty otherwise.
+``$<COMPILE_LANGUAGE>``
+  The compile language of source files when evaluating compile options. See
+  the unary version for notes about portability of this generator
+  expression.
 
 Output Expressions
 ==================
@@ -197,6 +237,10 @@ where ``${prop}`` refers to a helper variable::
 
 Available output expressions are:
 
+``$<0:...>``
+  Empty string (ignores ``...``)
+``$<1:...>``
+  Content of ``...``
 ``$<JOIN:list,...>``
   Joins the list with the content of ``...``
 ``$<ANGLE-R>``

Help/manual/cmake-generators.7.rst

@@ -34,6 +34,11 @@ These generators support command-line build tools.  In order to use them,
 one must launch CMake from a command-line prompt whose environment is
 already configured for the chosen compiler and build tool.
 
+.. _`Makefile Generators`:
+
+Makefile Generators
+^^^^^^^^^^^^^^^^^^^
+
 .. toctree::
    :maxdepth: 1
 
@@ -42,10 +47,17 @@ already configured for the chosen compiler and build tool.
    /generator/MinGW Makefiles
    /generator/NMake Makefiles
    /generator/NMake Makefiles JOM
-   /generator/Ninja
    /generator/Unix Makefiles
    /generator/Watcom WMake
 
+Ninja Generator
+^^^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+
+   /generator/Ninja
+
 IDE Build Tool Generators
 -------------------------
 
@@ -53,6 +65,11 @@ These generators support Integrated Development Environment (IDE)
 project files.  Since the IDEs configure their own environment
 one may launch CMake from any environment.
 
+.. _`Visual Studio Generators`:
+
+Visual Studio Generators
+^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. toctree::
    :maxdepth: 1
 
@@ -65,6 +82,14 @@ one may launch CMake from any environment.
    /generator/Visual Studio 11 2012
    /generator/Visual Studio 12 2013
    /generator/Visual Studio 14 2015
+
+Other Generators
+^^^^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 1
+
+   /generator/Green Hills MULTI
    /generator/Xcode
 
 Extra Generators

Help/manual/cmake-language.7.rst

@@ -485,6 +485,8 @@ The :command:`macro`/:command:`endmacro`, and
 :command:`function`/:command:`endfunction` commands delimit
 code blocks to be recorded for later invocation as commands.
 
+.. _`CMake Language Variables`:
+
 Variables
 =========
 
@@ -538,6 +540,8 @@ The :manual:`cmake-variables(7)` manual documents many variables
 that are provided by CMake or have meaning to CMake when set
 by project code.
 
+.. _`CMake Language Lists`:
+
 Lists
 =====
 

Help/manual/cmake-modules.7.rst

@@ -22,6 +22,7 @@ All Modules
    /module/CheckCXXSourceCompiles
    /module/CheckCXXSourceRuns
    /module/CheckCXXSymbolExists
+   /module/CheckFortranCompilerFlag
    /module/CheckFortranFunctionExists
    /module/CheckFortranSourceCompiles
    /module/CheckFunctionExists
@@ -211,6 +212,7 @@ All Modules
    /module/FindWish
    /module/FindwxWidgets
    /module/FindwxWindows
+   /module/FindXCTest
    /module/FindXercesC
    /module/FindX11
    /module/FindXMLRPC

Help/manual/cmake-packages.7.rst

@@ -373,38 +373,6 @@ attempt to use version 3 together with version 4.  Packages can choose to
 employ such a pattern if different major versions of the package are designed
 to be incompatible.
 
-Note that it is not advisable to populate any properties which may contain
-paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
-:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevnt to dependencies.
-That would hard-code into installed packages the include directory or library
-paths for dependencies **as found on the machine the package was made on**.
-
-That is, code like this is incorrect for targets which will be used to
-generate config file packages:
-
-.. code-block:: cmake
-
-  target_link_libraries(ClimbingStats INTERFACE
-    ${Boost_LIBRARIES};${OtherDep_LIBRARIES}>
-  )
-  target_include_directories(ClimbingStats INTERFACE
-    $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
-  )
-
-Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
-which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
-:prop_tgt:`IMPORTED_LOCATION` populated appropriately.  Those
-:ref:`IMPORTED targets <Imported Targets>` may then be
-used with the :command:`target_link_libraries` command for ``ClimbingStats``.
-
-That way, when a consumer uses the installed package, the
-consumer will run the appropriate :command:`find_package` command (via the
-find_dependency macro described below) to find
-the dependencies on their own machine and populate the
-:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that
-many modules currently shipped with CMake do not currently provide
-:ref:`IMPORTED targets <Imported Targets>`.
-
 A ``NAMESPACE`` with double-colons is specified when exporting the targets
 for installation.  This convention of double-colons gives CMake a hint that
 the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams
@@ -418,6 +386,9 @@ directory in the :variable:`CMAKE_INSTALL_PREFIX`.  When the ``IMPORTED``
 target is used by downsteam, it automatically consumes the entries from
 that property.
 
+Creating a Package Configuration File
+-------------------------------------
+
 In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as:
 
 .. code-block:: cmake
@@ -429,44 +400,6 @@ should be provided by the ``ClimbingStats`` package, they should
 be in a separate file which is installed to the same location as the
 ``ClimbingStatsConfig.cmake`` file, and included from there.
 
-Packages created by :command:`install(EXPORT)` are designed to be relocatable,
-using paths relative to the location of the package itself.  When defining
-the interface of a target for ``EXPORT``, keep in mind that the include
-directories should be specified as relative paths which are relative to the
-:variable:`CMAKE_INSTALL_PREFIX`:
-
-.. code-block:: cmake
-
-  target_include_directories(tgt INTERFACE
-    # Wrong, not relocatable:
-    $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
-  )
-
-  target_include_directories(tgt INTERFACE
-    # Ok, relocatable:
-    $<INSTALL_INTERFACE:include/TgtName>
-  )
-
-The ``$<INSTALL_PREFIX>``
-:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
-a placeholder for the install prefix without resulting in a non-relocatable
-package.  This is necessary if complex generator expressions are used:
-
-.. code-block:: cmake
-
-  target_include_directories(tgt INTERFACE
-    # Ok, relocatable:
-    $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
-  )
-
-The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
-definition file which is specific to the build-tree, and is not relocatable.
-This can similiarly be used with a suitable package configuration file and
-package version file to define a package for the build tree which may be used
-without installation.  Consumers of the build tree can simply ensure that the
-:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
-``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
-
 This can also be extended to cover dependencies:
 
 .. code-block:: cmake
@@ -526,6 +459,111 @@ could not be found because an invalid component was specified.  This message
 variable can be set for any case where the ``_FOUND`` variable is set to ``False``,
 and will be displayed to the user.
 
+Creating a Package Configuration File for the Build Tree
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
+definition file which is specific to the build-tree, and is not relocatable.
+This can similiarly be used with a suitable package configuration file and
+package version file to define a package for the build tree which may be used
+without installation.  Consumers of the build tree can simply ensure that the
+:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
+``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
+
+.. _`Creating Relocatable Packages`:
+
+Creating Relocatable Packages
+-----------------------------
+
+A relocatable package must not reference absolute paths of files on
+the machine where the package is built that will not exist on the
+machines where the package may be installed.
+
+Packages created by :command:`install(EXPORT)` are designed to be relocatable,
+using paths relative to the location of the package itself.  When defining
+the interface of a target for ``EXPORT``, keep in mind that the include
+directories should be specified as relative paths which are relative to the
+:variable:`CMAKE_INSTALL_PREFIX`:
+
+.. code-block:: cmake
+
+  target_include_directories(tgt INTERFACE
+    # Wrong, not relocatable:
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
+  )
+
+  target_include_directories(tgt INTERFACE
+    # Ok, relocatable:
+    $<INSTALL_INTERFACE:include/TgtName>
+  )
+
+The ``$<INSTALL_PREFIX>``
+:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
+a placeholder for the install prefix without resulting in a non-relocatable
+package.  This is necessary if complex generator expressions are used:
+
+.. code-block:: cmake
+
+  target_include_directories(tgt INTERFACE
+    # Ok, relocatable:
+    $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
+  )
+
+This also applies to paths referencing external dependencies.
+It is not advisable to populate any properties which may contain
+paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies.
+For example, this code may not work well for a relocatable package:
+
+.. code-block:: cmake
+
+  target_link_libraries(ClimbingStats INTERFACE
+    ${Foo_LIBRARIES} ${Bar_LIBRARIES}
+    )
+  target_include_directories(ClimbingStats INTERFACE
+    "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
+    )
+
+The referenced variables may contain the absolute paths to libraries
+and include directories **as found on the machine the package was made on**.
+This would create a package with hard-coded paths to dependencies and not
+suitable for relocation.
+
+Ideally such dependencies should be used through their own
+:ref:`IMPORTED targets <Imported Targets>` that have their own
+:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties
+such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated
+appropriately.  Those imported targets may then be used with
+the :command:`target_link_libraries` command for ``ClimbingStats``:
+
+.. code-block:: cmake
+
+  target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
+
+With this approach the package references its external dependencies
+only through the names of :ref:`IMPORTED targets <Imported Targets>`.
+When a consumer uses the installed package, the consumer will run the
+appropriate :command:`find_package` commands (via the ``find_dependency``
+macro described above) to find the dependencies and populate the
+imported targets with appropriate paths on their own machine.
+
+Unfortunately many :manual:`modules <cmake-modules(7)>` shipped with
+CMake do not yet provide :ref:`IMPORTED targets <Imported Targets>`
+because their development pre-dated this approach.  This may improve
+incrementally over time.  Workarounds to create relocatable packages
+using such modules include:
+
+* When building the package, specify each ``Foo_LIBRARY`` cache
+  entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``.  This
+  tells the corresponding find module to populate the ``Foo_LIBRARIES``
+  with just ``foo`` to ask the linker to search for the library
+  instead of hard-coding a path.
+
+* Or, after installing the package content but before creating the
+  package installation binary for redistribution, manually replace
+  the absolute paths with placeholders for substitution by the
+  installation tool when the package is installed.
+
 .. _`Package Registry`:
 
 Package Registry

Help/manual/cmake-policies.7.rst

@@ -20,11 +20,11 @@ for a policy, also avoiding the warning.  Each policy can also be set to
 either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
 :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
 
-Note that policies are not reliable feature toggles.  A policy should
+A policy is a deprecation mechanism and not a reliable feature toggle.
-almost never be set to ``OLD``, except to silence warnings in an otherwise
+A policy should almost never be set to ``OLD``, except to silence warnings
-frozen or stable codebase, or temporarily as part of a larger migration
+in an otherwise frozen or stable codebase, or temporarily as part of a
-path. The ``OLD`` behavior of each policy is undesirable and will be
+larger migration path. The ``OLD`` behavior of each policy is undesirable
-replaced with an error condition in a future release.
+and will be replaced with an error condition in a future release.
 
 The :command:`cmake_minimum_required` command does more than report an
 error if a too-old version of CMake is used to build a project.  It
@@ -114,3 +114,10 @@ All Policies
    /policy/CMP0054
    /policy/CMP0055
    /policy/CMP0056
+   /policy/CMP0057
+   /policy/CMP0058
+   /policy/CMP0059
+   /policy/CMP0060
+   /policy/CMP0061
+   /policy/CMP0062
+   /policy/CMP0063

Help/manual/cmake-properties.7.rst

@@ -7,6 +7,8 @@ cmake-properties(7)
 
    .. contents::
 
+.. _`Global Properties`:
+
 Properties of Global Scope
 ==========================
 
@@ -41,6 +43,8 @@ Properties of Global Scope
    /prop_gbl/TARGET_SUPPORTS_SHARED_LIBS
    /prop_gbl/USE_FOLDERS
 
+.. _`Directory Properties`:
+
 Properties on Directories
 =========================
 
@@ -72,6 +76,8 @@ Properties on Directories
    /prop_dir/VS_GLOBAL_SECTION_POST_section
    /prop_dir/VS_GLOBAL_SECTION_PRE_section
 
+.. _`Target Properties`:
+
 Properties on Targets
 =====================
 
@@ -113,6 +119,7 @@ Properties on Targets
    /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
    /prop_tgt/CONFIG_OUTPUT_NAME
    /prop_tgt/CONFIG_POSTFIX
+   /prop_tgt/CROSSCOMPILING_EMULATOR
    /prop_tgt/CXX_EXTENSIONS
    /prop_tgt/CXX_STANDARD
    /prop_tgt/CXX_STANDARD_REQUIRED
@@ -170,6 +177,7 @@ Properties on Targets
    /prop_tgt/JOB_POOL_COMPILE
    /prop_tgt/JOB_POOL_LINK
    /prop_tgt/LABELS
+   /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE
    /prop_tgt/LANG_VISIBILITY_PRESET
    /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG
    /prop_tgt/LIBRARY_OUTPUT_DIRECTORY
@@ -243,6 +251,9 @@ Properties on Targets
    /prop_tgt/VS_WINRT_REFERENCES
    /prop_tgt/WIN32_EXECUTABLE
    /prop_tgt/XCODE_ATTRIBUTE_an-attribute
+   /prop_tgt/XCTEST
+
+.. _`Test Properties`:
 
 Properties on Tests
 ===================
@@ -268,6 +279,8 @@ Properties on Tests
    /prop_test/WILL_FAIL
    /prop_test/WORKING_DIRECTORY
 
+.. _`Source File Properties`:
+
 Properties on Source Files
 ==========================
 
@@ -297,10 +310,13 @@ Properties on Source Files
    /prop_sf/VS_SHADER_FLAGS
    /prop_sf/VS_SHADER_MODEL
    /prop_sf/VS_SHADER_TYPE
+   /prop_sf/VS_XAML_TYPE
    /prop_sf/WRAP_EXCLUDE
    /prop_sf/XCODE_EXPLICIT_FILE_TYPE
    /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE
 
+.. _`Cache Entry Properties`:
+
 Properties on Cache Entries
 ===========================
 
@@ -314,19 +330,24 @@ Properties on Cache Entries
    /prop_cache/TYPE
    /prop_cache/VALUE
 
+.. _`Installed File Properties`:
+
 Properties on Installed Files
 =============================
 
 .. toctree::
    :maxdepth: 1
 
+   /prop_inst/CPACK_DESKTOP_SHORTCUTS.rst
    /prop_inst/CPACK_NEVER_OVERWRITE.rst
    /prop_inst/CPACK_PERMANENT.rst
+   /prop_inst/CPACK_START_MENU_SHORTCUTS.rst
+   /prop_inst/CPACK_STARTUP_SHORTCUTS.rst
    /prop_inst/CPACK_WIX_ACL.rst
 
 
 Deprecated Properties on Directories
-=====================================
+====================================
 
 .. toctree::
    :maxdepth: 1

Help/manual/cmake-variables.7.rst

@@ -25,6 +25,7 @@ Variables that Provide Information
    /variable/CMAKE_CFG_INTDIR
    /variable/CMAKE_COMMAND
    /variable/CMAKE_CROSSCOMPILING
+   /variable/CMAKE_CROSSCOMPILING_EMULATOR
    /variable/CMAKE_CTEST_COMMAND
    /variable/CMAKE_CURRENT_BINARY_DIR
    /variable/CMAKE_CURRENT_LIST_DIR
@@ -181,6 +182,7 @@ Variables that Describe the System
    /variable/CMAKE_SYSTEM_VERSION
    /variable/CYGWIN
    /variable/ENV
+   /variable/GHS-MULTI
    /variable/MINGW
    /variable/MSVC10
    /variable/MSVC11
@@ -211,6 +213,7 @@ Variables that Control the Build
    /variable/CMAKE_ANDROID_API_MIN
    /variable/CMAKE_ANDROID_GUI
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
+   /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_AUTOMOC_MOC_OPTIONS
    /variable/CMAKE_AUTOMOC
    /variable/CMAKE_AUTORCC
@@ -232,8 +235,10 @@ Variables that Control the Build
    /variable/CMAKE_INSTALL_NAME_DIR
    /variable/CMAKE_INSTALL_RPATH
    /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH
+   /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE
    /variable/CMAKE_LANG_VISIBILITY_PRESET
    /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY
+   /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_LIBRARY_PATH_FLAG
    /variable/CMAKE_LINK_DEF_FILE_FLAG
    /variable/CMAKE_LINK_DEPENDS_NO_SHARED
@@ -254,6 +259,7 @@ Variables that Control the Build
    /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_POSITION_INDEPENDENT_CODE
    /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
+   /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
    /variable/CMAKE_SHARED_LINKER_FLAGS
    /variable/CMAKE_SKIP_BUILD_RPATH
@@ -263,6 +269,7 @@ Variables that Control the Build
    /variable/CMAKE_TRY_COMPILE_CONFIGURATION
    /variable/CMAKE_USE_RELATIVE_PATHS
    /variable/CMAKE_VISIBILITY_INLINES_HIDDEN
+   /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
    /variable/CMAKE_WIN32_EXECUTABLE
    /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
    /variable/EXECUTABLE_OUTPUT_PATH
@@ -306,6 +313,10 @@ Variables for Languages
    /variable/CMAKE_LANG_FLAGS_RELEASE
    /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
    /variable/CMAKE_LANG_FLAGS
+   /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG
+   /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL
+   /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE
+   /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO
    /variable/CMAKE_LANG_IGNORE_EXTENSIONS
    /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES
    /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES

Help/manual/cmake.1.rst

@@ -9,7 +9,7 @@ Synopsis
 .. parsed-literal::
 
  cmake [<options>] (<path-to-source> | <path-to-existing-build>)
- cmake [(-D<var>=<value>)...] -P <cmake-script-file>
+ cmake [(-D <var>=<value>)...] -P <cmake-script-file>
  cmake --build <dir> [<options>] [-- <build-tool-options>...]
  cmake -E <command> [<options>...]
  cmake --find-package <options>...
@@ -215,6 +215,10 @@ Available commands are:
     names start in ``-``.
   ``--mtime=<date>``
     Specify modification time recorded in tarball entries.
+  ``--format=<format>``
+    Specify the format of the archive to be created.
+    Supported formats are: ``7zip``, ``gnutar``, ``pax``,
+    ``paxr`` (restricted pax, default), and ``zip``.
 
 ``time <command> [<args>...]``
   Run command and return elapsed time.

Help/manual/ctest.1.rst

@@ -48,7 +48,9 @@ Options
  useful for debugging dashboard problems.
 
 ``--output-on-failure``
- Output anything outputted by the test program if the test should fail.  This option can also be enabled by setting the environment variable CTEST_OUTPUT_ON_FAILURE
+ Output anything outputted by the test program if the test should fail.
+ This option can also be enabled by setting the environment variable
+ ``CTEST_OUTPUT_ON_FAILURE``.
 
 ``-F``
  Enable failover.
@@ -62,7 +64,7 @@ Options
 
  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.
+ environment variable ``CTEST_PARALLEL_LEVEL``.
 
 ``-Q,--quiet``
  Make ctest quiet.
@@ -194,6 +196,11 @@ Options
  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>``
+ Require each test to run ``<n>`` times without failing in order to pass.
+
+ This is useful in finding sporadic failures in test cases.
+
 ``--max-width <width>``
  Set the max width for a test name to output
 
@@ -365,6 +372,8 @@ Options
 
 .. include:: OPTIONS_HELP.txt
 
+.. _`Dashboard Client`:
+
 Dashboard Client
 ================
 
@@ -568,7 +577,7 @@ Configuration settings to specify the version control tool include:
   * :module:`CTest` module variable: ``GITCOMMAND``
 
 ``GITUpdateCustom``
-  Specify a semicolon-separated list of custom command lines to run
+  Specify a custom command line (as a semicolon-separated list) to run
   in the source tree (Git work tree) to update it instead of running
   the ``GITCommand``.
 
@@ -612,7 +621,7 @@ Configuration settings to specify the version control tool include:
   * :module:`CTest` module variable: ``CTEST_P4_OPTIONS``
 
 ``P4UpdateCustom``
-  Specify a semicolon-separated list of custom command lines to run
+  Specify a custom command line (as a semicolon-separated list) to run
   in the source tree (Perforce tree) to update it instead of running
   the ``P4Command``.
 
@@ -742,8 +751,9 @@ Configuration settings include:
     initialized by the :command:`build_command` command
 
 ``UseLaunchers``
-  For build trees generated by CMake using a Makefile generator
+  For build trees generated by CMake using one of the
-  or the :generator:`Ninja` generator, specify whether the
+  :ref:`Makefile Generators` or the :generator:`Ninja`
+  generator, specify whether the
   ``CTEST_USE_LAUNCHERS`` feature is enabled by the
   :module:`CTestUseLaunchers` module (also included by the
   :module:`CTest` module).  When enabled, the generated build

Help/module/CheckFortranCompilerFlag.rst

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

Help/module/FindXCTest.rst

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

Help/policy/CMP0000.rst

@@ -28,3 +28,5 @@ a warning.  An included file may set CMP0000 explicitly to affect how
 this policy is enforced for the main CMakeLists.txt file.
 
 This policy was introduced in CMake version 2.6.0.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0001.rst

@@ -17,3 +17,5 @@ below.
 This policy was introduced in CMake version 2.6.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0002.rst

@@ -24,3 +24,5 @@ property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).
 This policy was introduced in CMake version 2.6.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0003.rst

@@ -100,3 +100,5 @@ when setting the policy once will probably fix all targets.
 This policy was introduced in CMake version 2.6.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0004.rst

@@ -21,3 +21,5 @@ target is created by an add_executable or add_library command.
 This policy was introduced in CMake version 2.6.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0005.rst

@@ -22,3 +22,5 @@ limitations of the escaping implementation.
 This policy was introduced in CMake version 2.6.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0006.rst

@@ -20,3 +20,5 @@ without a BUNDLE DESTINATION.
 This policy was introduced in CMake version 2.6.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0007.rst

@@ -13,3 +13,5 @@ empty elements in a list.
 This policy was introduced in CMake version 2.6.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0008.rst

@@ -30,3 +30,5 @@ pass it directly to the native build tool unchanged.
 This policy was introduced in CMake version 2.6.1.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0009.rst

@@ -17,3 +17,5 @@ as an additional argument to the FILE command.
 This policy was introduced in CMake version 2.6.2.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0010.rst

@@ -16,3 +16,5 @@ and is treated as always being ``NEW``.
 This policy was introduced in CMake version 2.6.3.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0011.rst

@@ -20,3 +20,5 @@ cmake_policy PUSH and POP.
 This policy was introduced in CMake version 2.6.3.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0012.rst

@@ -23,3 +23,5 @@ dereferencing variables with such names.
 This policy was introduced in CMake version 2.8.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0013.rst

@@ -17,3 +17,5 @@ with an error.
 This policy was introduced in CMake version 2.8.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0014.rst

@@ -13,3 +13,5 @@ behavior for this policy is to report an error.
 This policy was introduced in CMake version 2.8.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0015.rst

@@ -15,3 +15,5 @@ paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR.
 This policy was introduced in CMake version 2.8.1.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0016.rst

@@ -11,3 +11,5 @@ in this case.
 This policy was introduced in CMake version 2.8.3.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0017.rst

@@ -17,3 +17,5 @@ from the CMake modules directory.
 This policy was introduced in CMake version 2.8.4.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0018.rst

@@ -30,3 +30,5 @@ honor the POSITION_INDEPENDENT_CODE target property.
 This policy was introduced in CMake version 2.8.9.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0019.rst

@@ -18,3 +18,5 @@ the values untouched.
 This policy was introduced in CMake version 2.8.11.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0020.rst

@@ -23,3 +23,5 @@ automatically when they link to QtCore IMPORTED target.
 This policy was introduced in CMake version 2.8.11.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0021.rst

@@ -16,3 +16,5 @@ relative path.
 This policy was introduced in CMake version 2.8.12.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0022.rst

@@ -35,3 +35,5 @@ property for in-build targets, and ignore the old properties matching
 This policy was introduced in CMake version 2.8.12.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0023.rst

@@ -31,3 +31,5 @@ signatures.
 This policy was introduced in CMake version 2.8.12.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0024.rst

@@ -20,3 +20,5 @@ allow including the result of an export() command.
 This policy was introduced in CMake version 3.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0025.rst

@@ -25,3 +25,5 @@ by default when this policy is not set and simply uses OLD behavior.
 See documentation of the
 :variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
 variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0026.rst

@@ -1,7 +1,7 @@
 CMP0026
 -------
 
-Disallow use of the LOCATION target property.
+Disallow use of the LOCATION property for build targets.
 
 CMake 2.8.12 and lower allowed reading the LOCATION target
 property (and configuration-specific variants) to
@@ -24,3 +24,5 @@ not to allow reading the LOCATION properties from build-targets.
 This policy was introduced in CMake version 3.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0027.rst

@@ -23,3 +23,5 @@ conditionally linked IMPORTED target does not exist.
 This policy was introduced in CMake version 3.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0028.rst

@@ -21,3 +21,5 @@ double-colons but is not an IMPORTED target or an ALIAS target.
 This policy was introduced in CMake version 3.0.  CMake version
 |release| warns when the policy is not set and uses OLD behavior.  Use
 the cmake_policy command to set it to OLD or NEW explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0029.rst

@@ -8,3 +8,5 @@ but was kept in CMake for compatibility for a long time.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0030.rst

@@ -9,3 +9,5 @@ not used it in years.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0031.rst

@@ -11,3 +11,5 @@ the CMake process.  It has been mostly superseded by the
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0032.rst

@@ -11,3 +11,5 @@ functionality is better achieved through dedicated outside tools.
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0033.rst

@@ -12,3 +12,5 @@ The functionality has been superseded by the :command:`export` and
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0034.rst

@@ -9,3 +9,5 @@ generate other files.  This approach has long been replaced by
 
 .. |disallowed_version| replace:: 3.0
 .. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt