New upstream version 3.18.2

.clang-format

@@ -22,7 +22,9 @@ IncludeBlocks: Regroup
 IncludeCategories:
   - Regex:           '^[<"]cmConfigure\.h'
     Priority:        -1
-  - Regex:           '^(<|")cm/'
+  - Regex:           '^<queue>'
+    Priority:        1
+  - Regex:           '^(<|")cm(ext)?/'
     Priority:        2
   - Regex:           '^(<|")windows\.h'
     Priority:        3
@@ -30,16 +32,18 @@ IncludeCategories:
     Priority:        5
   - Regex:           '^(<|")Qt?[A-Z]'
     Priority:        6
-  - Regex:           '^(<|")cmsys/'
+  - Regex:           '^<cmtp/'
     Priority:        7
-  - Regex:           '^(<|")cm_'
+  - Regex:           '^(<|")cmsys/'
     Priority:        8
-  - Regex:           '^(<|")cm[A-Z][^.]+\.h'
+  - Regex:           '^(<|")cm_'
     Priority:        9
+  - Regex:           '^(<|")cm[A-Z][^.]+\.h'
+    Priority:        10
   - Regex:           '^<[^.]+\.h'
     Priority:        4
   - Regex:           '^<'
     Priority:        1
   - Regex:           '.*'
-    Priority:        10
+    Priority:        11
 ...

.clang-tidy

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

Auxiliary/CMakeLists.txt

@@ -1,4 +1,16 @@
-install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMAKE_DATA_DIR}/editors/vim)
+# Install Vim files to a typical system integration directory.
-install(FILES cmake-mode.el DESTINATION ${CMAKE_DATA_DIR}/editors/emacs)
+# Packagers can set CMake_INSTALL_VIMFILES_DIR to control this.
+if(NOT CMake_INSTALL_VIMFILES_DIR)
+  set(CMake_INSTALL_VIMFILES_DIR ${CMAKE_XDGDATA_DIR}/vim/vimfiles)
+endif()
+install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMake_INSTALL_VIMFILES_DIR})
+
+# Install Emacs files to a typical system integration directory.
+# Packagers can set CMake_INSTALL_EMACS_DIR to control this.
+if(NOT CMake_INSTALL_EMACS_DIR)
+  set(CMake_INSTALL_EMACS_DIR ${CMAKE_XDGDATA_DIR}/emacs/site-lisp)
+endif()
+install(FILES cmake-mode.el DESTINATION ${CMake_INSTALL_EMACS_DIR})
+
 install(FILES cmake.m4 DESTINATION ${CMAKE_XDGDATA_DIR}/aclocal)
 add_subdirectory (bash-completion)

Auxiliary/bash-completion/CMakeLists.txt

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

Auxiliary/vim/syntax/cmake.vim

@@ -101,6 +101,7 @@ syn keyword cmakeProperty contained
             \ CLEAN_NO_CUSTOM
             \ CMAKE_CONFIGURE_DEPENDS
             \ CMAKE_CXX_KNOWN_FEATURES
+            \ CMAKE_CUDA_KNOWN_FEATURES
             \ CMAKE_C_KNOWN_FEATURES
             \ CMAKE_ROLE
             \ COMMON_LANGUAGE_RUNTIME
@@ -169,6 +170,7 @@ syn keyword cmakeProperty contained
             \ FRAMEWORK_VERSION
             \ Fortran_FORMAT
             \ Fortran_MODULE_DIRECTORY
+            \ Fortran_PREPROCESS
             \ GENERATED
             \ GENERATOR_FILE_NAME
             \ GENERATOR_IS_MULTI_CONFIG
@@ -220,6 +222,7 @@ syn keyword cmakeProperty contained
             \ JOB_POOLS
             \ JOB_POOL_COMPILE
             \ JOB_POOL_LINK
+            \ JOB_POOL_PRECOMPILE_HEADER
             \ KEEP_EXTENSION
             \ LABELS
             \ LANGUAGE
@@ -725,6 +728,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_CUDA_COMPILER_AR
             \ CMAKE_CUDA_COMPILER_ARCHITECTURE_ID
             \ CMAKE_CUDA_COMPILER_EXTERNAL_TOOLCHAIN
+            \ CMAKE_CUDA_COMPILE_FEATURES
             \ CMAKE_CUDA_COMPILER_ID
             \ CMAKE_CUDA_COMPILER_LAUNCHER
             \ CMAKE_CUDA_COMPILER_LOADED
@@ -1016,6 +1020,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_Fortran_MODULE_DIRECTORY
             \ CMAKE_Fortran_OUTPUT_EXTENSION
             \ CMAKE_Fortran_PLATFORM_ID
+            \ CMAKE_Fortran_PREPROCESS
             \ CMAKE_Fortran_SIMULATE_ID
             \ CMAKE_Fortran_SIMULATE_VERSION
             \ CMAKE_Fortran_SIZEOF_DATA_PTR
@@ -1064,6 +1069,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_JOB_POOLS
             \ CMAKE_JOB_POOL_COMPILE
             \ CMAKE_JOB_POOL_LINK
+            \ CMAKE_JOB_POOL_PRECOMPILE_HEADER
             \ CMAKE_Java
             \ CMAKE_Java_ANDROID_TOOLCHAIN_MACHINE
             \ CMAKE_Java_ANDROID_TOOLCHAIN_PREFIX
@@ -2862,6 +2868,11 @@ syn keyword cmakeKWtarget_link_options contained
             \ _LINKER_WRAPPER_FLAG
             \ _LINKER_WRAPPER_FLAG_SEP
 
+syn keyword cmakeKWtarget_precompile_headers contained
+            \ INTERFACE
+            \ PRIVATE
+            \ PUBLIC
+
 syn keyword cmakeKWtarget_sources contained
             \ ALIAS
             \ IMPORTED
@@ -3166,6 +3177,7 @@ syn keyword cmakeCommand
             \ target_link_directories
             \ target_link_libraries
             \ target_link_options
+            \ target_precompile_headers
             \ target_sources
             \ try_compile
             \ try_run
@@ -3322,6 +3334,7 @@ hi def link cmakeKWtarget_include_directories ModeMsg
 hi def link cmakeKWtarget_link_directories ModeMsg
 hi def link cmakeKWtarget_link_libraries ModeMsg
 hi def link cmakeKWtarget_link_options ModeMsg
+hi def link cmakeKWtarget_precompile_headers ModeMsg
 hi def link cmakeKWtarget_sources ModeMsg
 hi def link cmakeKWtry_compile ModeMsg
 hi def link cmakeKWtry_run ModeMsg

CMakeLists.txt

@@ -37,7 +37,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
   if(CMAKE_SYSTEM_NAME STREQUAL "HP-UX")
     message(FATAL_ERROR
       "CMake no longer compiles on HP-UX.  See\n"
-      "  https://gitlab.kitware.com/cmake/cmake/issues/17137\n"
+      "  https://gitlab.kitware.com/cmake/cmake/-/issues/17137\n"
       "Use CMake 3.9 or lower instead."
       )
   endif()
@@ -154,7 +154,7 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
 
   # Allow the user to enable/disable all system utility library options by
   # defining CMAKE_USE_SYSTEM_LIBRARIES or CMAKE_USE_SYSTEM_LIBRARY_${util}.
-  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV ZLIB ZSTD)
+  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV NGHTTP2 ZLIB ZSTD)
   foreach(util ${UTILITIES})
     if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
         AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
@@ -192,6 +192,8 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
     "${CMAKE_USE_SYSTEM_LIBRARY_ZSTD}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
   CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_LIBLZMA "Use system-installed liblzma"
     "${CMAKE_USE_SYSTEM_LIBRARY_LIBLZMA}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
+  CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_NGHTTP2 "Use system-installed nghttp2"
+    "${CMAKE_USE_SYSTEM_LIBRARY_NGHTTP2}" "NOT CMAKE_USE_SYSTEM_CURL" ON)
   option(CMAKE_USE_SYSTEM_FORM "Use system-installed libform" "${CMAKE_USE_SYSTEM_LIBRARY_FORM}")
   option(CMAKE_USE_SYSTEM_JSONCPP "Use system-installed jsoncpp" "${CMAKE_USE_SYSTEM_LIBRARY_JSONCPP}")
   option(CMAKE_USE_SYSTEM_LIBRHASH "Use system-installed librhash" "${CMAKE_USE_SYSTEM_LIBRARY_LIBRHASH}")
@@ -264,7 +266,6 @@ macro(CMAKE_SETUP_TESTING)
       ${CMake_BINARY_DIR}/Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
   endif()
   mark_as_advanced(DART_ROOT)
-  mark_as_advanced(CURL_TESTING)
 endmacro()
 
 
@@ -336,6 +337,9 @@ endmacro()
 macro (CMAKE_BUILD_UTILITIES)
   find_package(Threads)
 
+  # Suppress unnecessary checks in third-party code.
+  include(Utilities/cmThirdPartyChecks.cmake)
+
   #---------------------------------------------------------------------
   # Create the kwsys library for CMake.
   set(KWSYS_NAMESPACE cmsys)
@@ -352,6 +356,21 @@ macro (CMAKE_BUILD_UTILITIES)
   if(CMake_NO_CXX_STANDARD)
     set(KWSYS_CXX_STANDARD "")
   endif()
+  if(WIN32)
+    # FIXME: Teach KWSys to hard-code these checks on Windows.
+    set(KWSYS_C_HAS_CLOCK_GETTIME_MONOTONIC_COMPILED 0)
+    set(KWSYS_C_HAS_PTRDIFF_T_COMPILED 1)
+    set(KWSYS_CXX_HAS_ENVIRON_IN_STDLIB_H_COMPILED 1)
+    set(KWSYS_CXX_HAS_RLIMIT64_COMPILED 0)
+    set(KWSYS_CXX_HAS_SETENV_COMPILED 0)
+    set(KWSYS_CXX_HAS_UNSETENV_COMPILED 0)
+    set(KWSYS_CXX_HAS_UTIMENSAT_COMPILED 0)
+    set(KWSYS_CXX_HAS_UTIMES_COMPILED 0)
+    set(KWSYS_CXX_STAT_HAS_ST_MTIM_COMPILED 0)
+    set(KWSYS_CXX_STAT_HAS_ST_MTIMESPEC_COMPILED 0)
+    set(KWSYS_STL_HAS_WSTRING_COMPILED 1)
+    set(KWSYS_SYS_HAS_IFADDRS_H 0)
+  endif()
   add_subdirectory(Source/kwsys)
   set(kwsys_folder "Utilities/KWSys")
   CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE} "${kwsys_folder}")
@@ -368,17 +387,20 @@ macro (CMAKE_BUILD_UTILITIES)
   # Setup third-party libraries.
   # Everything in the tree should be able to include files from the
   # Utilities directory.
-  if (CMAKE_SYSTEM_NAME STREQUAL "AIX" AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+  if ((CMAKE_SYSTEM_NAME STREQUAL "AIX" OR CMAKE_SYSTEM_NAME STREQUAL "OS400") AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     # using -isystem option generate error "template with C linkage"
     include_directories("${CMake_SOURCE_DIR}/Utilities/std")
   else()
     include_directories(SYSTEM "${CMake_SOURCE_DIR}/Utilities/std")
   endif()
 
-  include_directories(
+  include_directories("${CMake_BINARY_DIR}/Utilities")
-    ${CMake_BINARY_DIR}/Utilities
+  if ((CMAKE_SYSTEM_NAME STREQUAL "AIX" OR CMAKE_SYSTEM_NAME STREQUAL "OS400") AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-    ${CMake_SOURCE_DIR}/Utilities
+    # using -isystem option generate error "template with C linkage"
-    )
+    include_directories("${CMake_SOURCE_DIR}/Utilities")
+  else()
+    include_directories(SYSTEM "${CMake_SOURCE_DIR}/Utilities")
+  endif()
 
   #---------------------------------------------------------------------
   # Build CMake std library for CMake and CTest.
@@ -431,6 +453,13 @@ macro (CMAKE_BUILD_UTILITIES)
   else()
     set(CMAKE_ZLIB_INCLUDES ${CMake_SOURCE_DIR}/Utilities)
     set(CMAKE_ZLIB_LIBRARIES cmzlib)
+    set(WITHOUT_ZLIB_DLL "")
+    set(WITHOUT_ZLIB_DLL_WITH_LIB cmzlib)
+    set(ZLIB_DLL "")
+    set(ZLIB_DLL_WITH_LIB cmzlib)
+    set(ZLIB_WINAPI "")
+    set(ZLIB_WINAPI_COMPILED 0)
+    set(ZLIB_WINAPI_WITH_LIB cmzlib)
     add_subdirectory(Utilities/cmzlib)
     CMAKE_SET_TARGET_FOLDER(cmzlib "Utilities/3rdParty")
   endif()
@@ -466,9 +495,19 @@ macro (CMAKE_BUILD_UTILITIES)
       set(CURL_CA_PATH "" CACHE PATH "Path to SSL CA Certificate Directory")
       mark_as_advanced(CURL_CA_BUNDLE CURL_CA_PATH)
     endif()
+    if(NOT CMAKE_USE_SYSTEM_NGHTTP2)
+      # Tell curl's FindNGHTTP2 module to use our library.
+      set(NGHTTP2_LIBRARY cmnghttp2)
+      set(NGHTTP2_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmnghttp2/lib/includes)
+    endif()
     add_subdirectory(Utilities/cmcurl)
     CMAKE_SET_TARGET_FOLDER(cmcurl "Utilities/3rdParty")
     CMAKE_SET_TARGET_FOLDER(LIBCURL "Utilities/3rdParty")
+    if(NOT CMAKE_USE_SYSTEM_NGHTTP2)
+      # Configure after curl to re-use some check results.
+      add_subdirectory(Utilities/cmnghttp2)
+      CMAKE_SET_TARGET_FOLDER(cmnghttp2 "Utilities/3rdParty")
+    endif()
   endif()
 
   #---------------------------------------------------------------------
@@ -497,6 +536,11 @@ macro (CMAKE_BUILD_UTILITIES)
       set(BZIP2_INCLUDE_DIR
         "${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmbzip2")
       set(BZIP2_LIBRARIES cmbzip2)
+      set(BZIP2_NEED_PREFIX "")
+      set(USE_BZIP2_DLL "")
+      set(USE_BZIP2_DLL_WITH_LIB cmbzip2)
+      set(USE_BZIP2_STATIC "")
+      set(USE_BZIP2_STATIC_WITH_LIB cmbzip2)
       add_subdirectory(Utilities/cmbzip2)
       CMAKE_SET_TARGET_FOLDER(cmbzip2 "Utilities/3rdParty")
     endif()
@@ -548,21 +592,25 @@ macro (CMAKE_BUILD_UTILITIES)
     set(ZLIB_INCLUDE_DIR ${CMAKE_ZLIB_INCLUDES})
     set(ZLIB_LIBRARY ${CMAKE_ZLIB_LIBRARIES})
     add_definitions(-DLIBARCHIVE_STATIC)
+    set(ENABLE_MBEDTLS OFF CACHE INTERNAL "Enable use of mbed TLS")
     set(ENABLE_NETTLE OFF CACHE INTERNAL "Enable use of Nettle")
     set(ENABLE_OPENSSL ${CMAKE_USE_OPENSSL} CACHE INTERNAL "Enable use of OpenSSL")
+    set(ENABLE_LIBB2 OFF CACHE INTERNAL "Enable the use of the system LIBB2 library if found")
     set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system LZMA library if found")
     set(ENABLE_LZ4 OFF CACHE INTERNAL "Enable the use of the system LZ4 library if found")
     set(ENABLE_LZO OFF CACHE INTERNAL "Enable the use of the system LZO library if found")
     set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system ZLIB library if found")
     set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system BZip2 library if found")
+    set(ENABLE_ZSTD ON CACHE INTERNAL "Enable the use of the system zstd library if found")
     set(ENABLE_LIBXML2 OFF CACHE INTERNAL "Enable the use of the system libxml2 library if found")
-    set(ENABLE_EXPAT ON CACHE INTERNAL "Enable the use of the system EXPAT library if found")
+    set(ENABLE_EXPAT OFF CACHE INTERNAL "Enable the use of the system EXPAT library if found")
     set(ENABLE_PCREPOSIX OFF CACHE INTERNAL "Enable the use of the system PCREPOSIX library if found")
     set(ENABLE_LibGCC OFF CACHE INTERNAL "Enable the use of the system LibGCC library if found")
     set(ENABLE_XATTR OFF CACHE INTERNAL "Enable extended attribute support")
     set(ENABLE_ACL OFF CACHE INTERNAL "Enable ACL support")
     set(ENABLE_ICONV OFF CACHE INTERNAL "Enable iconv support")
     set(ENABLE_CNG OFF CACHE INTERNAL "Enable the use of CNG(Crypto Next Generation)")
+    SET(POSIX_REGEX_LIB "" CACHE INTERNAL "Choose what library should provide POSIX regular expression support")
     add_subdirectory(Utilities/cmlibarchive)
     CMAKE_SET_TARGET_FOLDER(cmlibarchive "Utilities/3rdParty")
     set(CMAKE_TAR_LIBRARIES cmlibarchive ${BZIP2_LIBRARIES})
@@ -671,10 +719,6 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
   set(LIBRARY_OUTPUT_PATH "" CACHE INTERNAL
     "Where to put the libraries for CMake")
 
-  # The CMake executables usually do not need any rpath to run in the build or
-  # install tree.
-  set(CMAKE_SKIP_RPATH ON CACHE INTERNAL "CMake does not need RPATHs.")
-
   # Load install destinations.
   include(Source/CMakeInstallDestinations.cmake)
 
@@ -682,10 +726,15 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
     include(${CMake_SOURCE_DIR}/Tests/CMakeInstall.cmake)
   endif()
 
-  # no clue why we are testing for this here
+  # Checks for cmSystemTools.
-  include(CheckSymbolExists)
+  if(WIN32)
-  CHECK_SYMBOL_EXISTS(unsetenv "stdlib.h" HAVE_UNSETENV)
+    set(HAVE_UNSETENV 0)
-  CHECK_SYMBOL_EXISTS(environ "stdlib.h" HAVE_ENVIRON_NOT_REQUIRE_PROTOTYPE)
+    set(HAVE_ENVIRON_NOT_REQUIRE_PROTOTYPE 1)
+  else()
+    include(CheckSymbolExists)
+    CHECK_SYMBOL_EXISTS(unsetenv "stdlib.h" HAVE_UNSETENV)
+    CHECK_SYMBOL_EXISTS(environ "stdlib.h" HAVE_ENVIRON_NOT_REQUIRE_PROTOTYPE)
+  endif()
 endif()
 
 # CMAKE_TESTS_CDASH_SERVER: CDash server used by CMake/Tests.
@@ -714,19 +763,6 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
   # build the utilities (a macro defined in this file)
   CMAKE_BUILD_UTILITIES()
 
-  # On NetBSD ncurses is required, since curses doesn't have the wsyncup()
-  # function. ncurses is installed via pkgsrc, so the library is in /usr/pkg/lib,
-  # which isn't in the default linker search path. So without RPATH ccmake
-  # doesn't run and the build doesn't succeed since ccmake is executed for
-  # generating the documentation.
-  if(BUILD_CursesDialog)
-    get_filename_component(_CURSES_DIR "${CURSES_LIBRARY}" PATH)
-    set(CURSES_NEED_RPATH FALSE)
-    if(NOT "${_CURSES_DIR}" STREQUAL "/lib" AND NOT "${_CURSES_DIR}" STREQUAL "/usr/lib" AND NOT "${_CURSES_DIR}" STREQUAL "/lib64" AND NOT "${_CURSES_DIR}" STREQUAL "/usr/lib64")
-      set(CURSES_NEED_RPATH TRUE)
-    endif()
-  endif()
-
   if(BUILD_QtDialog)
     if(APPLE)
       set(CMAKE_BUNDLE_VERSION
@@ -739,28 +775,15 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
       set(CMAKE_INSTALL_PREFIX
         "${CMAKE_INSTALL_PREFIX}CMake.app/Contents")
     endif()
-
-    set(QT_NEED_RPATH FALSE)
-    if(NOT "${QT_LIBRARY_DIR}" STREQUAL "/lib" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/usr/lib" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/lib64" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/usr/lib64")
-      set(QT_NEED_RPATH TRUE)
-    endif()
   endif()
 
-
+  if(UNIX)
-  # The same might be true on other systems for other libraries.
+    # Install executables with the RPATH set for libraries outside the build tree.
-  # Then only enable RPATH if we have are building at least with cmake 2.4,
+    # This is also suitable for binaries in the build tree.  Avoid re-link on install.
-  # since this one has much better RPATH features than cmake 2.2.
+    set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON CACHE BOOL "Install with RPATH set to find custom-built libraries.")
-  # The executables are then built with the RPATH for the libraries outside
+    set(CMAKE_BUILD_WITH_INSTALL_RPATH ON CACHE BOOL "Build with RPATH set to match install-tree RPATH.")
-  # the build tree, which is both the build and the install RPATH.
+    mark_as_advanced(CMAKE_INSTALL_RPATH_USE_LINK_PATH CMAKE_BUILD_WITH_INSTALL_RPATH)
-  if (UNIX)
+  endif()
-    if(   CMAKE_USE_SYSTEM_CURL   OR  CMAKE_USE_SYSTEM_ZLIB
-          OR  CMAKE_USE_SYSTEM_EXPAT  OR  CURSES_NEED_RPATH  OR  QT_NEED_RPATH)
-      set(CMAKE_SKIP_RPATH OFF CACHE INTERNAL "CMake built with RPATH.")
-      set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
-      set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
-    endif()
-  endif ()
-
 
   # add the uninstall support
   configure_file(
@@ -841,6 +864,10 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
     PATTERN "*.sh*" PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE
                                 GROUP_READ GROUP_EXECUTE
                                 WORLD_READ WORLD_EXECUTE
+    REGEX "/(ExportImportList|cpp)$"
+      PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE
+                  GROUP_READ GROUP_EXECUTE
+                  WORLD_READ WORLD_EXECUTE
     REGEX "Help/(dev|guide)($|/)" EXCLUDE
     )
 

CONTRIBUTING.rst

@@ -11,11 +11,11 @@ Community
 
 CMake is maintained and supported by `Kitware`_ and developed in
 collaboration with a productive community of contributors.
-Please subscribe and post to the `CMake Developers List`_ to raise
+Please post to the ``Development`` category of the `CMake Forum`_ to raise
 discussion of development topics.
 
 .. _`Kitware`: http://www.kitware.com/cmake
-.. _`CMake Developers List`: https://cmake.org/mailman/listinfo/cmake-developers
+.. _`CMake Forum`: https://discourse.cmake.org
 
 Patches
 =======

CTestConfig.cmake

@@ -1,6 +1,8 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
+# If changing this file, also update Utilities/Sphinx/CTestConfig.cmake
+
 set(CTEST_PROJECT_NAME "CMake")
 set(CTEST_NIGHTLY_START_TIME "1:00:00 UTC")
 

CTestCustom.cmake.in

@@ -11,6 +11,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "warning: \\(Long double usage is reported only once for each file"
   "warning: To disable this warning use"
   "could not be inlined"
+  "libcmexpat.*has no symbols"
   "libcmcurl.*has no symbols"
   "not sorted slower link editing will result"
   "stl_deque.h:479"
@@ -64,6 +65,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "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"
+  "ld: warning: symbol .(deflate|inflate)_copyright. has differing sizes" # system libz and QtCore disagree
   "warning.*This version of Mac OS X is unsupported"
   "clang.*: warning: argument unused during compilation: .-g"
   "note: in expansion of macro" # diagnostic context note
@@ -72,6 +74,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*rand.*isn.*t random" # we do not do crypto
   "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*srand.*seed choices are.*poor" # we do not do crypto
   "IPA warning: function.*multiply defined in"
+  "LICENSE WARNING" # PGI license expiry.  Not useful in nightly testing.
 
   # Ignore compiler summary warning, assuming prior text has matched some
   # other warning expression:
@@ -79,7 +82,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "compilation completed with warnings" # PGI
   "[0-9]+ Warning\\(s\\) detected" # SunPro
 
-# scanbuild exceptions
+  # 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.*"
@@ -98,6 +101,9 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "liblzma/common/index_encoder.c:[0-9]+:[0-9]+: warning: Value stored to .* during its initialization is never read"
   "libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
   "libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '==' is a garbage value"
+  "libuv/src/.*:[0-9]+:[0-9]+: warning: 1st function call argument is an uninitialized value"
+  "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
+  "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to .* is never read"
   )
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")

Copyright.txt

@@ -1,5 +1,5 @@
 CMake - Cross Platform Makefile Generator
-Copyright 2000-2019 Kitware, Inc. and Contributors
+Copyright 2000-2020 Kitware, Inc. and Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -99,6 +99,7 @@ The following individuals and institutions are among the Contributors:
 * Sebastian Holtermann <sebholt@xwmw.org>
 * Stephen Kelly <steveire@gmail.com>
 * Sylvain Joubert <joubert.sy@gmail.com>
+* The Qt Company Ltd.
 * Thomas Sondergaard <ts@medical-insight.com>
 * Tobias Hunger <tobias.hunger@qt.io>
 * Todd Gamblin <tgamblin@llnl.gov>

Help/command/DEVICE_LINK_OPTIONS.txt

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

Help/command/FIND_XXX.txt

@@ -15,6 +15,7 @@ The general signature is:
              [PATHS path1 [path2 ... ENV var]]
              [PATH_SUFFIXES suffix1 [suffix2 ...]]
              [DOC "cache documentation string"]
+             [REQUIRED]
              [NO_DEFAULT_PATH]
              [NO_PACKAGE_ROOT_PATH]
              [NO_CMAKE_PATH]
@@ -31,8 +32,9 @@ A cache entry named by ``<VAR>`` is created to store the result
 of this command.
 If the |SEARCH_XXX| is found the result is stored in the variable
 and the search will not be repeated unless the variable is cleared.
-If nothing is found, the result will be
+If nothing is found, the result will be ``<VAR>-NOTFOUND``.
-``<VAR>-NOTFOUND``, and the search will be attempted again the
+The ``REQUIRED`` option stops processing with an error message if nothing
+is found, otherwise the search will be attempted again the
 next time |FIND_XXX| is invoked with the same variable.
 
 Options include:
@@ -57,6 +59,9 @@ Options include:
 ``DOC``
   Specify the documentation string for the ``<VAR>`` cache entry.
 
+``REQUIRED``
+  Stop processing with an error message if nothing is found.
+
 If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
 added to the search.
 If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
@@ -138,6 +143,10 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    * |CMAKE_SYSTEM_XXX_PATH|
    * |CMAKE_SYSTEM_XXX_MAC_PATH|
 
+   The platform paths that these variables contain are locations that
+   typically include installed software. An example being ``/usr/local`` for
+   UNIX based platforms.
+
 7. Search the paths specified by the PATHS option
    or in the short-hand version of the command.
    These are typically hard-coded guesses.

Help/command/add_compile_definitions.rst

@@ -7,10 +7,12 @@ Add preprocessor definitions to the compilation of source files.
 
   add_compile_definitions(<definition> ...)
 
-Adds preprocessor definitions to the compiler command line for targets in the
+Adds preprocessor definitions to the compiler command line.
-current directory and below (whether added before or after this command is
+
-invoked). See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>`
+The preprocessor definitions are added to the :prop_dir:`COMPILE_DEFINITIONS`
-and :prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties.
+directory property for the current ``CMakeLists`` file. They are also added to
+the :prop_tgt:`COMPILE_DEFINITIONS` target property for each target in the
+current ``CMakeLists`` file.
 
 Definitions are specified using the syntax ``VAR`` or ``VAR=value``.
 Function-style definitions are not supported. CMake will automatically

Help/command/add_compile_options.rst

@@ -46,3 +46,6 @@ to use the more specific commands :command:`add_compile_definitions`
 and :command:`include_directories`.
 
 The command :command:`target_compile_options` adds target-specific options.
+
+The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
+source file.

Help/command/add_custom_command.rst

@@ -68,6 +68,9 @@ The options are:
   order-only dependencies to ensure the byproducts will be
   available before their dependents build.
 
+  The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
+  :prop_sf:`GENERATED` files during ``make clean``.
+
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,
@@ -112,24 +115,42 @@ The options are:
   build time.
 
 ``DEPENDS``
-  Specify files on which the command depends.  If any dependency is
+  Specify files on which the command depends.  Each argument is converted
-  an ``OUTPUT`` of another custom command in the same directory
+  to a dependency as follows:
-  (``CMakeLists.txt`` file) CMake automatically brings the other
+
+  1. If the argument is the name of a target (created by the
+     :command:`add_custom_target`, :command:`add_executable`, or
+     :command:`add_library` command) a target-level dependency is
+     created to make sure the target is built before any target
+     using this custom command.  Additionally, if the target is an
+     executable or library, a file-level dependency is created to
+     cause the custom command to re-run whenever the target is
+     recompiled.
+
+  2. If the argument is an absolute path, a file-level dependency
+     is created on that path.
+
+  3. If the argument is the name of a source file that has been
+     added to a target or on which a source file property has been set,
+     a file-level dependency is created on that source file.
+
+  4. If the argument is a relative path and it exists in the current
+     source directory, a file-level dependency is created on that
+     file in the current source directory.
+
+  5. Otherwise, a file-level dependency is created on that path relative
+     to the current binary directory.
+
+  If any dependency is an ``OUTPUT`` of another custom command in the same
+  directory (``CMakeLists.txt`` file), CMake automatically brings the other
   custom command into the target in which this command is built.
   A target-level dependency is added if any dependency is listed as
   ``BYPRODUCTS`` of a target or any of its build events in the same
   directory to ensure the byproducts will be available.
-  If ``DEPENDS`` is not specified the command will run whenever
+
+  If ``DEPENDS`` is not specified, the command will run whenever
   the ``OUTPUT`` is missing; if the command does not actually
-  create the ``OUTPUT`` then the rule will always run.
+  create the ``OUTPUT``, the rule will always run.
-  If ``DEPENDS`` specifies any target (created by the
-  :command:`add_custom_target`, :command:`add_executable`, or
-  :command:`add_library` command) a target-level dependency is
-  created to make sure the target is built before any target
-  using this custom command.  Additionally, if the target is an
-  executable or library a file-level dependency is created to
-  cause the custom command to re-run whenever the target is
-  recompiled.
 
   Arguments to ``DEPENDS`` may use
   :manual:`generator expressions <cmake-generator-expressions(7)>`.

Help/command/add_custom_target.rst

@@ -49,6 +49,9 @@ The options are:
   order-only dependencies to ensure the byproducts will be
   available before their dependents build.
 
+  The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
+  :prop_sf:`GENERATED` files during ``make clean``.
+
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,

Help/command/add_definitions.rst

@@ -8,9 +8,9 @@ Add -D define flags to the compilation of source files.
   add_definitions(-DFOO -DBAR ...)
 
 Adds definitions to the compiler command line for targets in the current
-directory and below (whether added before or after this command is invoked).
+directory, whether added before or after this command is invoked, and for
-This command can be used to add any flags, but it is intended to add
+the ones in sub-directories added after. This command can be used to add any
-preprocessor definitions.
+flags, but it is intended to add preprocessor definitions.
 
 .. note::
 

Help/command/add_executable.rst

@@ -1,8 +1,15 @@
 add_executable
 --------------
 
+.. only:: html
+
+  .. contents::
+
 Add an executable to the project using the specified source files.
 
+Normal Executables
+^^^^^^^^^^^^^^^^^^
+
 .. code-block:: cmake
 
   add_executable(<name> [WIN32] [MACOSX_BUNDLE]
@@ -45,7 +52,8 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
 pre-processed, and you want to have the original sources reachable from
 within IDE.
 
---------------------------------------------------------------------------
+Imported Executables
+^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: cmake
 
@@ -65,7 +73,8 @@ whose names begin in ``IMPORTED_``.  The most important such property is
 the main executable file on disk.  See documentation of the ``IMPORTED_*``
 properties for more information.
 
---------------------------------------------------------------------------
+Alias Executables
+^^^^^^^^^^^^^^^^^
 
 .. code-block:: cmake
 
@@ -74,8 +83,13 @@ properties for more information.
 Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
 be used to refer to ``<target>`` in subsequent commands.  The ``<name>``
 does not appear in the generated buildsystem as a make target.  The
-``<target>`` may not be a non-``GLOBAL``
+``<target>`` may not be an ``ALIAS``.
-:ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
+
+An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
+has scope in the directory in which the alias is created and below.
+The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
+alias is global or not.
+
 ``ALIAS`` targets can be used as targets to read properties
 from, executables for custom commands and custom targets.  They can also be
 tested for existence with the regular :command:`if(TARGET)` subcommand.

Help/command/add_library.rst

@@ -139,8 +139,13 @@ Alias Libraries
 Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
 used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
 not appear in the generated buildsystem as a make target.  The ``<target>``
-may not be a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an
+may not be an ``ALIAS``.
-``ALIAS``.
+
+An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
+has scope in the directory in which the alias is created and below.
+The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
+alias is global or not.
+
 ``ALIAS`` targets can be used as linkable targets and as targets to
 read properties from.  They can also be tested for existence with the
 regular :command:`if(TARGET)` subcommand.  The ``<name>`` may not be used

Help/command/add_link_options.rst

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

Help/command/cmake_language.rst

@@ -0,0 +1,99 @@
+cmake_language
+--------------
+
+Call meta-operations on CMake commands.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  cmake_language(`CALL`_ <command> [<args>...])
+  cmake_language(`EVAL`_ CODE <code>...)
+
+Introduction
+^^^^^^^^^^^^
+
+This command will call meta-operations on built-in CMake commands or
+those created via the :command:`macro` or :command:`function` commands.
+
+``cmake_language`` does not introduce a new variable or policy scope.
+
+Calling Commands
+^^^^^^^^^^^^^^^^
+
+.. _CALL:
+
+.. code-block:: cmake
+
+  cmake_language(CALL <command> [<args>...])
+
+Calls the named ``<command>`` with the given arguments (if any).
+For example, the code:
+
+.. code-block:: cmake
+
+  set(message_command "message")
+  cmake_language(CALL ${message_command} STATUS "Hello World!")
+
+is equivalent to
+
+.. code-block:: cmake
+
+  message(STATUS "Hello World!")
+
+.. note::
+  To ensure consistency of the code, the following commands are not allowed:
+
+  * ``if`` / ``elseif`` / ``else`` / ``endif``
+  * ``while`` / ``endwhile``
+  * ``foreach`` / ``endforeach``
+  * ``function`` / ``endfunction``
+  * ``macro`` / ``endmacro``
+
+Evaluating Code
+^^^^^^^^^^^^^^^
+
+.. _EVAL:
+
+.. code-block:: cmake
+
+  cmake_language(EVAL CODE <code>...)
+
+Evaluates the ``<code>...`` as CMake code.
+
+For example, the code:
+
+.. code-block:: cmake
+
+  set(A TRUE)
+  set(B TRUE)
+  set(C TRUE)
+  set(condition "(A AND B) OR C")
+
+  cmake_language(EVAL CODE "
+    if (${condition})
+      message(STATUS TRUE)
+    else()
+      message(STATUS FALSE)
+    endif()"
+  )
+
+is equivalent to
+
+.. code-block:: cmake
+
+  set(A TRUE)
+  set(B TRUE)
+  set(C TRUE)
+  set(condition "(A AND B) OR C")
+
+  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
+    if (${condition})
+      message(STATUS TRUE)
+    else()
+      message(STATUS FALSE)
+    endif()"
+  )
+
+  include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

Help/command/ctest_test.rst

@@ -20,9 +20,11 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
              [RESOURCE_SPEC_FILE <file>]
              [TEST_LOAD <threshold>]
              [SCHEDULE_RANDOM <ON|OFF>]
+             [STOP_ON_FAILURE]
              [STOP_TIME <time-of-day>]
              [RETURN_VALUE <result-var>]
              [CAPTURE_CMAKE_ERROR <result-var>]
+             [REPEAT <mode>:<n>]
              [QUIET]
              )
 
@@ -95,10 +97,32 @@ The options are:
   and then the ``--test-load`` command-line argument to :manual:`ctest(1)`.
   See also the ``TestLoad`` setting in the :ref:`CTest Test Step`.
 
+``REPEAT <mode>:<n>``
+  Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times.
+  The modes are:
+
+  ``UNTIL_FAIL``
+    Require each test to run ``<n>`` times without failing in order to pass.
+    This is useful in finding sporadic failures in test cases.
+
+  ``UNTIL_PASS``
+    Allow each test to run up to ``<n>`` times in order to pass.
+    Repeats tests if they fail for any reason.
+    This is useful in tolerating sporadic failures in test cases.
+
+  ``AFTER_TIMEOUT``
+    Allow each test to run up to ``<n>`` times in order to pass.
+    Repeats tests only if they timeout.
+    This is useful in tolerating sporadic timeouts in test cases
+    on busy machines.
+
 ``SCHEDULE_RANDOM <ON|OFF>``
   Launch tests in a random order.  This may be useful for detecting
   implicit test dependencies.
 
+``STOP_ON_FAILURE``
+  Stop the execution of the tests once one has failed.
+
 ``STOP_TIME <time-of-day>``
   Specify a time of day at which the tests should all stop running.
 

Help/command/execute_process.rst

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

Help/command/file.rst

@@ -19,6 +19,7 @@ Synopsis
     file({`WRITE`_ | `APPEND`_} <filename> <content>...)
     file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
     file(`GENERATE`_ OUTPUT <output-file> [...])
+    file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])
 
   `Filesystem`_
     file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
@@ -41,6 +42,10 @@ Synopsis
   `Locking`_
     file(`LOCK`_ <path> [...])
 
+  `Archiving`_
+    file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
+    file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])
+
 Reading
 ^^^^^^^
 
@@ -54,7 +59,9 @@ Reading
 Read content from a file called ``<filename>`` and store it in a
 ``<variable>``.  Optionally start from the given ``<offset>`` and
 read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
-be converted to a hexadecimal representation (useful for binary data).
+be converted to a hexadecimal representation (useful for binary data). If the
+``HEX`` option is specified, letters in the output (``a`` through ``f``) are in
+lowercase.
 
 .. _STRINGS:
 
@@ -243,8 +250,8 @@ be resolved. See below for a full description of how they work.
   List of post-exclude regexes through which to filter the names of resolved
   dependencies.
 
-These arguments can be used to blacklist unwanted system libraries when
+These arguments can be used to exclude unwanted system libraries when
-resolving the dependencies, or to whitelist libraries from a specific
+resolving the dependencies, or to include libraries from a specific
 directory. The filtering works as follows:
 
 1. If the not-yet-resolved dependency matches any of the
@@ -395,8 +402,8 @@ dependency resolution:
   Determines the path to the tool to use for dependency resolution. This is the
   actual path to ``objdump``, ``dumpbin``, or ``otool``.
 
-  If this variable is not specified, it is determined automatically by system
+  If this variable is not specified, it is determined by the value of
-  introspection.
+  ``CMAKE_OBJDUMP`` if set, else by system introspection.
 
 Writing
 ^^^^^^^
@@ -482,6 +489,44 @@ generation phase. The output file will not yet have been written when the
 ``file(GENERATE)`` command returns, it is written only after processing all
 of a project's ``CMakeLists.txt`` files.
 
+.. _CONFIGURE:
+
+.. code-block:: cmake
+
+  file(CONFIGURE OUTPUT output-file
+       CONTENT content
+       [ESCAPE_QUOTES] [@ONLY]
+       [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
+
+Generate an output file using the input given by ``CONTENT`` and substitute
+variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
+substitution rules behave the same as the :command:`configure_file` command.
+In order to match :command:`configure_file`'s behavior, generator expressions
+are not supported for both ``OUTPUT`` and ``CONTENT``.
+
+The arguments are:
+
+``OUTPUT <output-file>``
+  Specify the output file name to generate. A relative path is treated with
+  respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
+  ``<output-file>`` does not support generator expressions.
+
+``CONTENT <content>``
+  Use the content given explicitly as input.
+  ``<content>`` does not support generator expressions.
+
+``ESCAPE_QUOTES``
+  Escape any substituted quotes with backslashes (C-style).
+
+``@ONLY``
+  Restrict variable replacement to references of the form ``@VAR@``.
+  This is useful for configuring scripts that use ``${VAR}`` syntax.
+
+``NEWLINE_STYLE <style>``
+  Specify the newline style for the output file.  Specify
+  ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
+  ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
+
 Filesystem
 ^^^^^^^^^^
 
@@ -540,7 +585,7 @@ are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
 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.
+``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
 
 Examples of recursive globbing include::
 
@@ -790,6 +835,18 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 If neither ``NETRC`` option is given CMake will check variables
 ``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively.
 
+``TLS_VERIFY <ON|OFF>``
+  Specify whether to verify the server certificate for ``https://`` URLs.
+  The default is to *not* verify.
+
+``TLS_CAINFO <file>``
+  Specify a custom Certificate Authority file for ``https://`` URLs.
+
+For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
+certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
+check certificates. If neither ``TLS`` option is given CMake will check
+variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
+
 Additional options to ``DOWNLOAD`` are:
 
 ``EXPECTED_HASH ALGO=<value>``
@@ -801,19 +858,6 @@ Additional options to ``DOWNLOAD`` are:
 ``EXPECTED_MD5 <value>``
   Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
 
-``TLS_VERIFY <ON|OFF>``
-  Specify whether to verify the server certificate for ``https://`` URLs.
-  The default is to *not* verify.
-
-``TLS_CAINFO <file>``
-  Specify a custom Certificate Authority file for ``https://`` URLs.
-
-For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
-certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
-check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
-If neither ``TLS`` option is given CMake will check variables
-``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
-
 Locking
 ^^^^^^^
 
@@ -846,3 +890,66 @@ child directory or file.
 Trying to lock file twice is not allowed.  Any intermediate directories and
 file itself will be created if they not exist.  ``GUARD`` and ``TIMEOUT``
 options ignored on ``RELEASE`` operation.
+
+Archiving
+^^^^^^^^^
+
+.. _ARCHIVE_CREATE:
+
+.. code-block:: cmake
+
+  file(ARCHIVE_CREATE OUTPUT <archive>
+    PATHS <paths>...
+    [FORMAT <format>]
+    [COMPRESSION <compression>]
+    [MTIME <mtime>]
+    [VERBOSE])
+
+Creates the specified ``<archive>`` file with the files and directories
+listed in ``<paths>``.  Note that ``<paths>`` must list actual files or
+directories, wildcards are not supported.
+
+Use the ``FORMAT`` option to specify the archive format.  Supported values
+for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
+``zip``.  If ``FORMAT`` is not given, the default format is ``paxr``.
+
+Some archive formats allow the type of compression to be specified.
+The ``7zip`` and ``zip`` archive formats already imply a specific type of
+compression.  The other formats use no compression by default, but can be
+directed to do so with the ``COMPRESSION`` option.  Valid values for
+``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
+
+.. note::
+  With ``FORMAT`` set to ``raw`` only one file will be compressed with the
+  compression type specified by ``COMPRESSION``.
+
+The ``VERBOSE`` option enables verbose output for the archive operation.
+
+To specify the modification time recorded in tarball entries, use
+the ``MTIME`` option.
+
+.. _ARCHIVE_EXTRACT:
+
+.. code-block:: cmake
+
+  file(ARCHIVE_EXTRACT INPUT <archive>
+    [DESTINATION <dir>]
+    [PATTERNS <patterns>...]
+    [LIST_ONLY]
+    [VERBOSE])
+
+Extracts or lists the content of the specified ``<archive>``.
+
+The directory where the content of the archive will be extracted to can
+be specified using the ``DESTINATION`` option.  If the directory does not
+exist, it will be created.  If ``DESTINATION`` is not given, the current
+binary directory will be used.
+
+If required, you may select which files and directories to list or extract
+from the archive using the specified ``<patterns>``.  Wildcards are supported.
+If the ``PATTERNS`` option is not given, the entire archive will be listed or
+extracted.
+
+``LIST_ONLY`` will list the files in the archive rather than extract them.
+
+With ``VERBOSE``, the command will produce verbose output.

Help/command/find_package.rst

@@ -59,7 +59,7 @@ for finding the package, checking the version, and producing any needed
 messages.  Some find-modules provide limited or no support for versioning;
 check the module documentation.
 
-If the ``MODULE`` option is not specfied in the above signature,
+If the ``MODULE`` option is not specified in the above signature,
 CMake first searches for the package using Module mode. Then, if the
 package is not found, it searches again using Config mode. A user
 may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to
@@ -302,23 +302,23 @@ enabled.
    are intended to be used on the command line with a ``-DVAR=value``.
    The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
    This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
-   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``::
+   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:
 
-     CMAKE_PREFIX_PATH
+   * :variable:`CMAKE_PREFIX_PATH`
-     CMAKE_FRAMEWORK_PATH
+   * :variable:`CMAKE_FRAMEWORK_PATH`
-     CMAKE_APPBUNDLE_PATH
+   * :variable:`CMAKE_APPBUNDLE_PATH`
 
 3. Search paths specified in cmake-specific environment variables.
    These are intended to be set in the user's shell configuration,
    and therefore use the host's native path separator
    (``;`` on Windows and ``:`` on UNIX).
    This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting
-   the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``::
+   the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:
 
-     <PackageName>_DIR
+   * ``<PackageName>_DIR``
-     CMAKE_PREFIX_PATH
+   * :envvar:`CMAKE_PREFIX_PATH`
-     CMAKE_FRAMEWORK_PATH
+   * ``CMAKE_FRAMEWORK_PATH``
-     CMAKE_APPBUNDLE_PATH
+   * ``CMAKE_APPBUNDLE_PATH``
 
 4. Search paths specified by the ``HINTS`` option.  These should be paths
    computed by system introspection, such as a hint provided by the
@@ -329,9 +329,9 @@ enabled.
    skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed  or by setting the
    :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries
    ending in ``/bin`` or ``/sbin`` are automatically converted to their
-   parent directories::
+   parent directories:
 
-     PATH
+   * ``PATH``
 
 6. Search paths stored in the CMake :ref:`User Package Registry`.
    This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
@@ -345,11 +345,15 @@ enabled.
 7. Search cmake variables defined in the Platform files for the
    current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
    passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
-   to ``FALSE``::
+   to ``FALSE``:
 
-     CMAKE_SYSTEM_PREFIX_PATH
+   * :variable:`CMAKE_SYSTEM_PREFIX_PATH`
-     CMAKE_SYSTEM_FRAMEWORK_PATH
+   * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
-     CMAKE_SYSTEM_APPBUNDLE_PATH
+   * :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`
+
+   The platform paths that these variables contain are locations that
+   typically include installed software. An example being ``/usr/local`` for
+   UNIX based platforms.
 
 8. Search paths stored in the CMake :ref:`System Package Registry`.
    This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed

Help/command/foreach.rst

@@ -47,7 +47,7 @@ of undocumented behavior that may change in future releases.
 
 .. code-block:: cmake
 
-  foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
+  foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
 
 In this variant, ``<lists>`` is a whitespace or semicolon
 separated list of list-valued variables. The ``foreach``
@@ -82,3 +82,46 @@ yields
   -- X=6
   -- X=7
   -- X=8
+
+
+.. code-block:: cmake
+
+  foreach(<loop_var>... IN ZIP_LISTS <lists>)
+
+In this variant, ``<lists>`` is a whitespace or semicolon
+separated list of list-valued variables. The ``foreach``
+command iterates over each list simultaneously setting the
+iteration variables as follows:
+
+- if the only ``loop_var`` given, then it sets a series of
+  ``loop_var_N`` variables to the current item from the
+  corresponding list;
+- if multiple variable names passed, their count should match
+  the lists variables count;
+- if any of the lists are shorter, the corresponding iteration
+  variable is not defined for the current iteration.
+
+.. code-block:: cmake
+
+  list(APPEND English one two three four)
+  list(APPEND Bahasa satu dua tiga)
+
+  foreach(num IN ZIP_LISTS English Bahasa)
+      message(STATUS "num_0=${num_0}, num_1=${num_1}")
+  endforeach()
+
+  foreach(en ba IN ZIP_LISTS English Bahasa)
+      message(STATUS "en=${en}, ba=${ba}")
+  endforeach()
+
+yields
+::
+
+  -- num_0=one, num_1=satu
+  -- num_0=two, num_1=dua
+  -- num_0=three, num_1=tiga
+  -- num_0=four, num_1=
+  -- en=one, ba=satu
+  -- en=two, ba=dua
+  -- en=three, ba=tiga
+  -- en=four, ba=

Help/command/function.rst

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

Help/command/get_property.rst

@@ -10,6 +10,7 @@ Get a property.
                 DIRECTORY [<dir>]  |
                 TARGET    <target> |
                 SOURCE    <source> |
+                          [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
                 INSTALL   <file>   |
                 TEST      <test>   |
                 CACHE     <entry>  |
@@ -30,18 +31,36 @@ It must be one of the following:
   Scope defaults to the current directory but another
   directory (already processed by CMake) may be named by the
   full or relative path ``<dir>``.
+  See also the :command:`get_directory_property` command.
 
 ``TARGET``
   Scope must name one existing target.
+  See also the :command:`get_target_property` command.
 
 ``SOURCE``
-  Scope must name one source file.
+  Scope must name one source file.  By default, the source file's property
+  will be read from the current source directory's scope, but this can be
+  overridden with one of the following sub-options:
+
+  ``DIRECTORY <dir>``
+    The source file property will be read from the ``<dir>`` directory's
+    scope.  CMake must already know about that source directory, either by
+    having added it through a call to :command:`add_subdirectory` or ``<dir>``
+    being the top level source directory.  Relative paths are treated as
+    relative to the current source directory.
+
+  ``TARGET_DIRECTORY <target>``
+    The source file property will be read from the directory scope in which
+    ``<target>`` was created (``<target>`` must therefore already exist).
+
+  See also the :command:`get_source_file_property` command.
 
 ``INSTALL``
   Scope must name one installed file path.
 
 ``TEST``
   Scope must name one existing test.
+  See also the :command:`get_test_property` command.
 
 ``CACHE``
   Scope must name one cache entry.

Help/command/get_source_file_property.rst

@@ -5,15 +5,33 @@ Get a property for a source file.
 
 .. code-block:: cmake
 
-  get_source_file_property(VAR file property)
+  get_source_file_property(<variable> <file>
+                           [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
+                           <property>)
 
 Gets a property from a source file.  The value of the property is
-stored in the variable ``VAR``.  If the source property is not found, the
+stored in the specified ``<variable>``.  If the source property is not found,
-behavior depends on whether it has been defined to be an ``INHERITED`` property
+the behavior depends on whether it has been defined to be an ``INHERITED``
-or not (see :command:`define_property`).  Non-inherited properties will set
+property or not (see :command:`define_property`).  Non-inherited properties
-``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant
+will set ``variable`` to ``NOTFOUND``, whereas inherited properties will search
-parent scope as described for the :command:`define_property` command and
+the relevant parent scope as described for the :command:`define_property`
-if still unable to find the property, ``VAR`` will be set to an empty string.
+command and if still unable to find the property, ``variable`` will be set to
+an empty string.
+
+By default, the source file's property will be read from the current source
+directory's scope, but this can be overridden with one of the following
+sub-options:
+
+``DIRECTORY <dir>``
+  The source file property will be read from the ``<dir>`` directory's
+  scope.  CMake must already know about that source directory, either by
+  having added it through a call to :command:`add_subdirectory` or ``<dir>``
+  being the top level source directory.  Relative paths are treated as
+  relative to the current source directory.
+
+``TARGET_DIRECTORY <target>``
+  The source file property will be read from the directory scope in which
+  ``<target>`` was created (``<target>`` must therefore already exist).
 
 Use :command:`set_source_files_properties` to set property values.  Source
 file properties usually control how the file is built. One property that is

Help/command/get_target_property.rst

@@ -5,15 +5,15 @@ Get a property from a target.
 
 .. code-block:: cmake
 
-  get_target_property(VAR target property)
+  get_target_property(<VAR> target property)
 
 Get a property from a target.  The value of the property is stored in
-the variable ``VAR``.  If the target property is not found, the behavior
+the variable ``<VAR>``.  If the target property is not found, the behavior
 depends on whether it has been defined to be an ``INHERITED`` property
 or not (see :command:`define_property`).  Non-inherited properties will
-set ``VAR`` to ``NOTFOUND``, whereas inherited properties will search the
+set ``<VAR>`` to ``<VAR>-NOTFOUND``, whereas inherited properties will search
-relevant parent scope as described for the :command:`define_property`
+the relevant parent scope as described for the :command:`define_property`
-command and if still unable to find the property, ``VAR`` will be set to
+command and if still unable to find the property, ``<VAR>`` will be set to
 an empty string.
 
 Use :command:`set_target_properties` to set target property values.

Help/command/install.rst

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

Help/command/list.rst

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

Help/command/macro.rst

@@ -42,11 +42,15 @@ can be invoked through any of
   foo()
   Foo()
   FOO()
+  cmake_language(CALL foo)
 
 and so on. However, it is strongly recommended to stay with the
 case chosen in the macro definition.  Typically macros use
 all-lowercase names.
 
+The :command:`cmake_language(CALL ...)` command can also be used to
+invoke the macro.
+
 Arguments
 ^^^^^^^^^
 
@@ -91,6 +95,12 @@ just terminate execution of the macro; rather, control is returned
 from the scope of the macro call.  To avoid confusion, it is recommended
 to avoid :command:`return()` in macros altogether.
 
+Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`,
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`,
+:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not
+set for a macro.
+
 .. _`Argument Caveats`:
 
 Argument Caveats

Help/command/mark_as_advanced.rst

@@ -22,3 +22,9 @@ If neither ``FORCE`` nor ``CLEAR`` is specified,
 new values will be marked as advanced, but if a
 variable already has an advanced/non-advanced state,
 it will not be changed.
+
+.. note::
+
+  Policy :policy:`CMP0102` affects the behavior of the ``mark_as_advanced``
+  call. When set to ``NEW``, variables passed to this command which are not
+  already in the cache are ignored. See policy :policy:`CMP0102`.

Help/command/message.rst

@@ -1,13 +1,33 @@
 message
 -------
 
-Display a message to the user.
+Log a message.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  `General messages`_
+    message([<mode>] "message text" ...)
+
+  `Reporting checks`_
+    message(<checkState> "message text" ...)
+
+
+General messages
+^^^^^^^^^^^^^^^^
 
 .. code-block:: cmake
 
-  message([<mode>] "message to display" ...)
+  message([<mode>] "message text" ...)
 
-The optional ``<mode>`` keyword determines the type of message:
+Record the specified message text in the log.  If more than one message
+string is given, they are concatenated into a single message with no
+separator between the strings.
+
+The optional ``<mode>`` keyword determines the type of message, which
+influences the way the message is handled:
 
 ``FATAL_ERROR``
   CMake Error, stop processing and generation.
@@ -59,12 +79,104 @@ The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE``
 messages one at a time on a status line and other messages in an
 interactive pop-up box.  The ``--log-level`` command-line option to each of
 these tools can be used to control which messages will be shown.
+To make a log level persist between CMake runs, the
+:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead.
+Note that the command line option takes precedence over the cache variable.
 
-Messages of log levels ``NOTICE`` and below will also have each line preceded
+Messages of log levels ``NOTICE`` and below will have each line preceded
 by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
 a single string by concatenating its list items).  For ``STATUS`` to ``TRACE``
 messages, this indenting content will be inserted after the hyphens.
 
+Messages of log levels ``NOTICE`` and below can also have each line preceded
+with context of the form ``[some.context.example]``.  The content between the
+square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT`
+list variable to a dot-separated string.  The message context will always
+appear before any indenting content but after any automatically added leading
+hyphens. By default, message context is not shown, it has to be explicitly
+enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context``
+command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
+variable to true.  See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for
+usage examples.
+
 CMake Warning and Error message text displays using a simple markup
 language.  Non-indented text is formatted in line-wrapped paragraphs
 delimited by newlines.  Indented text is considered pre-formatted.
+
+
+Reporting checks
+^^^^^^^^^^^^^^^^
+
+A common pattern in CMake output is a message indicating the start of some
+sort of check, followed by another message reporting the result of that check.
+For example:
+
+.. code-block:: cmake
+
+  message(STATUS "Looking for someheader.h")
+  #... do the checks, set checkSuccess with the result
+  if(checkSuccess)
+    message(STATUS "Looking for someheader.h - found")
+  else()
+    message(STATUS "Looking for someheader.h - not found")
+  endif()
+
+This can be more robustly and conveniently expressed using the ``CHECK_...``
+keyword form of the ``message()`` command:
+
+.. code-block:: cmake
+
+  message(<checkState> "message" ...)
+
+where ``<checkState>`` must be one of the following:
+
+  ``CHECK_START``
+    Record a concise message about the check about to be performed.
+
+  ``CHECK_PASS``
+    Record a successful result for a check.
+
+  ``CHECK_FAIL``
+    Record an unsuccessful result for a check.
+
+When recording a check result, the command repeats the message from the most
+recently started check for which no result has yet been reported, then some
+separator characters and then the message text provided after the
+``CHECK_PASS`` or ``CHECK_FAIL`` keyword.  Check messages are always reported
+at ``STATUS`` log level.
+
+Checks may be nested and every ``CHECK_START`` should have exactly one
+matching ``CHECK_PASS`` or ``CHECK_FAIL``.
+The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add
+indenting to nested checks if desired.  For example:
+
+.. code-block:: cmake
+
+  message(CHECK_START "Finding my things")
+  list(APPEND CMAKE_MESSAGE_INDENT "  ")
+  unset(missingComponents)
+
+  message(CHECK_START "Finding partA")
+  # ... do check, assume we find A
+  message(CHECK_PASS "found")
+
+  message(CHECK_START "Finding partB")
+  # ... do check, assume we don't find B
+  list(APPEND missingComponents B)
+  message(CHECK_FAIL "not found")
+
+  list(POP_BACK CMAKE_MESSAGE_INDENT)
+  if(missingComponents)
+    message(CHECK_FAIL "missing components: ${missingComponents}")
+  else()
+    message(CHECK_PASS "all components found")
+  endif()
+
+Output from the above would appear something like the following::
+
+  -- Finding my things
+  --   Finding partA
+  --   Finding partA - found
+  --   Finding partB
+  --   Finding partB - not found
+  -- Finding my things - missing components: B

Help/command/option.rst

@@ -9,7 +9,7 @@ Provide an option that the user can optionally select.
 
 Provides an option for the user to select as ``ON`` or ``OFF``.
 If no initial ``<value>`` is provided, ``OFF`` is used.
-If ``<variable>`` is already set as a normal variable
+If ``<variable>`` is already set as a normal or cache variable,
 then the command does nothing (see policy :policy:`CMP0077`).
 
 If you have options that depend on the values of other options, see

Help/command/project.rst

@@ -102,9 +102,12 @@ options are intended for use as default values in package metadata and documenta
 Code Injection
 ^^^^^^^^^^^^^^
 
-If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file
+If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or
-pointed to by that variable will be included as the first step of the
+:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set,
+the files they point to will be included as the first step of the
 ``project()`` command.
+If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be
+included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`.
 
 If the :variable:`CMAKE_PROJECT_INCLUDE` or
 :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files

Help/command/separate_arguments.rst

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

Help/command/set_property.rst

@@ -8,12 +8,14 @@ Set a named property in a given scope.
   set_property(<GLOBAL                      |
                 DIRECTORY [<dir>]           |
                 TARGET    [<target1> ...]   |
-                SOURCE    [<src1> ...]      |
+                SOURCE    [<src1> ...]
+                          [DIRECTORY <dirs> ...] |
+                          [TARGET_DIRECTORY <targets> ...]
                 INSTALL   [<file1> ...]     |
                 TEST      [<test1> ...]     |
                 CACHE     [<entry1> ...]    >
                [APPEND] [APPEND_STRING]
-               PROPERTY <name> [value1 ...])
+               PROPERTY <name> [<value1> ...])
 
 Sets one property on zero or more objects of a scope.
 
@@ -33,9 +35,23 @@ It must be one of the following:
   See also the :command:`set_target_properties` command.
 
 ``SOURCE``
-  Scope may name zero or more source files.  Note that source
+  Scope may name zero or more source files.  By default, source file properties
-  file properties are visible only to targets added in the same
+  are only visible to targets added in the same directory (``CMakeLists.txt``).
-  directory (``CMakeLists.txt``).
+  Visibility can be set in other directory scopes using one or both of the
+  following sub-options:
+
+  ``DIRECTORY <dirs>...``
+    The source file property will be set in each of the ``<dirs>``
+    directories' scopes.  CMake must already know about each of these
+    source directories, either by having added them through a call to
+    :command:`add_subdirectory` or it being the top level source directory.
+    Relative paths are treated as relative to the current source directory.
+
+  ``TARGET_DIRECTORY <targets>...``
+    The source file property will be set in each of the directory scopes
+    where any of the specified ``<targets>`` were created (the ``<targets>``
+    must therefore already exist).
+
   See also the :command:`set_source_files_properties` command.
 
 ``INSTALL``
@@ -66,7 +82,8 @@ the property to set.  Remaining arguments are used to compose the
 property value in the form of a semicolon-separated list.
 
 If the ``APPEND`` option is given the list is appended to any existing
-property value.  If the ``APPEND_STRING`` option is given the string is
+property value (except that empty values are ignored and not appended).
+If the ``APPEND_STRING`` option is given the string is
 appended to any existing property value as string, i.e. it results in a
 longer string and not a list of strings.  When using ``APPEND`` or
 ``APPEND_STRING`` with a property defined to support ``INHERITED``

Help/command/set_source_files_properties.rst

@@ -5,15 +5,33 @@ Source files can have properties that affect how they are built.
 
 .. code-block:: cmake
 
-  set_source_files_properties([file1 [file2 [...]]]
+  set_source_files_properties(<files> ...
-                              PROPERTIES prop1 value1
+                              [DIRECTORY <dirs> ...]
-                              [prop2 value2 [...]])
+                              [TARGET_DIRECTORY <targets> ...]
+                              PROPERTIES <prop1> <value1>
+                              [<prop2> <value2>] ...)
 
 Sets properties associated with source files using a key/value paired
 list.
 
+By default, source file properties are only visible to targets added in the
+same directory (``CMakeLists.txt``).  Visibility can be set in other directory
+scopes using one or both of the following options:
+
+``DIRECTORY <dirs>...``
+  The source file properties will be set in each of the ``<dirs>``
+  directories' scopes.  CMake must already know about each of these
+  source directories, either by having added them through a call to
+  :command:`add_subdirectory` or it being the top level source directory.
+  Relative paths are treated as relative to the current source directory.
+
+``TARGET_DIRECTORY <targets>...``
+  The source file properties will be set in each of the directory scopes
+  where any of the specified ``<targets>`` were created (the ``<targets>``
+  must therefore already exist).
+
+Use :command:`get_source_file_property` to get property values.
 See also the :command:`set_property(SOURCE)` command.
 
 See :ref:`Source File Properties` for the list of properties known
-to CMake.  Source file properties are visible only to targets added
+to CMake.
-in the same directory (``CMakeLists.txt``).

Help/command/source_group.rst

@@ -37,11 +37,13 @@ explicitly lists the file with ``FILES`` will be favored, if any.
 If no group explicitly lists the file, the *last* group whose
 regular expression matches the file will be favored.
 
-The ``<name>`` of the group and ``<prefix>`` argument may contain backslashes
+The ``<name>`` of the group and ``<prefix>`` argument may contain forward
-to specify subgroups:
+slashes or backslashes to specify subgroups.  Backslashes need to be escaped
+appropriately:
 
 .. code-block:: cmake
 
+  source_group(base/subdir ...)
   source_group(outer\\inner ...)
   source_group(TREE <root> PREFIX sources\\inc ...)
 

Help/command/string.rst

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

Help/command/target_compile_features.rst

@@ -8,9 +8,9 @@ Add expected compiler features to a target.
   target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
 
 Specifies compiler features required when compiling a given target.  If the
-feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable
+feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`,
-or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable,
+:variable:`CMAKE_CUDA_COMPILE_FEATURES`, or :variable:`CMAKE_CXX_COMPILE_FEATURES`
-then an error will be reported by CMake.  If the use of the feature requires
+variables, then an error will be reported by CMake.  If the use of the feature requires
 an additional compiler flag, such as ``-std=gnu++11``, the flag will be added
 automatically.
 

Help/command/target_compile_options.rst

@@ -46,3 +46,5 @@ to use the more specific commands :command:`target_compile_definitions`
 and :command:`target_include_directories`.
 
 For directory-wide settings, there is the command :command:`add_compile_options`.
+
+For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.

Help/command/target_link_options.rst

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

Help/command/target_precompile_headers.rst

@@ -56,35 +56,34 @@ e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
 must be available for the compiler to find them.  Other header file names
 (e.g. ``project_header.h``) are interpreted as being relative to the current
 source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
-included by absolute path.
+included by absolute path.  For example:
-
-Arguments to ``target_precompile_headers()`` 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 and a list of supported compilers.
-The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
-useful for specifying a language-specific header to precompile for
-only one language (e.g. ``CXX`` and not ``C``).  For example:
 
 .. code-block:: cmake
 
   target_precompile_headers(myTarget
     PUBLIC
       project_header.h
-      "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>"
     PRIVATE
       [["other_header.h"]]
       <unordered_map>
   )
 
-When specifying angle brackets inside a :manual:`generator expression
+Arguments to ``target_precompile_headers()`` may use "generator expressions"
-<cmake-generator-expressions(7)>`, be sure to encode the closing ``>``
+with the syntax ``$<...>``.
-as ``$<ANGLE-R>``.  For example:
+See the :manual:`cmake-generator-expressions(7)` manual for available
+expressions.
+The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
+useful for specifying a language-specific header to precompile for
+only one language (e.g. ``CXX`` and not ``C``).  In this case, header
+file names that are not explicitly in double quotes or angle brackets
+must be specified by absolute path.  Also, when specifying angle brackets
+inside a generator expression, be sure to encode the closing ``>`` as
+``$<ANGLE-R>``.  For example:
 
 .. code-block:: cmake
 
   target_precompile_headers(mylib PRIVATE
+    "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
     "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
     "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
   )
@@ -94,7 +93,7 @@ Reusing Precompile Headers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The command also supports a second signature which can be used to specify that
-one target re-uses a precompiled header file artefact from another target
+one target re-uses a precompiled header file artifact from another target
 instead of generating its own:
 
 .. code-block:: cmake

Help/command/try_compile.rst

@@ -135,6 +135,7 @@ If set, the following variables are passed in to the generated
 try_compile CMakeLists.txt to initialize compile target properties with
 default values:
 
+* :variable:`CMAKE_CUDA_RUNTIME_LIBRARY`
 * :variable:`CMAKE_ENABLE_EXPORTS`
 * :variable:`CMAKE_LINK_SEARCH_START_STATIC`
 * :variable:`CMAKE_LINK_SEARCH_END_STATIC`

Help/cpack_gen/archive.rst

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

Help/cpack_gen/cygwin.rst

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

Help/cpack_gen/deb.rst

@@ -25,8 +25,8 @@ or a component GROUP name.
 Here are some CPack DEB generator wiki resources that are here for historic
 reasons and are no longer maintained but may still prove useful:
 
- - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration
+ - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration
- - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#deb-unix-only
+ - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#deb-unix-only
 
 List of CPack DEB generator specific variables:
 
@@ -282,7 +282,7 @@ List of CPack DEB generator specific variables:
    You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value
    if you use this feature, because if you don't ``dpkg-shlibdeps``
    may fail to find your own shared libs.
-   See https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling
+   See https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling
 
 .. variable:: CPACK_DEBIAN_PACKAGE_DEBUG
 

Help/cpack_gen/dmg.rst

@@ -54,10 +54,12 @@ on macOS:
 
   Directory where license and menu files for different languages are stored.
   Setting this causes CPack to look for a ``<language>.menu.txt`` and
-  ``<language>.license.txt`` file for every language defined in
+  ``<language>.license.txt`` or ``<language>.license.rtf`` file for every
-  ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and
+  language defined in ``CPACK_DMG_SLA_LANGUAGES``.  If both this variable and
   ``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu
-  files and use the same license file for all languages.
+  files and use the same license file for all languages.  If both
+  ``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt``
+  file will be used.
 
 .. variable:: CPACK_DMG_SLA_LANGUAGES
 
@@ -81,6 +83,13 @@ on macOS:
   ``<language>.menu.txt`` and ``<language>.license.txt`` in the directory
   specified by the :variable:`CPACK_DMG_SLA_DIR` variable.
 
+.. variable:: CPACK_DMG_<component>_FILE_NAME
+
+ File name when packaging ``<component>`` as its own DMG
+ (``CPACK_COMPONENTS_GROUPING`` set to IGNORE).
+
+ - Default: ``CPACK_PACKAGE_FILE_NAME-<component>``
+
 .. variable:: CPACK_COMMAND_HDIUTIL
 
  Path to the ``hdiutil(1)`` command used to operate on disk image files on

Help/cpack_gen/freebsd.rst

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

Help/cpack_gen/ifw.rst

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

Help/cpack_gen/nsis.rst

@@ -1,7 +1,9 @@
 CPack NSIS Generator
 --------------------
 
-CPack Nullsoft Scriptable Install System (NSIS) generator specific options
+CPack Nullsoft Scriptable Install System (NSIS) generator specific options.
+
+The NSIS generator requires NSIS 3.0 or newer.
 
 Variables specific to CPack NSIS generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -128,3 +130,32 @@ on Windows Nullsoft Scriptable Install System.
   set(CPACK_NSIS_MENU_LINKS
       "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html"
       "CMake Help" "https://cmake.org" "CMake Web Site")
+
+.. variable:: CPACK_NSIS_UNINSTALL_NAME
+
+ Specify the name of the program to uninstall the version.
+ Default is ``Uninstall``.
+
+.. variable:: CPACK_NSIS_WELCOME_TITLE
+
+  The title to display on the top of the page for the welcome page.
+
+.. variable:: CPACK_NSIS_WELCOME_TITLE_3LINES
+
+ Display the title in the welcome page on 3 lines instead of 2.
+
+.. variable:: CPACK_NSIS_FINISH_TITLE
+
+ The title to display on the top of the page for the finish page.
+
+.. variable:: CPACK_NSIS_FINISH_TITLE_3LINES
+
+ Display the title in the finish page on 3 lines instead of 2.
+
+.. variable:: CPACK_NSIS_MUI_HEADERIMAGE
+
+ The image to display on the header of installers pages.
+
+.. variable:: CPACK_NSIS_MANIFEST_DPI_AWARE
+
+ If set, declares that the installer is DPI-aware.

Help/cpack_gen/packagemaker.rst

@@ -3,6 +3,11 @@ CPack PackageMaker Generator
 
 PackageMaker CPack generator (macOS).
 
+.. deprecated:: 3.17
+
+  Xcode no longer distributes the PackageMaker tools.
+  This CPack generator will be removed in a future version of CPack.
+
 Variables specific to CPack PackageMaker generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -15,9 +20,60 @@ macOS using PackageMaker:
  compatible with. Different versions of macOS support different
  features. For example, CPack can only build component-based installers for
  macOS 10.4 or newer, and can only build installers that download
- component son-the-fly for macOS 10.5 or newer. If left blank, this value
+ components on-the-fly for macOS 10.5 or newer. If left blank, this value
  will be set to the minimum version of macOS that supports the requested
  features. Set this variable to some value (e.g., 10.4) only if you want to
  guarantee that your installer will work on that version of macOS, and
  don't mind missing extra features available in the installer shipping with
  later versions of macOS.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND
+
+ Adds a background to Distribtion XML if specified. The value contains the
+ path to image in ``Resources`` directory.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT
+
+ Adds an ``alignment`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING
+
+ Adds a ``scaling`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE
+
+ Adds a ``mime-type`` attribute to the background in Distribution XML.
+ The option contains MIME type of an image.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI
+
+ Adds an ``uti`` attribute to the background in Distribution XML.
+ The option contains UTI type of an image.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA
+
+ Adds a background for the Dark Aqua theme to Distribution XML if
+ specified. The value contains the path to image in ``Resources``
+ directory.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI
+
+ Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option,
+ but for the dark theme.

Help/cpack_gen/productbuild.rst

@@ -58,7 +58,6 @@ macOS using ProductBuild:
  component name.  No ``postinstall`` script is added if this variable is not
  defined for a given component.
 
-
 .. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR
 
  If specified the productbuild generator copies files from this directory
@@ -66,3 +65,54 @@ macOS using ProductBuild:
  before the :variable:`CPACK_RESOURCE_FILE_WELCOME`,
  :variable:`CPACK_RESOURCE_FILE_README`, and
  :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND
+
+ Adds a background to Distribtion XML if specified. The value contains the
+ path to image in ``Resources`` directory.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT
+
+ Adds an ``alignment`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING
+
+ Adds a ``scaling`` attribute to the background in Distribution XML.
+ Refer to Apple documentation for valid values.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE
+
+ Adds a ``mime-type`` attribute to the background in Distribution XML.
+ The option contains MIME type of an image.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI
+
+ Adds an ``uti`` attribute to the background in Distribution XML.
+ The option contains UTI type of an image.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA
+
+ Adds a background for the Dark Aqua theme to Distribution XML if
+ specified. The value contains the path to image in ``Resources``
+ directory.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option,
+ but for the dark theme.
+
+.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI
+
+ Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option,
+ but for the dark theme.

Help/cpack_gen/rpm.rst

@@ -36,8 +36,8 @@ http://www.rpm.org/wiki/Docs
 Here are some CPack RPM generator wiki resources that are here for historic
 reasons and are no longer maintained but may still prove useful:
 
- - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration
+ - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration
- - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#rpm-unix-only
+ - https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#rpm-unix-only
 
 List of CPack RPM generator specific variables:
 
@@ -473,38 +473,42 @@ List of CPack RPM generator specific variables:
 
 .. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
               CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
+              CPACK_RPM_PRE_TRANS_SCRIPT_FILE
 
- Path to file containing pre (un)install script.
+ Path to file containing pre install/uninstall/transaction script.
 
  * Mandatory : NO
  * Default   : -
 
- May be used to embed a pre (un)installation script in the spec file.
+ May be used to embed a pre installation/uninstallation/transaction script in the spec file.
  The referred script file (or both) will be read and directly
  put after the ``%pre`` or ``%preun`` section
- If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
+ If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
  script for each component can be overridden with
- ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and
+ ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``,
- ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``.
+ ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and
+ ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE``
  One may verify which scriptlet has been included with::
 
   rpm -qp --scripts  package.rpm
 
 .. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
               CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
+              CPACK_RPM_POST_TRANS_SCRIPT_FILE
 
- Path to file containing post (un)install script.
+ Path to file containing post install/uninstall/transaction script.
 
  * Mandatory : NO
  * Default   : -
 
- May be used to embed a post (un)installation script in the spec file.
+ May be used to embed a post installation/uninstallation/transaction script in the spec file.
  The referred script file (or both) will be read and directly
  put after the ``%post`` or ``%postun`` section.
- If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
+ If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
  script for each component can be overridden with
- ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and
+ ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``,
- ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``.
+ ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and
+ ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE``
  One may verify which scriptlet has been included with::
 
   rpm -qp --scripts  package.rpm

Help/dev/maint.rst

@@ -14,6 +14,11 @@ Review a Merge Request
 The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge``
 command to integrate a merge request.  Please check at least the following:
 
+* If the MR source branch (or part of it) should be backported
+  to the ``release`` branch (and is already based on a commit
+  contained in the ``release`` branch), add a ``Backport: release`` or
+  ``Backport: release:<commit-ish>`` trailing line to the MR description.
+
 * If the MR source branch is not named well for the change it makes
   (e.g. it is just ``master`` or the patch changed during review),
   add a ``Topic-rename: <topic>`` trailing line to the MR description
@@ -38,9 +43,10 @@ command to integrate a merge request.  Please check at least the following:
   of various nightly builders.)
 
 * Ensure that the MR targets the ``master`` branch.  A MR intended for
-  the ``release`` branch should be based on ``release`` but still merged
+  the ``release`` branch should be based on ``release`` but still target
-  to ``master`` first (via ``Do: merge``).  A maintainer may then merge
+  ``master``.  Use the above-mentioned ``Backport: release`` line to tell
-  the MR topic to ``release`` manually.
+  ``Do: merge`` to merge to both.  If a MR is merged without the backport
+  line, a maintainer may still merge the MR topic to ``release`` manually.
 
 Maintain Current Release
 ========================
@@ -51,6 +57,12 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version
 number of the current release in the form ``$major.$minor``.  It is always
 merged into ``master`` before publishing.
 
+To merge an open MR to the ``release`` branch, edit its description to
+use the ``Backport: release`` line mentioned above and then ``Do: merge``
+normally.  To update the ``release`` branch manually (e.g. to merge a
+``$topic`` branch that was merged without the backport line), use the
+following procedure.
+
 Before merging a ``$topic`` branch into ``release``, verify that the
 ``$topic`` branch has already been merged to ``master`` via the usual
 ``Do: merge`` process.  Then, to merge the ``$topic`` branch into

Help/dev/review.rst

@@ -28,7 +28,7 @@ request is accepted" option when creating the MR or by editing it.
 This will cause the MR topic branch to be automatically removed from
 the user's fork during the `Merge`_ step.
 
-.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/merge_requests
+.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/-/merge_requests
 .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
 
 Workflow Status
@@ -53,10 +53,14 @@ in GitLab to track the state of a MR:
   to a period of inactivity.  See the `Expire`_ step.  Use this label
   after closing a MR for this reason.
 
+* ``workflow:external-discussion`` indicates that the MR has been closed
+  pending discussion elsewhere.  See the `External Discussion`_ step.
+  Use this label after closing a MR for this reason.
+
 The workflow status labels are intended to be mutually exclusive,
 so please remove any existing workflow label when adding one.
 
-.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/settings/members
+.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/-/settings/members
 
 Robot Review
 ============
@@ -274,42 +278,52 @@ merging.
 Topic Testing
 =============
 
-CMake has a `buildbot`_ instance watching for merge requests to test.
+CMake uses `GitLab CI`_ to test merge requests, configured by the top-level
-`CMake GitLab Project Developers`_ may activate buildbot on a MR by
+``.gitlab-ci.yml`` file.  Results may be seen both on the merge request's
-adding a comment with a command among the `comment trailing lines`_::
+pipeline page and on the `CMake CDash Page`_.  Filtered CDash results
+showing just the pipeline's jobs can be reached by selecting the ``cdash``
+job in the ``External`` stage of the pipeline.
 
-  Do: test
+Lint and documentation build jobs run automatically after every push.
+Heavier jobs require a manual trigger to run:
 
-``@kwrobot`` will add an award emoji to the comment to indicate that it
+* Merge request authors may visit their merge request's pipeline and click the
-was processed and also inform buildbot about the request.  The buildbot
+  "Play" button on one or more jobs manually.  If the merge request has the
-user (``@buildbot``) will schedule builds and respond with a comment
+  "Allow commits from members who can merge to the target branch" check box
-linking to the `CMake CDash Page`_ with a filter for results associated
+  enabled, CMake maintainers may use the "Play" button too.
-with the topic test request.  If the MR topic branch is updated by a
-push a new ``Do: test`` command is needed to activate testing again.
 
-The ``Do: test`` command accepts the following arguments:
+* `CMake GitLab Project Developers`_ may trigger CI on a merge request by
+  adding a comment with a command among the `comment trailing lines`_::
 
-* ``--stop``: clear the list of commands for the merge request
+    Do: test
-* ``--clear``: clear previous commands before adding this command
-* ``--regex-include <arg>`` or ``-i <arg>``: only build on builders
-  matching ``<arg>`` (a Python regular expression)
-* ``--regex-exclude <arg>`` or ``-e <arg>``: exclude builds on builders
-  matching ``<arg>`` (a Python regular expression)
 
-Builder names follow the pattern ``project-host-os-buildtype-generator``:
+  ``@kwrobot`` will add an award emoji to the comment to indicate that it
+  was processed and also trigger all manual jobs in the merge request's
+  pipeline.
 
-* ``project``: always ``cmake`` for CMake builds
+  The ``Do: test`` command accepts the following arguments:
-* ``host``: the buildbot host
-* ``os``: one of ``windows``, ``osx``, or ``linux``
-* ``buildtype``: ``release`` or ``debug``
-* ``generator``: ``ninja``, ``makefiles``, ``vs<year>``,
-  or ``lint-iwyu-tidy``
 
-The special ``lint-<tools>`` generator name is a builder that builds
+  * ``--named <regex>``, ``-n <regex>``: Trigger jobs matching ``<regex>``
-CMake using lint tools but does not run the test suite (so the actual
+    anywhere in their name.  Job names may be seen on the merge request's
-generator does not matter).
+    pipeline page.
+  * ``--stage <stage>``, ``-s <stage>``: Only affect jobs in a given stage.
+    Stage names may be seen on the merge request's pipeline page.  Note that
+    the names are determined by what is in the ``.gitlab-ci.yml`` file and may
+    be capitalized in the web page, so lowercasing the webpage's display name
+    for stages may be required.
+  * ``--action <action>``, ``-a <action>``: The action to perform on the jobs.
+    Possible actions:
 
-.. _`buildbot`: http://buildbot.net
+    * ``manual`` (the default): Start jobs awaiting manual interaction.
+    * ``unsuccessful``: Start or restart jobs which have not completed
+      successfully.
+    * ``failed``: Restart jobs which have completed, but without success.
+    * ``completed``: Restart all completed jobs.
+
+If the merge request topic branch is updated by a push, a new manual trigger
+using one of the above methods is needed to start CI again.
+
+.. _`GitLab CI`: https://gitlab.kitware.com/help/ci/README.md
 .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
 
 Integration Testing
@@ -429,13 +443,30 @@ Additionally, ``Do: merge`` extracts configuration from trailing lines
 in the MR description (the following have no effect if used in a MR
 comment instead):
 
+* ``Backport: release[:<commit-ish>]``: merge the topic branch into
+  the ``release`` branch to backport the change.  This is allowed
+  only if the topic branch is based on a commit in ``release`` already.
+  If only part of the topic branch should be backported, specify it as
+  ``:<commit-ish>``.  The ``<commit-ish>`` may use `git rev-parse`_
+  syntax to reference commits relative to the topic ``HEAD``.
+  See additional `backport instructions`_ for details.
+  For example:
+
+  ``Backport: release``
+    Merge the topic branch head into both ``release`` and ``master``.
+  ``Backport: release:HEAD~1^2``
+    Merge the topic branch head's parent's second parent commit into
+    the ``release`` branch.  Merge the topic branch head to ``master``.
+
 * ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of
   the MR topic branch in the constructed merge commit message.
   It is also used in merge commits constructed by ``Do: stage``.
   The ``-t`` option to a ``Do: merge`` command overrides any topic
   rename set in the MR description.
 
-.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members
+.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/-/settings/members
+.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/-/wikis/Backport-topics
+.. _`git rev-parse`: https://git-scm.com/docs/git-rev-parse
 
 Close
 -----

Help/dev/source.rst

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

Help/dev/testing.rst

@@ -33,7 +33,7 @@ CTest script with local settings and include ``cmake_common.cmake``.
 .. _`CMake Review Process`: review.rst
 .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
 .. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
-.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/blob/master/cmake_common.cmake
+.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake
 
 Nightly Start Time
 ------------------

Help/envvar/ASM_DIALECTFLAGS.rst

@@ -11,3 +11,5 @@ flags, after which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache
 as ``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>``.  For any configuration
 run (including the first), the environment variable will be ignored, if the
 ``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`` variable is defined.
+
+See also :variable:`CMAKE_ASM<DIALECT>_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/CCMAKE_COLORS.rst

@@ -0,0 +1,34 @@
+CCMAKE_COLORS
+-------------
+
+Determines what colors are used by the CMake curses interface,
+when run on a terminal that supports colors.
+The syntax follows the same conventions as ``LS_COLORS``;
+that is, a list of key/value pairs separated by ``:``.
+
+Keys are a single letter corresponding to a CMake cache variable type:
+
+- ``s``: A ``STRING``.
+- ``p``: A ``FILEPATH``.
+- ``c``: A value which has an associated list of choices.
+- ``y``: A ``BOOL`` which has a true-like value (e.g. ``ON``, ``YES``).
+- ``n``: A ``BOOL`` which has a false-like value (e.g. ``OFF``, ``NO``).
+
+Values are an integer number that specifies what color to use.
+``0`` is black (you probably don't want to use that).
+Others are determined by your terminal's color support.
+Most (color) terminals will support at least 8 or 16 colors.
+Some will support up to 256 colors. The colors will likely match
+`this chart <https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg>`_,
+although the first 16 colors may match the original
+`CGA color palette <https://en.wikipedia.org/wiki/Color_Graphics_Adapter#Color_palette>`_.
+(Many modern terminal emulators also allow their color palette,
+at least for the first 16 colors, to be configured by the user.)
+
+Note that fairly minimal checking is done for bad colors
+(although a value higher than what curses believes your terminal supports
+will be silently ignored) or bad syntax.
+
+For example::
+
+  CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46'

Help/envvar/CFLAGS.rst

@@ -9,3 +9,5 @@ flags, after which the value for ``CFLAGS`` is stored in the cache
 as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run
 (including the first), the environment variable will be ignored if the
 :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+
+See also :variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/CMAKE_EXPORT_COMPILE_COMMANDS.rst

@@ -0,0 +1,9 @@
+CMAKE_EXPORT_COMPILE_COMMANDS
+-----------------------------
+
+.. include:: ENV_VAR.txt
+
+The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there
+is no explicit configuration given on the first run while creating a new
+build tree.  On later runs in an existing build tree the value persists in
+the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`.

Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst

@@ -0,0 +1,10 @@
+CMAKE_<LANG>_COMPILER_LAUNCHER
+------------------------------
+
+.. include:: ENV_VAR.txt
+
+Default compiler launcher to use for the specified language. Will only be used
+by CMake to initialize the variable on the first configuration. Afterwards, it
+is available through the cache setting of the variable of the same name. For
+any configuration run (including the first), the environment variable will be
+ignored if the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable is defined.

Help/envvar/CMAKE_PREFIX_PATH.rst

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

Help/envvar/CSFLAGS.rst

@@ -9,3 +9,5 @@ compilation flags, after which the value for ``CSFLAGS`` is stored in the cache
 as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
 run (including the first), the environment variable will be ignored if the
 :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+
+See also :variable:`CMAKE_CSharp_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/CUDAFLAGS.rst

@@ -9,3 +9,5 @@ compilation flags, after which the value for ``CUDAFLAGS`` is stored in the
 cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
 run (including the first), the environment variable will be ignored if
 the :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+
+See also :variable:`CMAKE_CUDA_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/CXXFLAGS.rst

@@ -9,3 +9,5 @@ compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache
 as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run (
 including the first), the environment variable will be ignored if
 the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+
+See also :variable:`CMAKE_CXX_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/FFLAGS.rst

@@ -9,3 +9,5 @@ compilation flags, after which the value for ``FFLAGS`` is stored in the cache
 as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
 run (including the first), the environment variable will be ignored if
 the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+
+See also :variable:`CMAKE_Fortran_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/OBJC.rst

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

Help/envvar/OBJCXX.rst

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

Help/envvar/RCFLAGS.rst

@@ -9,3 +9,5 @@ default compilation flags, after which the value for ``RCFLAGS`` is stored in
 the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any
 configuration run (including the first), the environment variable will be ignored
 if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
+
+See also :variable:`CMAKE_RC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/generator/Ninja Multi-Config.rst

@@ -0,0 +1,87 @@
+Ninja Multi-Config
+------------------
+
+Generates multiple ``build-<Config>.ninja`` files.
+
+This generator is very much like the :generator:`Ninja` generator, but with
+some key differences. Only these differences will be discussed in this
+document.
+
+Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates
+multiple configurations at once with :variable:`CMAKE_CONFIGURATION_TYPES`
+instead of only one configuration with :variable:`CMAKE_BUILD_TYPE`. One
+``build-<Config>.ninja`` file will be generated for each of these
+configurations (with ``<Config>`` being the configuration name.) These files
+are intended to be run with ``ninja -f build-<Config>.ninja``. A
+``build.ninja`` file is also generated, using the configuration from either
+:variable:`CMAKE_DEFAULT_BUILD_TYPE` or the first item from
+:variable:`CMAKE_CONFIGURATION_TYPES`.
+
+``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja``
+to build. If no ``--config`` argument is specified, ``cmake --build .`` will
+default to ``build-Debug.ninja``, unless a ``build.ninja`` is generated (see
+below), in which case that will be used instead.
+
+Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as
+``<target>:<Config>`` targets, where ``<Config>`` is the same as the
+configuration specified in ``build-<Config>.ninja`` Additionally, if
+cross-config mode is enabled, ``build-<Config>.ninja`` may contain
+``<target>:<OtherConfig>`` targets, where ``<OtherConfig>`` is a cross-config,
+as well as ``<target>:all``, which builds the target in all cross-configs. See
+below for how to enable cross-config mode.
+
+The ``Ninja Multi-Config`` generator recognizes the following variables:
+
+:variable:`CMAKE_CONFIGURATION_TYPES`
+  Specifies the total set of configurations to build.
+
+:variable:`CMAKE_CROSS_CONFIGS`
+  Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
+  configurations available from all ``build-<Config>.ninja`` files.
+
+:variable:`CMAKE_DEFAULT_BUILD_TYPE`
+  Specifies the configuration to use by default in a ``build.ninja`` file.
+
+:variable:`CMAKE_DEFAULT_CONFIGS`
+  Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
+  configurations to build for a target in ``build.ninja``
+  if no ``:<Config>`` suffix is specified.
+
+Consider the following example:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.16)
+  project(MultiConfigNinja C)
+
+  add_executable(generator generator.c)
+  add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
+  add_library(generated ${CMAKE_BINARY_DIR}/generated.c)
+
+Now assume you configure the project with ``Ninja Multi-Config`` and run one of
+the following commands:
+
+.. code-block:: shell
+
+  ninja -f build-Debug.ninja generated
+  # OR
+  cmake --build . --config Debug --target generated
+
+This would build the ``Debug`` configuration of ``generator``, which would be
+used to generate ``generated.c``, which would be used to build the ``Debug``
+configuration of ``generated``.
+
+But if :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and you run the
+following instead:
+
+.. code-block:: shell
+
+  ninja -f build-Release.ninja generated:Debug
+  # OR
+  cmake --build . --config Release --target generated:Debug
+
+This would build the ``Release`` configuration of ``generator``, which would be
+used to generate ``generated.c``, which would be used to build the ``Debug``
+configuration of ``generated``. This is useful for running a release-optimized
+version of a generator utility while still building the debug version of the
+targets built with the generated code.

Help/generator/Ninja.rst

@@ -1,7 +1,7 @@
 Ninja
 -----
 
-Generates build.ninja files.
+Generates ``build.ninja`` files.
 
 A ``build.ninja`` file is generated into the build tree.  Use the ninja
 program to build the project through the ``all`` target and install the
@@ -33,8 +33,10 @@ Fortran Support
 ^^^^^^^^^^^^^^^
 
 The ``Ninja`` generator conditionally supports Fortran when the ``ninja``
-tool has the required features.  As of this version of CMake the needed
+tool is at least version 1.10 (which has the required features).
-features have not been integrated into upstream Ninja.  Kitware maintains
-a branch of Ninja with the required features on `github.com/Kitware/ninja`_.
 
-.. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme
+See Also
+^^^^^^^^
+
+The :generator:`Ninja Multi-Config` generator is similar to the ``Ninja``
+generator, but generates multiple configurations at once.

Help/guide/tutorial/Complete/CMakeLists.txt

@@ -3,6 +3,8 @@ cmake_minimum_required(VERSION 3.15)
 # set the project name and version
 project(Tutorial VERSION 1.0)
 
+set(CMAKE_DEBUG_POSTFIX d)
+
 add_library(tutorial_compiler_flags INTERFACE)
 target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
@@ -37,6 +39,8 @@ add_subdirectory(MathFunctions)
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
+set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
+
 target_link_libraries(Tutorial PUBLIC MathFunctions)
 
 # add the binary tree to the search path for include files

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

@@ -17,7 +17,7 @@ if(USE_MYMATH)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
-  target_link_libraries(MakeTable tutorial_compiler_flags)
+  target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(

Help/guide/tutorial/Complete/MultiCPackConfig.cmake

@@ -1,4 +1,3 @@
-
 include("release/CPackConfig.cmake")
 
 set(CPACK_INSTALL_CMAKE_PROJECTS

Help/guide/tutorial/Complete/tutorial.cxx

@@ -1,6 +1,5 @@
 // A simple program that computes the square root of a number
 #include <iostream>
-#include <sstream>
 #include <string>
 
 #include "MathFunctions.h"
@@ -9,6 +8,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -18,8 +18,8 @@ int main(int argc, char* argv[])
   // convert input to double
   const double inputValue = std::stod(argv[1]);
 
-  // calculate square root
   const double outputValue = mathfunctions::sqrt(inputValue);
+
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;
   return 0;

Help/guide/tutorial/Consumer/CMakeLists.txt

@@ -1,51 +0,0 @@
-cmake_minimum_required(VERSION 3.10)
-
-if(NOT DEFINED CMAKE_CXX_STANDARD)
-  set(CMAKE_CXX_STANDARD 11)
-  set(CMAKE_CXX_STANDARD_REQUIRED True)
-endif()
-
-
-function(find_external_dependency name)
-  set(${name}_ROOT ""  CACHE PATH "Root directory to find ${name}")
-  mark_as_advanced(${name}_DIR)
-  find_package(${name} PATHS ${${name}_ROOT} REQUIRED)
-endfunction()
-
-
-project(Consumer)
-
-find_external_dependency(MathFunctions)
-
-add_library(consumer consumer.cxx)
-target_link_libraries(consumer PUBLIC MathFunctions)
-
-# install the consumer library
-install(TARGETS consumer DESTINATION bin EXPORT ConsumerTargets)
-
-# install the configuration targets
-install(EXPORT ConsumerTargets
-  FILE ConsumerTargets.cmake
-  DESTINATION lib/cmake/Consumer
-)
-
-include(CMakePackageConfigHelpers)
-# generate the config file that is includes the exports
-configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
-  "${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake"
-  INSTALL_DESTINATION "lib/cmake/example"
-  NO_SET_AND_CHECK_MACRO
-  NO_CHECK_REQUIRED_COMPONENTS_MACRO
-  )
-
-# install the configuration file
-install(FILES
-  ${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake
-  DESTINATION lib/cmake/Consumer
-  )
-
-# generate the export targets for the build tree
-# needs to be after the install(TARGETS ) command
-export(EXPORT ConsumerTargets
-  FILE "${CMAKE_CURRENT_BINARY_DIR}/ConsumerTargets.cmake"
-)

Help/guide/tutorial/Consumer/Config.cmake.in

@@ -1,14 +0,0 @@
-
-@PACKAGE_INIT@
-
-include(CMakeFindDependencyMacro)
-
-function(find_external_dependency name)
-  set(${name}_ROOT ""  CACHE PATH "Root directory to find ${name}")
-  mark_as_advanced(${name}_DIR)
-  find_dependency(${name} PATHS ${${name}_ROOT} REQUIRED)
-endfunction()
-
-find_external_dependency(MathFunctions)
-
-include ( "${CMAKE_CURRENT_LIST_DIR}/ConsumerTargets.cmake" )

Help/guide/tutorial/Consumer/consumer.cxx

@@ -1,11 +0,0 @@
-// A simple function that computes the square root of a number
-#include <iostream>
-#include <sstream>
-#include <string>
-
-#include "MathFunctions.h"
-
-double string_square_root(std::string const& value)
-{
-  return mathfunctions::sqrt(std::stod(value));
-}

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

@@ -15,7 +15,7 @@ if(USE_MYMATH)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
-  target_link_libraries(MakeTable tutorial_compiler_flags)
+  target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(

Help/guide/tutorial/Step12/CMakeLists.txt

@@ -1,11 +1,19 @@
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.15)
 
 # set the project name and version
 project(Tutorial VERSION 1.0)
 
-set(CMAKE_CXX_STANDARD 11)
+add_library(tutorial_compiler_flags INTERFACE)
-set(CMAKE_CXX_STANDARD_REQUIRED True)
+target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
+# add compiler warning flags just when building this project via
+# the BUILD_INTERFACE genex
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
+set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
+target_compile_options(tutorial_compiler_flags INTERFACE
+  "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
+  "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
+)
 
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable

Help/guide/tutorial/Step12/CTestConfig.cmake

@@ -0,0 +1,7 @@
+set(CTEST_PROJECT_NAME "CMakeTutorial")
+set(CTEST_NIGHTLY_START_TIME "00:00:00 EST")
+
+set(CTEST_DROP_METHOD "http")
+set(CTEST_DROP_SITE "my.cdash.org")
+set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial")
+set(CTEST_DROP_SITE_CDASH TRUE)

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

@@ -17,6 +17,7 @@ if(USE_MYMATH)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
+  target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(
@@ -41,19 +42,18 @@ if(USE_MYMATH)
                         POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                         )
 
+  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
   target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()
 
+target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
+
 # define the symbol stating we are using the declspec(dllexport) when
 # building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
-# setup the version numbering
-set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
-set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
-
 # install rules
-install(TARGETS MathFunctions
+install(TARGETS MathFunctions tutorial_compiler_flags
         DESTINATION lib
         EXPORT MathFunctionsTargets)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx

@@ -17,11 +17,10 @@ double mysqrt(double x)
   // use the table to help find an initial value
   double result = x;
   if (x >= 1 && x < 10) {
+    std::cout << "Use the table to help find an initial value " << std::endl;
     result = sqrtTable[static_cast<int>(x)];
   }
 
-  // if we have both log and exp then use them
-
   // do ten iterations
   for (int i = 0; i < 10; ++i) {
     if (result <= 0) {

Help/guide/tutorial/Step12/TutorialConfig.h.in

@@ -1,3 +1,3 @@
-// the configured version number
+// the configured options and settings for Tutorial
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@

Help/guide/tutorial/Step12/tutorial.cxx

@@ -8,6 +8,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -15,7 +16,7 @@ int main(int argc, char* argv[])
   }
 
   // convert input to double
-  double inputValue = std::stod(argv[1]);
+  const double inputValue = std::stod(argv[1]);
 
   const double outputValue = mathfunctions::sqrt(inputValue);
 

Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx

@@ -1,25 +0,0 @@
-// A simple program that builds a sqrt table
-#include <cmath>
-#include <fstream>
-#include <iostream>
-
-int main(int argc, char* argv[])
-{
-  // make sure we have enough arguments
-  if (argc < 2) {
-    return 1;
-  }
-
-  std::ofstream fout(argv[1], std::ios_base::out);
-  const bool fileOpen = fout.is_open();
-  if (fileOpen) {
-    fout << "double sqrtTable[] = {" << std::endl;
-    for (int i = 0; i < 10; ++i) {
-      fout << sqrt(static_cast<double>(i)) << "," << std::endl;
-    }
-    // close the table with a zero
-    fout << "0};" << std::endl;
-    fout.close();
-  }
-  return fileOpen ? 0 : 1; // return 0 if wrote the file
-}

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

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

Help/guide/tutorial/index.rst

@@ -45,7 +45,8 @@ The first feature we will add is to provide our executable and project with a
 version number. While we could do this exclusively in the source code, using
 ``CMakeLists.txt`` provides more flexibility.
 
-First, modify the ``CMakeLists.txt`` file to set the version number.
+First, modify the ``CMakeLists.txt`` file to use the :command:`project` command
+to set the project name and version number.
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake
@@ -102,9 +103,10 @@ Next let's add some C++11 features to our project by replacing ``atof`` with
 
 We will need to explicitly state in the CMake code that it should use the
 correct flags. The easiest way to enable support for a specific C++ standard
-in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial,
+in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this
-set the ``CMAKE_CXX_STANDARD`` variable in the ``CMakeLists.txt`` file to 11
+tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the
-and ``CMAKE_CXX_STANDARD_REQUIRED`` to True:
+``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to
+True:
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake
@@ -113,7 +115,8 @@ and ``CMAKE_CXX_STANDARD_REQUIRED`` to True:
 Build and Test
 --------------
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+Run the :manual:`cmake <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool.
 
 For example, from the command line we could navigate to the
@@ -156,11 +159,11 @@ directory:
 .. literalinclude:: Step3/MathFunctions/CMakeLists.txt
   :language: cmake
 
-To make use of the new library we will add an ``add_subdirectory`` call in the
+To make use of the new library we will add an :command:`add_subdirectory`
-top-level ``CMakeLists.txt`` file so that the library will get built. We add
+call in the top-level ``CMakeLists.txt`` file so that the library will get
-the new library to the executable, and add ``MathFunctions`` as an include
+built. We add the new library to the executable, and add ``MathFunctions`` as
-directory so that the ``mqsqrt.h`` header file can be found. The last few lines
+an include directory so that the ``mqsqrt.h`` header file can be found. The
-of the top-level ``CMakeLists.txt`` file should now look like:
+last few lines of the top-level ``CMakeLists.txt`` file should now look like:
 
 .. code-block:: cmake
 
@@ -180,7 +183,7 @@ of the top-level ``CMakeLists.txt`` file should now look like:
                                   )
 
 Now let us make the MathFunctions library optional. While for the tutorial
-there really isn’t any need to do so, for larger projects this is a common
+there really isn't any need to do so, for larger projects this is a common
 occurrence. The first step is to add an option to the top-level
 ``CMakeLists.txt`` file.
 
@@ -189,10 +192,11 @@ occurrence. The first step is to add an option to the top-level
   :start-after: # should we use our own math functions
   :end-before: # add the MathFunctions library
 
-This option will be displayed in the CMake GUI and ccmake with a default
+This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
-value of ON that can be changed by the user. This setting will be stored in
+:manual:`ccmake <ccmake(1)>`
-the cache so that the user does not need to set the value each time they run
+with a default value of ON that can be changed by the user. This setting will
-CMake on a build directory.
+be stored in the cache so that the user does not need to set the value each
+time they run CMake on a build directory.
 
 The next change is to make building and linking the MathFunctions library
 conditional. To do this we change the end of the top-level ``CMakeLists.txt``
@@ -234,11 +238,13 @@ Since the source code now requires ``USE_MYMATH`` we can add it to
 **Exercise**: Why is it important that we configure ``TutorialConfig.h.in``
 after the option for ``USE_MYMATH``? What would happen if we inverted the two?
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+Run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool. Then run the built Tutorial executable.
 
-Use ccmake or the CMake GUI to update the value of ``USE_MYMATH``. Rebuild and
+Use the :manual:`ccmake <ccmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>`
-run the tutorial again. Which function gives better results, sqrt or mysqrt?
+to update the value of ``USE_MYMATH``. Rebuild and run the tutorial again.
+Which function gives better results, sqrt or mysqrt?
 
 Adding Usage Requirements for Library (Step 3)
 ==============================================
@@ -248,19 +254,20 @@ link and include line while also giving more control over the transitive
 property of targets inside CMake. The primary commands that leverage usage
 requirements are:
 
-  - ``target_compile_definitions``
+  - :command:`target_compile_definitions`
-  - ``target_compile_options``
+  - :command:`target_compile_options`
-  - ``target_include_directories``
+  - :command:`target_include_directories`
-  - ``target_link_libraries``
+  - :command:`target_link_libraries`
 
 Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern
 CMake approach of usage requirements. We first state that anybody linking to
 MathFunctions needs to include the current source directory, while
-MathFunctions itself doesn't. So  this can become an ``INTERFACE`` usage
+MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage
 requirement.
 
 Remember ``INTERFACE`` means things that consumers require but the producer
-doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``:
+doesn't. Add the following lines to the end of
+``MathFunctions/CMakeLists.txt``:
 
 .. literalinclude:: Step4/MathFunctions/CMakeLists.txt
   :language: cmake
@@ -281,9 +288,10 @@ And here:
   :language: cmake
   :start-after: # so that we will find TutorialConfig.h
 
-Once this is done, run **cmake** or **cmake-gui** to configure the project
+Once this is done, run the :manual:`cmake  <cmake(1)>` executable or the
-and then build it with your chosen build tool or by using ``cmake --build .``
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
-from the build directory.
+with your chosen build tool or by using ``cmake --build .`` from the build
+directory.
 
 Installing and Testing (Step 4)
 ===============================
@@ -312,16 +320,17 @@ And to the end of the top-level ``CMakeLists.txt`` we add:
 
 That is all that is needed to create a basic local install of the tutorial.
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+Run the :manual:`cmake  <cmake(1)>` executable or the
-with your chosen build tool. Run the install step by typing
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
-``cmake --install .`` (introduced in 3.15, older versions of CMake must use
+with your chosen build tool. Run the install step by using the ``install``
-``make install``) from the command line, or build the ``INSTALL`` target from
+option of the :manual:`cmake  <cmake(1)>` command (introduced in 3.15, older
-an IDE. This will install the appropriate header files, libraries, and
+versions of CMake must use ``make install``) from the command line, or build
-executables.
+the ``INSTALL`` target from an IDE. This will install the appropriate header
+files, libraries, and executables.
 
-The CMake variable ``CMAKE_INSTALL_PREFIX`` is used to determine the root of
+The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
-where the files will be installed. If using ``cmake --install`` a custom
+root of where the files will be installed. If using ``cmake --install`` a
-installation directory can be given via ``--prefix`` argument. For
+custom installation directory can be given via the ``--prefix`` argument. For
 multi-configuration tools, use the ``--config`` argument to specify the
 configuration.
 
@@ -339,25 +348,25 @@ the application is working correctly.
   :start-after: # enable testing
 
 The first test simply verifies that the application runs, does not segfault or
-otherwise crash, and has a zero return value. This is the basic form of a CTest
+otherwise crash, and has a zero return value. This is the basic form of a
-test.
+CTest test.
 
-The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to
+The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test
-verify that the output of the test contains certain strings. In this case,
+property to verify that the output of the test contains certain strings. In
-verifying that the usage message is printed when an incorrect number of
+this case, verifying that the usage message is printed when an incorrect number
-arguments are provided.
+of arguments are provided.
 
 Lastly, we have a function called ``do_test`` that runs the application and
 verifies that the computed square root is correct for given input. For each
 invocation of ``do_test``, another test is added to the project with a name,
 input, and expected results based on the passed arguments.
 
-Rebuild the application and then cd to the binary directory and run
+Rebuild the application and then cd to the binary directory and run the
-``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual
+:manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For
-Studio), the configuration type must be specified. To run tests in Debug mode,
+multi-config generators (e.g. Visual Studio), the configuration type must be
-for example, use ``ctest -C Debug -VV`` from the build directory (not the
+specified. To run tests in Debug mode, for example, use ``ctest -C Debug -VV``
-Debug subdirectory!). Alternatively, build the ``RUN_TESTS`` target from the
+from the build directory (not the Debug subdirectory!). Alternatively, build
-IDE.
+the ``RUN_TESTS`` target from the IDE.
 
 Adding System Introspection (Step 5)
 ====================================
@@ -370,14 +379,18 @@ tutorial assume that they are not common.
 
 If the platform has ``log`` and ``exp`` then we will use them to compute the
 square root in the ``mysqrt`` function. We first test for the availability of
-these functions using the ``CheckSymbolExists`` module in the top-level
+these functions using the :module:`CheckSymbolExists` module in the top-level
-``CMakeLists.txt``. We're going to use the new defines in
+``CMakeLists.txt``. On some platforms, we will need to link to the m library.
-``TutorialConfig.h.in``, so be sure to set them before that file is configured.
+If ``log`` and ``exp`` are not initially found, require the m library and try
+again.
+
+We're going to use the new defines in ``TutorialConfig.h.in``, so be sure to
+set them before that file is configured.
 
 .. literalinclude:: Step6/MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # does this system provide the log and exp functions?
-  :end-before: if(HAVE_LOG AND HAVE_EXP)
+  :end-before: # add compile definitions
 
 Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them
 from ``mysqrt.cxx``:
@@ -388,22 +401,29 @@ from ``mysqrt.cxx``:
   #cmakedefine HAVE_LOG
   #cmakedefine HAVE_EXP
 
-Modify ``mysqrt.cxx`` to include cmath. Next, in that same file in the
+If ``log`` and ``exp`` are available on the system, then we will use them to
-``mysqrt`` function we can provide an alternate implementation based on
+compute the square root in the ``mysqrt`` function. Add the following code to
-``log`` and ``exp`` if they are available on the system using the following
+the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
-code (don't forget the ``#endif`` before returning the result!):
+``#endif`` before returning the result!):
 
 .. literalinclude:: Step6/MathFunctions/mysqrt.cxx
   :language: c++
   :start-after: // if we have both log and exp then use them
   :end-before: // do ten iterations
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
+
+.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
+  :language: c++
+  :end-before: #include <iostream>
+
+Run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool and run the Tutorial executable.
 
 You will notice that we're not using ``log`` and ``exp``, even if we think they
-should be available. We should realize quickly that we have forgotten to include
+should be available. We should realize quickly that we have forgotten to
-``TutorialConfig.h`` in ``mysqrt.cxx``.
+include ``TutorialConfig.h`` in ``mysqrt.cxx``.
 
 We will also need to update ``MathFunctions/CMakeLists.txt`` so ``mysqrt.cxx``
 knows where this file is located:
@@ -415,10 +435,10 @@ knows where this file is located:
             PRIVATE ${CMAKE_BINARY_DIR}
             )
 
-After making this update, go ahead and build the project again and run the built
+After making this update, go ahead and build the project again and run the
-Tutorial executable. If ``log`` and ``exp`` are still not being used, open the
+built Tutorial executable. If ``log`` and ``exp`` are still not being used,
-generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't
+open the generated ``TutorialConfig.h`` file from the build directory. Maybe
-available on the current system?
+they aren't available on the current system?
 
 Which function gives better results now, sqrt or mysqrt?
 
@@ -427,7 +447,7 @@ Specify Compile Definition
 
 Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values
 other than in ``TutorialConfig.h``? Let's try to use
-``target_compile_definitions``.
+:command:`target_compile_definitions`.
 
 First, remove the defines from ``TutorialConfig.h.in``. We no longer need to
 include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in
@@ -460,8 +480,8 @@ First, let's remove the check for the ``log`` and ``exp`` functions in
 ``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove
 :code:`#include <cmath>`.
 
-In the ``MathFunctions`` subdirectory, a new source file named ``MakeTable.cxx``
+In the ``MathFunctions`` subdirectory, a new source file named
-has been provided to generate the table.
+``MakeTable.cxx`` has been provided to generate the table.
 
 After reviewing the file, we can see that the table is produced as valid C++
 code and that the output filename is passed in as an argument.
@@ -510,7 +530,8 @@ Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
   :language: c++
   :start-after: // a hack square root calculation using simple operations
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+Run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool.
 
 When this project is built it will first build the ``MakeTable`` executable.
@@ -530,26 +551,28 @@ previously in `Installing and Testing (Step 4)`_ , where we were
 installing the binaries that we had built from the source code. In this
 example we will be building installation packages that support binary
 installations and package management features. To accomplish this we will use
-CPack to create platform specific installers. Specifically we need to add
+CPack to create platform specific installers. Specifically we need to add a
-a few lines to the bottom of our top-level ``CMakeLists.txt`` file.
+few lines to the bottom of our top-level ``CMakeLists.txt`` file.
 
 .. literalinclude:: Step8/CMakeLists.txt
   :language: cmake
   :start-after: # setup installer
 
 That is all there is to it. We start by including
-``InstallRequiredSystemLibraries``. This module will include any runtime
+:module:`InstallRequiredSystemLibraries`. This module will include any runtime
-libraries that are needed by the project for the current platform. Next we
+libraries that are needed by the project for the current platform. Next we set
-set some CPack variables to where we have stored the license and version
+some CPack variables to where we have stored the license and version
 information for this project. The version information was set earlier in this
 tutorial and the ``license.txt`` has been included in the top-level source
 directory for this step.
 
-Finally we include the CPack module which will use these variables and some
+Finally we include the :module:`CPack module <CPack>` which will use these
-other properties of the current system to setup an installer.
+variables and some other properties of the current system to setup an
+installer.
 
-The next step is to build the project in the usual manner and then run
+The next step is to build the project in the usual manner and then run the
-CPack on it. To build a binary distribution, from the binary directory run:
+:manual:`cpack <cpack(1)>` executable. To build a binary distribution, from the
+binary directory run:
 
 .. code-block:: console
 
@@ -571,16 +594,17 @@ To create a source distribution you would type:
 Alternatively, run ``make package`` or right click the ``Package`` target and
 ``Build Project`` from an IDE.
 
-Run the installer found in the binary directory. Then run the
+Run the installer found in the binary directory. Then run the installed
-installed executable and verify that it works.
+executable and verify that it works.
 
 Adding Support for a Dashboard (Step 8)
 =======================================
 
-Adding support for submitting our test results to a dashboard is very easy. We
+Adding support for submitting our test results to a dashboard is simple. We
 already defined a number of tests for our project in `Testing Support`_. Now we
 just have to run those tests and submit them to a dashboard. To include support
-for dashboards we include the CTest module in our top-level ``CMakeLists.txt``.
+for dashboards we include the :module:`CTest` module in our top-level
+``CMakeLists.txt``.
 
 Replace:
 
@@ -596,8 +620,8 @@ With:
   # enable dashboard scripting
   include(CTest)
 
-The CTest module will automatically call ``enable_testing()``, so
+The :module:`CTest` module will automatically call ``enable_testing()``, so we
-we can remove it from our CMake files.
+can remove it from our CMake files.
 
 We will also need to create a ``CTestConfig.cmake`` file in the top-level
 directory where we can specify the name of the project and where to submit the
@@ -606,9 +630,11 @@ dashboard.
 .. literalinclude:: Step9/CTestConfig.cmake
   :language: cmake
 
-CTest will read in this file when it runs. To create a simple dashboard you can
+The :manual:`ctest <ctest(1)>` executable will read in this file when it runs.
-run **cmake** or **cmake-gui** to configure the project, but do not build it
+To create a simple dashboard you can run the :manual:`cmake <cmake(1)>`
-yet. Instead, change directory to the binary tree, and then run::
+executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project,
+but do not build it yet. Instead, change directory to the binary tree, and then
+run:
 
   ctest [-VV] -D Experimental
 
@@ -619,26 +645,26 @@ type must be specified::
 
 Or, from an IDE, build the ``Experimental`` target.
 
-``ctest`` will build and test the project and submit the results to the Kitware
+The :manual:`ctest <ctest(1)>` executable will build and test the project and
-public dashboard. The results of your dashboard will be uploaded to Kitware's
+submit the results to Kitware's public dashboard:
-public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial.
+https://my.cdash.org/index.php?project=CMakeTutorial.
 
 Mixing Static and Shared (Step 9)
 =================================
 
-In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable
+In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can
-we can control the default behavior of ``add_library``, and allow control
+be used to control the default behavior of :command:`add_library`,
-over how libraries without an explicit type (``STATIC``, ``SHARED``, ``MODULE``
+and allow control over how libraries without an explicit type (``STATIC``,
-or ``OBJECT``) are built.
+``SHARED``, ``MODULE`` or ``OBJECT``) are built.
 
-To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level
+To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the
-``CMakeLists.txt``. We use the ``option`` command as it allows users to
+top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows
-optionally select if the value should be On or Off.
+users to optionally select if the value should be ON or OFF.
 
 Next we are going to refactor MathFunctions to become a real library that
 encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling
 code to do this logic. This will also mean that ``USE_MYMATH`` will not control
-building MathFuctions, but instead will control the behavior of this library.
+building MathFunctions, but instead will control the behavior of this library.
 
 The first step is to update the starting section of the top-level
 ``CMakeLists.txt`` to look like:
@@ -680,8 +706,8 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 At this point, if you build everything, you will notice that linking fails
 as we are combining a static library without position independent code with a
 library that has position independent code. The solution to this is to
-explicitly set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary
+explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
-to be True no matter the build type.
+SqrtLibrary to be True no matter the build type.
 
 .. literalinclude:: Step10/MathFunctions/CMakeLists.txt
   :language: cmake
@@ -694,35 +720,39 @@ Using CMake documentation can you find a helper module to simplify this?
 Adding Generator Expressions (Step 10)
 ======================================
 
-Generator expressions are evaluated during build system generation to produce
+:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated
-information specific to each build configuration.
+during build system generation to produce information specific to each build
+configuration.
 
-Generator expressions are allowed in the context of many target properties,
+:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in
-such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS``
+the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`,
-and others. They may also be used when using commands to populate those
+:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others.
-properties, such as ``target_link_libraries()``,
+They may also be used when using commands to populate those properties, such as
-``target_include_directories()``,
+:command:`target_link_libraries`, :command:`target_include_directories`,
-``target_compile_definitions()`` and others.
+:command:`target_compile_definitions` and others.
 
-Generator expressions may be used to enable conditional linking, conditional
+:manual:`Generator expressions <cmake-generator-expressions(7)>`  may be used
-definitions used when compiling, conditional include directories and more.
+to enable conditional linking, conditional definitions used when compiling,
-The conditions may be based on the build configuration, target properties,
+conditional include directories and more. The conditions may be based on the
-platform information or any other queryable information.
+build configuration, target properties, platform information or any other
+queryable information.
 
-There are different types of generator expressions including Logical,
+There are different types of
-Informational, and Output expressions.
+:manual:`generator expressions <cmake-generator-expressions(7)>` including
+Logical, Informational, and Output expressions.
 
 Logical expressions are used to create conditional output. The basic
 expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty
 string, and ``<1:...>`` results in the content of "...".  They can also be
 nested.
 
-A common usage of generator expressions is to conditionally add compiler
+A common usage of
-flags, such as those for language levels or warnings. A nice pattern is
+:manual:`generator expressions <cmake-generator-expressions(7)>` is to
-to associate this information to an ``INTERFACE`` target allowing this
+conditionally add compiler flags, such as those for language levels or
-information to propagate. Lets start by constructing an ``INTERFACE``
+warnings. A nice pattern is to associate this information to an ``INTERFACE``
-target and specifying the required C++ standard level of ``11`` instead
+target allowing this information to propagate. Lets start by constructing an
-of using ``CMAKE_CXX_STANDARD``.
+``INTERFACE`` target and specifying the required C++ standard level of ``11``
+instead of using :variable:`CMAKE_CXX_STANDARD`.
 
 So the following code:
 
@@ -739,11 +769,10 @@ Would be replaced with:
   :end-before: # add compiler warning flags just when building this project via
 
 
-Next we add the desired compiler warning flags that we want for our
+Next we add the desired compiler warning flags that we want for our project. As
-project. As warning flags vary based on the compiler we use
+warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID``
-the ``COMPILE_LANG_AND_ID`` generator expression to control which
+generator expression to control which flags to apply given a language and a set
-flags to apply given a language and a set of compiler ids as seen
+of compiler ids as seen below:
-below:
 
 .. literalinclude:: Step11/CMakeLists.txt
   :language: cmake
@@ -755,8 +784,8 @@ Looking at this we see that the warning flags are encapsulated inside a
 project will not inherit our warning flags.
 
 
-**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that
+**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have
-all targets have a ``target_link_libraries()`` call to ``tutorial_compiler_flags``.
+a :command:`target_link_libraries` call to ``tutorial_compiler_flags``.
 
 
 Adding Export Configuration (Step 11)
@@ -771,12 +800,12 @@ The next step is to add the necessary information so that other CMake projects
 can use our project, be it from a build directory, a local install or when
 packaged.
 
-The first step is to update our ``install(TARGETS)`` commands to not only
+The first step is to update our :command:`install(TARGETS)` commands to not
-specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
+only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
 generates and installs a CMake file containing code to import all targets
-listed in the install command from the installation tree. So let's go ahead
+listed in the install command from the installation tree. So let's go ahead and
-and explicitly ``EXPORT`` the MathFunctions library by updating the
+explicitly ``EXPORT`` the MathFunctions library by updating the ``install``
-``install`` command in ``MathFunctions/CMakeLists.txt`` to look like:
+command in ``MathFunctions/CMakeLists.txt`` to look like:
 
 .. literalinclude:: Complete/MathFunctions/CMakeLists.txt
   :language: cmake
@@ -806,12 +835,12 @@ you will see that CMake will generate an error that looks like:
 What CMake is trying to say is that during generating the export information
 it will export a path that is intrinsically tied to the current machine and
 will not be valid on other machines. The solution to this is to update the
-MathFunctions ``target_include_directories`` to understand that it needs
+MathFunctions :command:`target_include_directories` to understand that it needs
 different ``INTERFACE`` locations when being used from within the build
 directory and from an install / package. This means converting the
-``target_include_directories`` call for MathFunctions to look like:
+:command:`target_include_directories` call for MathFunctions to look like:
 
-.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step12/MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # to find MathFunctions.h, while we don't.
   :end-before: # should we use our own math functions
@@ -821,16 +850,16 @@ warn anymore.
 
 At this point, we have CMake properly packaging the target information that is
 required but we will still need to generate a ``MathFunctionsConfig.cmake`` so
-that the CMake ``find_package`` command can find our project. So let's go
+that the CMake :command:`find_package` command can find our project. So let's go
 ahead and add a new file to the top-level of the project called
 ``Config.cmake.in`` with the following contents:
 
-.. literalinclude:: Complete/Config.cmake.in
+.. literalinclude:: Step12/Config.cmake.in
 
 Then, to properly configure and install that file, add the following to the
 bottom of the top-level ``CMakeLists.txt``:
 
-.. literalinclude:: Complete/CMakeLists.txt
+.. literalinclude:: Step12/CMakeLists.txt
   :language: cmake
   :start-after: # install the configuration targets
   :end-before: # generate the export
@@ -840,7 +869,7 @@ project that can be used after the project has been installed or packaged. If
 we want our project to also be used from a build directory we only have to add
 the following to the bottom of the top level ``CMakeLists.txt``:
 
-.. literalinclude:: Complete/CMakeLists.txt
+.. literalinclude:: Step12/CMakeLists.txt
   :language: cmake
   :start-after: # needs to be after the install(TARGETS ) command
 
@@ -848,55 +877,81 @@ With this export call we now generate a ``Targets.cmake``, allowing the
 configured ``MathFunctionsConfig.cmake`` in the build directory to be used by
 other projects, without needing it to be installed.
 
-Import a CMake Project (Consumer)
+Packaging Debug and Release (Step 12)
-=================================
+=====================================
 
-This example shows how a project can find other CMake packages that
+**Note:** This example is valid for single-configuration generators and will
-generate ``Config.cmake`` files.
+not work for multi-configuration generators (e.g. Visual Studio).
 
-It also shows how to state a project's external dependencies when generating
+By default, CMake's model is that a build directory only contains a single
-a ``Config.cmake``.
+configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is
+possible, however, to setup CPack to bundle multiple build directories and
+construct a package that contains multiple configurations of the same project.
 
-Packaging Debug and Release (MultiPackage)
+First, we want to ensure that the debug and release builds use different names
-==========================================
+for the executables and libraries that will be installed. Let's use `d` as the
+postfix for the debug executable and libraries.
 
-By default CMake's model is that a build directory only contains a single
+Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
-configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo.
+``CMakeLists.txt`` file:
 
-But it is possible to setup CPack to bundle multiple build directories at the
+.. literalinclude:: Complete/CMakeLists.txt
-same time to build a package that contains multiple configurations of the
+  :language: cmake
-same project.
+  :start-after: project(Tutorial VERSION 1.0)
+  :end-before: target_compile_features(tutorial_compiler_flags
 
-First we need to construct a directory called ``multi_config``, which
+And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable:
-will contain all the builds that we want to package together.
 
-Second create a ``debug`` and ``release`` directory underneath
+.. literalinclude:: Complete/CMakeLists.txt
-``multi_config``. At the end you should have a layout that looks like:
+  :language: cmake
+  :start-after: # add the executable
+  :end-before: # add the binary tree to the search path for include files
+
+Let's also add version numbering to the MathFunctions library. In
+``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and
+:prop_tgt:`SOVERSION` properties:
+
+.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # setup the version numbering
+  :end-before: # install rules
+
+From the ``Step12`` directory, create ``debug`` and ``release``
+subbdirectories. The layout will look like:
 
 .. code-block:: none
 
-  ─ multi_config
+  - Step12
-      ├── debug
+     - debug
-      └── release
+     - release
 
-Now we need to setup debug and release builds, which would roughly entail
+Now we need to setup debug and release builds. We can use
-the following:
+:variable:`CMAKE_BUILD_TYPE` to set the configuration type:
 
 .. code-block:: console
 
   cd debug
-  cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/
+  cmake -DCMAKE_BUILD_TYPE=Debug ..
   cmake --build .
   cd ../release
-  cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/
+  cmake -DCMAKE_BUILD_TYPE=Release ..
   cmake --build .
-  cd ..
 
+Now that both the debug and release builds are complete, we can use a custom
+configuration file to package both builds into a single release. In the
+``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this
+file, first include the default configuration file that was created by the
+:manual:`cmake  <cmake(1)>` executable.
 
-Now that both the debug and release builds are complete, we can use
+Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which
-a custom ``MultiCPackConfig.cmake`` file to package both builds into a single
+projects to install. In this case, we want to install both debug and release.
-release.
+
+.. literalinclude:: Complete/MultiCPackConfig.cmake
+  :language: cmake
+
+From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our
+custom configuration file with the ``config`` option:
 
 .. code-block:: console
 
-  cpack --config ../../MultiPackage/MultiCPackConfig.cmake
+  cpack --config MultiCPackConfig.cmake