Update upstream source from tag 'upstream/3.25.0'

Update to upstream version '3.25.0'
with Debian dir 068404b33fb7dc12acbeace99a929ff77eabff70

Auxiliary/cmake-mode.el

@@ -41,8 +41,8 @@ set the path with these commands:
   :group 'cmake)
 
 ;; Keywords
-(defconst cmake-keywords-block-open '("IF" "MACRO" "FOREACH" "ELSE" "ELSEIF" "WHILE" "FUNCTION"))
+(defconst cmake-keywords-block-open '("BLOCK" "IF" "MACRO" "FOREACH" "ELSE" "ELSEIF" "WHILE" "FUNCTION"))
-(defconst cmake-keywords-block-close '("ENDIF" "ENDFOREACH" "ENDMACRO" "ELSE" "ELSEIF" "ENDWHILE" "ENDFUNCTION"))
+(defconst cmake-keywords-block-close '("ENDBLOCK" "ENDIF" "ENDFOREACH" "ENDMACRO" "ELSE" "ELSEIF" "ENDWHILE" "ENDFUNCTION"))
 (defconst cmake-keywords
   (let ((kwds (append cmake-keywords-block-open cmake-keywords-block-close nil)))
     (delete-dups kwds)))
@@ -288,6 +288,39 @@ This puts the mark at the end, and point at the beginning."
 
 ;------------------------------------------------------------------------------
 
+(defun cmake--syntax-propertize-until-bracket-close (syntax)
+  ;; This function assumes that a previous search has matched the
+  ;; beginning of a bracket_comment or bracket_argument and that the
+  ;; second capture group has matched the equal signs between the two
+  ;; opening brackets
+  (let* ((mb (match-beginning 2))
+         (me (match-end 2))
+         (cb (format "]%s]" (buffer-substring mb me))))
+    (save-match-data
+      (if (search-forward cb end 'move)
+          (progn
+            (setq me (match-end 0))
+            (put-text-property
+             (1- me)
+             me
+             'syntax-table
+             (string-to-syntax syntax)))
+        (setq me end)))
+    (put-text-property
+     (match-beginning 1)
+     me
+     'syntax-multiline
+     t)))
+
+(defconst cmake--syntax-propertize-function
+  (syntax-propertize-rules
+   ("\\(#\\)\\[\\(=*\\)\\["
+    (1
+     (prog1 "!" (cmake--syntax-propertize-until-bracket-close "!"))))
+   ("\\(\\[\\)\\(=*\\)\\["
+    (1
+     (prog1 "|" (cmake--syntax-propertize-until-bracket-close "|"))))))
+
 ;; Syntax table for this mode.
 (defvar cmake-mode-syntax-table nil
   "Syntax table for CMake mode.")
@@ -318,7 +351,10 @@ This puts the mark at the end, and point at the beginning."
   ; Setup indentation function.
   (set (make-local-variable 'indent-line-function) 'cmake-indent)
   ; Setup comment syntax.
-  (set (make-local-variable 'comment-start) "#"))
+  (set (make-local-variable 'comment-start) "#")
+  ;; Setup syntax propertization
+  (set (make-local-variable 'syntax-propertize-function) cmake--syntax-propertize-function)
+  (add-hook 'syntax-propertize-extend-region-functions #'syntax-propertize-multiline nil t))
 
 ;; Default cmake-mode key bindings
 (define-key cmake-mode-map "\e\C-a" #'cmake-beginning-of-defun)

Auxiliary/vim/indent/cmake.vim

@@ -59,8 +59,8 @@ fun! CMakeGetIndent(lnum)
 
   let cmake_closing_parens_line = '^\s*\()\+\)\s*$'
 
-  let cmake_indent_begin_regex = '^\s*\(IF\|MACRO\|FOREACH\|ELSE\|ELSEIF\|WHILE\|FUNCTION\)\s*('
+  let cmake_indent_begin_regex = '^\s*\(BLOCK\|IF\|MACRO\|FOREACH\|ELSE\|ELSEIF\|WHILE\|FUNCTION\)\s*('
-  let cmake_indent_end_regex = '^\s*\(ENDIF\|ENDFOREACH\|ENDMACRO\|ELSE\|ELSEIF\|ENDWHILE\|ENDFUNCTION\)\s*('
+  let cmake_indent_end_regex = '^\s*\(ENDBLOCK\|ENDIF\|ENDFOREACH\|ENDMACRO\|ELSE\|ELSEIF\|ENDWHILE\|ENDFUNCTION\)\s*('
 
   if this_line =~? cmake_closing_parens_line
     if previous_line !~? cmake_indent_open_regex

Auxiliary/vim/syntax/cmake.vim

@@ -436,6 +436,7 @@ syn keyword cmakeProperty contained
             \ XCODE_SCHEME_ENVIRONMENT
             \ XCODE_SCHEME_EXECUTABLE
             \ XCODE_SCHEME_GUARD_MALLOC
+            \ XCODE_SCHEME_LAUNCH_MODE
             \ XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
             \ XCODE_SCHEME_MALLOC_GUARD_EDGES
             \ XCODE_SCHEME_MALLOC_SCRIBBLE
@@ -444,6 +445,9 @@ syn keyword cmakeProperty contained
             \ XCODE_SCHEME_THREAD_SANITIZER_STOP
             \ XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
             \ XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
+            \ XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
+            \ XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
+            \ XCODE_SCHEME_LAUNCH_CONFIGURATION
             \ XCODE_SCHEME_WORKING_DIRECTORY
             \ XCODE_SCHEME_ZOMBIE_OBJECTS
             \ XCTEST
@@ -1537,6 +1541,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
             \ CMAKE_XCODE_SCHEME_ENVIRONMENT
             \ CMAKE_XCODE_SCHEME_GUARD_MALLOC
+            \ CMAKE_XCODE_SCHEME_LAUNCH_MODE
             \ CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
             \ CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES
             \ CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE
@@ -1545,6 +1550,9 @@ syn keyword cmakeVariable contained
             \ CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP
             \ CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
             \ CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
+            \ CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
+            \ CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
+            \ CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION
             \ CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
             \ CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
             \ CPACK_ABSOLUTE_DESTINATION_FILES
@@ -3830,6 +3838,7 @@ syn keyword cmakeCommand
             \ add_subdirectory
             \ add_test
             \ aux_source_directory
+            \ block
             \ break
             \ build_command
             \ cmake_host_system_information
@@ -3857,6 +3866,7 @@ syn keyword cmakeCommand
             \ define_property
             \ enable_language
             \ enable_testing
+            \ endblock
             \ endfunction
             \ endmacro
             \ execute_process

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-cmake_minimum_required(VERSION 3.13...3.22 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.13...3.23 FATAL_ERROR)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
 
@@ -17,8 +17,8 @@ unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
 if(MSVC AND NOT CMAKE_VERSION VERSION_LESS 3.15)
   # Filter out MSVC runtime library flags that may have come from
   # the cache of an existing build tree or from scripts.
-  foreach(l C CXX)
+  foreach(l IN ITEMS C CXX)
-    foreach(c DEBUG MINSIZEREL RELEASE RELWITHDEBINFO)
+    foreach(c IN ITEMS DEBUG MINSIZEREL RELEASE RELWITHDEBINFO)
       string(REGEX REPLACE "[-/]M[DT]d?( |$)" "" "CMAKE_${l}_FLAGS_${c}" "${CMAKE_${l}_FLAGS_${c}}")
     endforeach()
   endforeach()
@@ -60,17 +60,6 @@ else()
   set(USE_LGPL "")
 endif()
 
-if("${CMake_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
-  # Disallow architecture-specific try_run.  It may not run on the host.
-  macro(TRY_RUN)
-    if(CMAKE_TRY_COMPILE_OSX_ARCHITECTURES)
-      message(FATAL_ERROR "TRY_RUN not allowed with CMAKE_TRY_COMPILE_OSX_ARCHITECTURES=[${CMAKE_TRY_COMPILE_OSX_ARCHITECTURES}]")
-    else()
-      _TRY_RUN(${ARGV})
-    endif()
-  endmacro()
-endif()
-
 # Use most-recent available language dialects with GNU and Clang
 if(NOT DEFINED CMAKE_C_STANDARD AND NOT CMake_NO_C_STANDARD)
   include(${CMake_SOURCE_DIR}/Source/Checks/cm_c11_thread_local.cmake)
@@ -81,7 +70,7 @@ if(NOT DEFINED CMAKE_C_STANDARD AND NOT CMake_NO_C_STANDARD)
   endif()
 endif()
 if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
-  if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
+  if(CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
     set(CMAKE_CXX_STANDARD 98)
   else()
     if(NOT CMAKE_VERSION VERSION_LESS 3.8)
@@ -114,9 +103,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
 endif()
 
 # Inform STL library header wrappers whether to use system versions.
-configure_file(${CMake_SOURCE_DIR}/Utilities/std/cmSTL.hxx.in
+configure_file(Utilities/std/cmSTL.hxx.in Utilities/cmSTL.hxx @ONLY)
-  ${CMake_BINARY_DIR}/Utilities/cmSTL.hxx
-  @ONLY)
 
 # set the internal encoding of CMake to UTF-8
 set(KWSYS_ENCODING_DEFAULT_CODEPAGE CP_UTF8)
@@ -143,7 +130,7 @@ option(CMake_BUILD_DEVELOPER_REFERENCE
 mark_as_advanced(CMake_BUILD_DEVELOPER_REFERENCE)
 
 # option to build using interprocedural optimizations (IPO/LTO)
-if (NOT CMAKE_VERSION VERSION_LESS 3.12.2)
+if(NOT CMAKE_VERSION VERSION_LESS 3.12.2)
   option(CMake_BUILD_LTO "Compile CMake with link-time optimization if supported" OFF)
   if(CMake_BUILD_LTO)
     include(CheckIPOSupported)
@@ -165,7 +152,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 NGHTTP2 ZLIB ZSTD)
-  foreach(util ${UTILITIES})
+  foreach(util IN LISTS UTILITIES)
     if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
         AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
       set(CMAKE_USE_SYSTEM_LIBRARY_${util} "${CMAKE_USE_SYSTEM_LIBRARIES}")
@@ -215,16 +202,14 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
   mark_as_advanced(CMAKE_USE_SYSTEM_KWIML)
 
   # Mention to the user what system libraries are being used.
-  foreach(util ${UTILITIES} KWIML)
+  foreach(util IN LISTS UTILITIES ITEMS KWIML)
     if(CMAKE_USE_SYSTEM_${util})
       message(STATUS "Using system-installed ${util}")
     endif()
   endforeach()
 
   # Inform utility library header wrappers whether to use system versions.
-  configure_file(${CMake_SOURCE_DIR}/Utilities/cmThirdParty.h.in
+  configure_file(Utilities/cmThirdParty.h.in Utilities/cmThirdParty.h @ONLY)
-    ${CMake_BINARY_DIR}/Utilities/cmThirdParty.h
-    @ONLY)
 
 endmacro()
 
@@ -235,7 +220,7 @@ endmacro()
 macro(CMAKE_SETUP_TESTING)
   if(BUILD_TESTING)
     set(CMAKE_TEST_SYSTEM_LIBRARIES 0)
-    foreach(util CURL EXPAT ZLIB)
+    foreach(util IN ITEMS CURL EXPAT ZLIB)
       if(CMAKE_USE_SYSTEM_${util})
         set(CMAKE_TEST_SYSTEM_LIBRARIES 1)
       endif()
@@ -250,7 +235,7 @@ macro(CMAKE_SETUP_TESTING)
       set(CMAKE_CTEST_COMMAND "${CMake_TEST_EXTERNAL_CMAKE}/ctest")
       set(CMAKE_CMAKE_COMMAND "${CMake_TEST_EXTERNAL_CMAKE}/cmake")
       set(CMAKE_CPACK_COMMAND "${CMake_TEST_EXTERNAL_CMAKE}/cpack")
-      foreach(exe cmake ctest cpack)
+      foreach(exe IN ITEMS cmake ctest cpack)
         add_executable(${exe} IMPORTED)
         set_property(TARGET ${exe} PROPERTY IMPORTED_LOCATION ${CMake_TEST_EXTERNAL_CMAKE}/${exe})
       endforeach()
@@ -262,18 +247,12 @@ macro(CMAKE_SETUP_TESTING)
   endif()
 
   # configure some files for testing
-  configure_file("${CMAKE_CURRENT_SOURCE_DIR}/Templates/CTestScript.cmake.in"
+  configure_file(Templates/CTestScript.cmake.in CTestScript.cmake @ONLY)
-    "${CMAKE_CURRENT_BINARY_DIR}/CTestScript.cmake"
+  configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage)
-    @ONLY)
+  configure_file(Tests/.NoDartCoverage Modules/.NoDartCoverage)
-  configure_file(${CMake_SOURCE_DIR}/Tests/.NoDartCoverage
+  configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY)
-    ${CMake_BINARY_DIR}/Tests/.NoDartCoverage)
-  configure_file(${CMake_SOURCE_DIR}/Tests/.NoDartCoverage
-    ${CMake_BINARY_DIR}/Modules/.NoDartCoverage)
-  configure_file(${CMake_SOURCE_DIR}/CTestCustom.cmake.in
-    ${CMake_BINARY_DIR}/CTestCustom.cmake @ONLY)
   if(BUILD_TESTING AND DART_ROOT)
-    configure_file(${CMake_SOURCE_DIR}/CMakeLogo.gif
+    configure_file(CMakeLogo.gif Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
-      ${CMake_BINARY_DIR}/Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
   endif()
   mark_as_advanced(DART_ROOT)
 endmacro()
@@ -339,390 +318,6 @@ macro(CMAKE_SET_TARGET_FOLDER tgt folder)
   endif()
 endmacro()
 
-
-#-----------------------------------------------------------------------
-# a macro to build the utilities used by CMake
-# Simply to improve readability of the main script.
-#-----------------------------------------------------------------------
-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)
-  set(KWSYS_USE_SystemTools 1)
-  set(KWSYS_USE_Directory 1)
-  set(KWSYS_USE_RegularExpression 1)
-  set(KWSYS_USE_Base64 1)
-  set(KWSYS_USE_MD5 1)
-  set(KWSYS_USE_Process 1)
-  set(KWSYS_USE_CommandLineArguments 1)
-  set(KWSYS_USE_ConsoleBuf 1)
-  set(KWSYS_HEADER_ROOT ${CMake_BINARY_DIR}/Source)
-  set(KWSYS_INSTALL_DOC_DIR "${CMAKE_DOC_DIR}")
-  if(CMake_NO_CXX_STANDARD)
-    set(KWSYS_CXX_STANDARD "")
-  endif()
-  if(CMake_NO_SELF_BACKTRACE)
-    set(KWSYS_NO_EXECINFO 1)
-  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}")
-  CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}_c "${kwsys_folder}")
-  if(BUILD_TESTING)
-    CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestDynload "${kwsys_folder}")
-    CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestProcess "${kwsys_folder}")
-    CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestsC "${kwsys_folder}")
-    CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestsCxx "${kwsys_folder}")
-    CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestSharedForward "${kwsys_folder}")
-  endif()
-
-  #---------------------------------------------------------------------
-  # Setup third-party libraries.
-  # Everything in the tree should be able to include files from the
-  # Utilities directory.
-  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("${CMake_BINARY_DIR}/Utilities")
-  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")
-  else()
-    include_directories(SYSTEM "${CMake_SOURCE_DIR}/Utilities")
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build CMake std library for CMake and CTest.
-  set(CMAKE_STD_LIBRARY cmstd)
-  add_subdirectory(Utilities/std)
-  CMAKE_SET_TARGET_FOLDER(cmstd "Utilities/std")
-
-  # check for the use of system libraries versus builtin ones
-  # (a macro defined in this file)
-  CMAKE_HANDLE_SYSTEM_LIBRARIES()
-
-  if(CMAKE_USE_SYSTEM_KWIML)
-    find_package(KWIML 1.0)
-    if(NOT KWIML_FOUND)
-      message(FATAL_ERROR "CMAKE_USE_SYSTEM_KWIML is ON but KWIML is not found!")
-    endif()
-    set(CMake_KWIML_LIBRARIES kwiml::kwiml)
-  else()
-    set(CMake_KWIML_LIBRARIES "")
-    if(BUILD_TESTING)
-      set(KWIML_TEST_ENABLE 1)
-    endif()
-    add_subdirectory(Utilities/KWIML)
-  endif()
-
-  if(CMAKE_USE_SYSTEM_LIBRHASH)
-    find_package(LibRHash)
-    if(NOT LibRHash_FOUND)
-      message(FATAL_ERROR
-        "CMAKE_USE_SYSTEM_LIBRHASH is ON but LibRHash is not found!")
-    endif()
-    set(CMAKE_LIBRHASH_LIBRARIES LibRHash::LibRHash)
-  else()
-    set(CMAKE_LIBRHASH_LIBRARIES cmlibrhash)
-    add_subdirectory(Utilities/cmlibrhash)
-    CMAKE_SET_TARGET_FOLDER(cmlibrhash "Utilities/3rdParty")
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build zlib library for Curl, CMake, and CTest.
-  set(CMAKE_ZLIB_HEADER "cm_zlib.h")
-  if(CMAKE_USE_SYSTEM_ZLIB)
-    find_package(ZLIB)
-    if(NOT ZLIB_FOUND)
-      message(FATAL_ERROR
-        "CMAKE_USE_SYSTEM_ZLIB is ON but a zlib is not found!")
-    endif()
-    set(CMAKE_ZLIB_INCLUDES ${ZLIB_INCLUDE_DIR})
-    set(CMAKE_ZLIB_LIBRARIES ${ZLIB_LIBRARIES})
-  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()
-
-  #---------------------------------------------------------------------
-  # Build Curl library for CTest.
-  if(CMAKE_USE_SYSTEM_CURL)
-    find_package(CURL)
-    if(NOT CURL_FOUND)
-      message(FATAL_ERROR
-        "CMAKE_USE_SYSTEM_CURL is ON but a curl is not found!")
-    endif()
-    set(CMAKE_CURL_INCLUDES ${CURL_INCLUDE_DIRS})
-    set(CMAKE_CURL_LIBRARIES ${CURL_LIBRARIES})
-  else()
-    set(CURL_SPECIAL_ZLIB_H ${CMAKE_ZLIB_HEADER})
-    set(CURL_SPECIAL_LIBZ_INCLUDES ${CMAKE_ZLIB_INCLUDES})
-    set(CURL_SPECIAL_LIBZ ${CMAKE_ZLIB_LIBRARIES})
-    set(CMAKE_CURL_INCLUDES)
-    set(CMAKE_CURL_LIBRARIES cmcurl)
-    if(CMAKE_TESTS_CDASH_SERVER)
-      set(CMAKE_CURL_TEST_URL "${CMAKE_TESTS_CDASH_SERVER}/user.php")
-    endif()
-    set(_CMAKE_USE_OPENSSL_DEFAULT OFF)
-    if(NOT DEFINED CMAKE_USE_OPENSSL AND NOT WIN32 AND NOT APPLE
-        AND CMAKE_SYSTEM_NAME MATCHES "(Linux|FreeBSD)")
-      set(_CMAKE_USE_OPENSSL_DEFAULT ON)
-    endif()
-    option(CMAKE_USE_OPENSSL "Use OpenSSL." ${_CMAKE_USE_OPENSSL_DEFAULT})
-    mark_as_advanced(CMAKE_USE_OPENSSL)
-    if(CMAKE_USE_OPENSSL)
-      set(CURL_CA_BUNDLE "" CACHE FILEPATH "Path to SSL CA Certificate Bundle")
-      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()
-
-  #---------------------------------------------------------------------
-  # Build expat library for CMake, CTest, and libarchive.
-  if(CMAKE_USE_SYSTEM_EXPAT)
-    find_package(EXPAT)
-    if(NOT EXPAT_FOUND)
-      message(FATAL_ERROR
-        "CMAKE_USE_SYSTEM_EXPAT is ON but a expat is not found!")
-    endif()
-    set(CMAKE_EXPAT_INCLUDES ${EXPAT_INCLUDE_DIRS})
-    set(CMAKE_EXPAT_LIBRARIES ${EXPAT_LIBRARIES})
-  else()
-    set(CMAKE_EXPAT_INCLUDES)
-    set(CMAKE_EXPAT_LIBRARIES cmexpat)
-    add_subdirectory(Utilities/cmexpat)
-    CMAKE_SET_TARGET_FOLDER(cmexpat "Utilities/3rdParty")
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build or use system libbz2 for libarchive.
-  if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
-    if(CMAKE_USE_SYSTEM_BZIP2)
-      find_package(BZip2)
-    else()
-      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()
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build or use system zstd for libarchive.
-  if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
-    if(NOT CMAKE_USE_SYSTEM_ZSTD)
-      set(ZSTD_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmzstd")
-      set(ZSTD_LIBRARY cmzstd)
-      add_subdirectory(Utilities/cmzstd)
-      CMAKE_SET_TARGET_FOLDER(cmzstd "Utilities/3rdParty")
-    endif()
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build or use system liblzma for libarchive.
-  if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
-    if(CMAKE_USE_SYSTEM_LIBLZMA)
-      find_package(LibLZMA)
-      if(NOT LIBLZMA_FOUND)
-        message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBLZMA is ON but LibLZMA is not found!")
-      endif()
-    else()
-      add_subdirectory(Utilities/cmliblzma)
-      CMAKE_SET_TARGET_FOLDER(cmliblzma "Utilities/3rdParty")
-      set(LIBLZMA_HAS_AUTO_DECODER 1)
-      set(LIBLZMA_HAS_EASY_ENCODER 1)
-      set(LIBLZMA_HAS_LZMA_PRESET 1)
-      set(LIBLZMA_INCLUDE_DIR
-        "${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmliblzma/liblzma/api")
-      set(LIBLZMA_LIBRARY cmliblzma)
-      set(HAVE_LZMA_STREAM_ENCODER_MT 1)
-    endif()
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build or use system libarchive for CMake and CTest.
-  if(CMAKE_USE_SYSTEM_LIBARCHIVE)
-    find_package(LibArchive 3.3.3)
-    if(NOT LibArchive_FOUND)
-      message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBARCHIVE is ON but LibArchive is not found!")
-    endif()
-    set(CMAKE_TAR_INCLUDES ${LibArchive_INCLUDE_DIRS})
-    set(CMAKE_TAR_LIBRARIES ${LibArchive_LIBRARIES})
-  else()
-    set(EXPAT_INCLUDE_DIR ${CMAKE_EXPAT_INCLUDES})
-    set(EXPAT_LIBRARY ${CMAKE_EXPAT_LIBRARIES})
-    set(ZLIB_INCLUDE_DIR ${CMAKE_ZLIB_INCLUDES})
-    set(ZLIB_LIBRARY ${CMAKE_ZLIB_LIBRARIES})
-    add_definitions(-DLIBARCHIVE_STATIC)
-    set(ENABLE_MBEDTLS OFF)
-    set(ENABLE_NETTLE OFF)
-    if(DEFINED CMAKE_USE_OPENSSL)
-      set(ENABLE_OPENSSL "${CMAKE_USE_OPENSSL}")
-    else()
-      set(ENABLE_OPENSSL OFF)
-    endif()
-    set(ENABLE_LIBB2 OFF)
-    set(ENABLE_LZ4 OFF)
-    set(ENABLE_LZO OFF)
-    set(ENABLE_LZMA ON)
-    set(ENABLE_ZSTD ON)
-    set(ENABLE_ZLIB ON)
-    set(ENABLE_BZip2 ON)
-    set(ENABLE_LIBXML2 OFF)
-    set(ENABLE_EXPAT OFF)
-    set(ENABLE_PCREPOSIX OFF)
-    set(ENABLE_LibGCC OFF)
-    set(ENABLE_CNG OFF)
-    set(ENABLE_TAR OFF)
-    set(ENABLE_TAR_SHARED OFF)
-    set(ENABLE_CPIO OFF)
-    set(ENABLE_CPIO_SHARED OFF)
-    set(ENABLE_CAT OFF)
-    set(ENABLE_CAT_SHARED OFF)
-    set(ENABLE_XATTR OFF)
-    set(ENABLE_ACL OFF)
-    set(ENABLE_ICONV OFF)
-    set(ENABLE_TEST OFF)
-    set(ENABLE_COVERAGE OFF)
-    set(ENABLE_INSTALL OFF)
-    set(POSIX_REGEX_LIB "" CACHE INTERNAL "libarchive: No POSIX regular expression support")
-    set(ENABLE_SAFESEH "" CACHE INTERNAL "libarchive: No /SAFESEH linker flag")
-    set(WINDOWS_VERSION "WIN7" CACHE INTERNAL "libarchive: Set Windows version to use (Windows only)")
-    add_subdirectory(Utilities/cmlibarchive)
-    CMAKE_SET_TARGET_FOLDER(cmlibarchive "Utilities/3rdParty")
-    set(CMAKE_TAR_LIBRARIES cmlibarchive ${BZIP2_LIBRARIES})
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build jsoncpp library.
-  if(CMAKE_USE_SYSTEM_JSONCPP)
-    find_package(JsonCpp 1.4.1)
-    if(NOT JsonCpp_FOUND)
-      message(FATAL_ERROR
-        "CMAKE_USE_SYSTEM_JSONCPP is ON but a JsonCpp is not found!")
-    endif()
-    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|LCC|Clang")
-      set_property(TARGET JsonCpp::JsonCpp APPEND PROPERTY
-        INTERFACE_COMPILE_OPTIONS -Wno-deprecated-declarations)
-    endif()
-    set(CMAKE_JSONCPP_LIBRARIES JsonCpp::JsonCpp)
-  else()
-    set(CMAKE_JSONCPP_LIBRARIES cmjsoncpp)
-    add_subdirectory(Utilities/cmjsoncpp)
-    CMAKE_SET_TARGET_FOLDER(cmjsoncpp "Utilities/3rdParty")
-  endif()
-
-  #---------------------------------------------------------------------
-  # Build libuv library.
-  if(CMAKE_USE_SYSTEM_LIBUV)
-    if(WIN32)
-      find_package(LibUV 1.38.0)
-    else()
-      find_package(LibUV 1.28.0)
-    endif()
-    if(NOT LIBUV_FOUND)
-      message(FATAL_ERROR
-        "CMAKE_USE_SYSTEM_LIBUV is ON but a libuv is not found!")
-    endif()
-    set(CMAKE_LIBUV_LIBRARIES LibUV::LibUV)
-  else()
-    set(CMAKE_LIBUV_LIBRARIES cmlibuv)
-    add_subdirectory(Utilities/cmlibuv)
-    CMAKE_SET_TARGET_FOLDER(cmlibuv "Utilities/3rdParty")
-  endif()
-
-  #---------------------------------------------------------------------
-  # Use curses?
-  if(NOT DEFINED BUILD_CursesDialog)
-    if (UNIX)
-      include(${CMake_SOURCE_DIR}/Source/Checks/Curses.cmake)
-      set(BUILD_CursesDialog_DEFAULT "${CMakeCheckCurses_COMPILED}")
-    elseif(WIN32)
-      set(BUILD_CursesDialog_DEFAULT "OFF")
-    endif()
-    option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${BUILD_CursesDialog_DEFAULT}")
-  endif ()
-  if(BUILD_CursesDialog)
-    if(UNIX)
-      set(CURSES_NEED_NCURSES TRUE)
-      find_package(Curses)
-      if(NOT CURSES_FOUND)
-        message(WARNING
-          "'ccmake' will not be built because Curses was not found.\n"
-          "Turn off BUILD_CursesDialog to suppress this message."
-          )
-        set(BUILD_CursesDialog 0)
-      endif()
-    elseif(WIN32)
-      # FIXME: Add support for system-provided pdcurses.
-      add_subdirectory(Utilities/cmpdcurses)
-      set(CURSES_LIBRARY cmpdcurses)
-      set(CURSES_INCLUDE_PATH "") # cmpdcurses has usage requirements
-      set(CMAKE_USE_SYSTEM_FORM 0)
-      set(HAVE_CURSES_USE_DEFAULT_COLORS 1)
-    endif()
-  endif()
-  if(BUILD_CursesDialog)
-    if(NOT CMAKE_USE_SYSTEM_FORM)
-      add_subdirectory(Source/CursesDialog/form)
-    elseif(NOT CURSES_FORM_LIBRARY)
-      message( FATAL_ERROR "CMAKE_USE_SYSTEM_FORM in ON but CURSES_FORM_LIBRARY is not set!" )
-    endif()
-  endif()
-endmacro ()
-
 #-----------------------------------------------------------------------
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
   if(CMAKE_CXX_PLATFORM_ID MATCHES "OpenBSD")
@@ -749,7 +344,7 @@ include(Source/CMakeVersion.cmake)
 
 # Include the standard Dart testing module
 enable_testing()
-include (${CMAKE_ROOT}/Modules/Dart.cmake)
+include(${CMAKE_ROOT}/Modules/Dart.cmake)
 
 # Set up test-time configuration.
 set_directory_properties(PROPERTIES
@@ -803,8 +398,9 @@ if(CMake_TEST_EXTERNAL_CMAKE)
 endif()
 
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
-  # build the utilities (a macro defined in this file)
+  find_package(Threads)
-  CMAKE_BUILD_UTILITIES()
+  # build the utilities
+  include(CMakeBuildUtilities)
 
   if(BUILD_QtDialog)
     if(APPLE)
@@ -813,10 +409,9 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
       set(CMAKE_BUNDLE_LOCATION "${CMAKE_INSTALL_PREFIX}")
       # make sure CMAKE_INSTALL_PREFIX ends in /
       if(NOT CMAKE_INSTALL_PREFIX MATCHES "/$")
-        set(CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}/")
+        string(APPEND CMAKE_INSTALL_PREFIX "/")
       endif()
-      set(CMAKE_INSTALL_PREFIX
+      string(APPEND CMAKE_INSTALL_PREFIX "CMake.app/Contents")
-        "${CMAKE_INSTALL_PREFIX}CMake.app/Contents")
     endif()
   endif()
 
@@ -829,14 +424,11 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
   endif()
 
   # add the uninstall support
-  configure_file(
+  configure_file(cmake_uninstall.cmake.in cmake_uninstall.cmake @ONLY)
-    "${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"
-    "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"
-    @ONLY)
   add_custom_target(uninstall
     "${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")
 
-  include (CMakeCPack.cmake)
+  include(CMakeCPack.cmake)
 
 endif()
 
@@ -860,10 +452,10 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
                          -Wshadow -Wpointer-arith -Wformat-security -Wundef
       )
 
-      foreach(FLAG_LANG  C CXX)
+      foreach(FLAG_LANG IN ITEMS C CXX)
-        foreach(FLAG ${${FLAG_LANG}_FLAGS_LIST})
+        foreach(FLAG IN LISTS ${FLAG_LANG}_FLAGS_LIST)
           if(NOT " ${CMAKE_${FLAG_LANG}_FLAGS} " MATCHES " ${FLAG} ")
-            set(CMAKE_${FLAG_LANG}_FLAGS "${CMAKE_${FLAG_LANG}_FLAGS} ${FLAG}")
+            string(APPEND CMAKE_${FLAG_LANG}_FLAGS " ${FLAG}")
           endif()
         endforeach()
       endforeach()
@@ -883,9 +475,6 @@ add_subdirectory(Tests)
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
   if(BUILD_TESTING)
     CMAKE_SET_TARGET_FOLDER(CMakeLibTests "Tests")
-    IF(TARGET CMakeServerLibTests)
-      CMAKE_SET_TARGET_FOLDER(CMakeServerLibTests "Tests")
-    ENDIF()
   endif()
   if(TARGET documentation)
     CMAKE_SET_TARGET_FOLDER(documentation "Documentation")
@@ -894,7 +483,8 @@ endif()
 
 if(BUILD_TESTING)
   add_test(SystemInformationNew "${CMAKE_CMAKE_COMMAND}"
-    --system-information  -G "${CMAKE_GENERATOR}" )
+    --system-information  -G "${CMAKE_GENERATOR}"
+  )
 endif()
 
 if(NOT CMake_TEST_EXTERNAL_CMAKE)

CTestCustom.cmake.in

@@ -74,6 +74,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*rand.*may return deterministic values"
   "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
+  "cmFindPackageCommand.cxx.*: warning #177-D: parameter .* was declared but never referenced"
   "IPA warning: function.*multiply defined in"
   "LICENSE WARNING" # PGI license expiry.  Not useful in nightly testing.
 
@@ -83,6 +84,11 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "compilation completed with warnings" # PGI
   "[0-9]+ Warning\\(s\\) detected" # SunPro
 
+  # Ignore false positive on `cm::optional` usage from GCC
+  "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' may be used uninitialized \\[-Wmaybe-uninitialized\\]"
+  "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: note: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' was declared here"
+  "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& modmap_fmt \\+4\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
+
   # clang-analyzer exceptions
   "cmListFileLexer.c:[0-9]+:[0-9]+: warning: Array subscript is undefined"
   "jsoncpp/src/.*:[0-9]+:[0-9]+: warning: Value stored to .* is never read"

CompileFlags.cmake

@@ -18,12 +18,12 @@ endif()
 # not hurt other versions, and this will work into the
 # future
 if(MSVC OR _INTEL_WINDOWS OR _CLANG_MSVC_WINDOWS)
-  add_definitions(-D_CRT_SECURE_NO_DEPRECATE -D_CRT_NONSTDC_NO_DEPRECATE)
+  add_compile_definitions(_CRT_SECURE_NO_DEPRECATE _CRT_NONSTDC_NO_DEPRECATE)
 else()
 endif()
 
 if(MSVC)
-  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -stack:10000000")
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${CMAKE_CXX_LINKER_WRAPPER_FLAG}-stack:10000000")
 endif()
 
 # MSVC 14.28 enables C5105, but the Windows SDK 10.0.18362.0 triggers it.
@@ -62,7 +62,7 @@ endif()
 # Use 64-bit off_t on 32-bit Linux
 if (CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SIZEOF_VOID_P EQUAL 4)
   # ensure 64bit offsets are used for filesystem accesses for 32bit compilation
-  add_definitions(-D_FILE_OFFSET_BITS=64)
+  add_compile_definitions(_FILE_OFFSET_BITS=64)
 endif()
 
 # Workaround for TOC Overflow on ppc64
@@ -98,7 +98,7 @@ if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND
   endif()
 endif()
 
-foreach(lang C CXX)
+foreach(lang IN ITEMS C CXX)
   # Suppress warnings from PGI compiler.
   if (CMAKE_${lang}_COMPILER_ID STREQUAL "PGI")
     set(CMAKE_${lang}_FLAGS "${CMAKE_${lang}_FLAGS} -w")
@@ -136,3 +136,12 @@ OFF to disable /MP completely." )
     endif()
   endif()
 endif()
+
+# Get rid of excess -Wunused-but-set-variable on release builds with LCC >= 1.26
+foreach(l IN ITEMS C CXX)
+  if(CMAKE_${l}_COMPILER_ID STREQUAL "LCC" AND NOT CMAKE_${l}_COMPILER_VERSION VERSION_LESS 1.26)
+    foreach(c IN ITEMS MINSIZEREL RELEASE RELWITHDEBINFO)
+      string(APPEND "CMAKE_${l}_FLAGS_${c}" " -Wno-unused-but-set-variable")
+    endforeach()
+  endif()
+endforeach()

Copyright.txt

@@ -53,6 +53,7 @@ The following individuals and institutions are among the Contributors:
 * Clement Creusot <creusot@cs.york.ac.uk>
 * Daniel Blezek <blezek@gmail.com>
 * Daniel Pfeifer <daniel@pfeifer-mail.de>
+* Dawid Wróbel <me@dawidwrobel.com>
 * Enrico Scholz <enrico.scholz@informatik.tu-chemnitz.de>
 * Eran Ifrah <eran.ifrah@gmail.com>
 * Esben Mose Hansen, Ange Optimization ApS

Help/command/FIND_XXX.txt

@@ -15,6 +15,7 @@ The general signature is:
              [PATHS [path | ENV var]... ]
              [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
              [PATH_SUFFIXES suffix1 [suffix2 ...]]
+             [VALIDATOR function]
              [DOC "cache documentation string"]
              [NO_CACHE]
              [REQUIRED]
@@ -66,6 +67,31 @@ Options include:
   Specify additional subdirectories to check below each directory
   location otherwise considered.
 
+``VALIDATOR``
+  .. versionadded:: 3.25
+
+  Specify a :command:`function` to be called for each candidate item found
+  (a :command:`macro` cannot be provided, that will result in an error).
+  Two arguments will be passed to the validator function: the name of a
+  result variable, and the absolute path to the candidate item.  The item
+  will be accepted and the search will end unless the function sets the
+  value in the result variable to false in the calling scope.  The result
+  variable will hold a true value when the validator function is entered.
+
+  .. parsed-literal::
+
+     function(my_check validator_result_var item)
+       if(NOT item MATCHES ...)
+         set(${validator_result_var} FALSE PARENT_SCOPE)
+       endif()
+     endfunction()
+
+     |FIND_XXX| (result NAMES ... VALIDATOR my_check)
+
+  Note that if a cached result is used, the search is skipped and any
+  ``VALIDATOR`` is ignored.  The cached result is not required to pass the
+  validation function.
+
 ``DOC``
   Specify the documentation string for the ``<VAR>`` cache entry.
 

Help/command/add_custom_command.rst

@@ -67,6 +67,8 @@ The options are:
   Each byproduct file will be marked with the :prop_sf:`GENERATED`
   source file property automatically.
 
+  *See policy* :policy:`CMP0058` *for the motivation behind this feature.*
+
   Explicit specification of byproducts is supported by the
   :generator:`Ninja` generator to tell the ``ninja`` build tool
   how to regenerate byproducts when they are missing.  It is
@@ -434,7 +436,7 @@ one of the keywords to make clear the behavior they expect.
   Because generator expressions can be used in custom commands,
   it is possible to define ``COMMAND`` lines or whole custom commands
   which evaluate to empty strings for certain configurations.
-  For **Visual Studio 2010 (and newer)** generators these command
+  For **Visual Studio 11 2012 (and newer)** generators these command
   lines or custom commands will be omitted for the specific
   configuration and no "empty-string-command" will be added.
 

Help/command/add_custom_target.rst

@@ -42,6 +42,8 @@ The options are:
   Each byproduct file will be marked with the :prop_sf:`GENERATED`
   source file property automatically.
 
+  *See policy* :policy:`CMP0058` *for the motivation behind this feature.*
+
   Explicit specification of byproducts is supported by the
   :generator:`Ninja` generator to tell the ``ninja`` build tool
   how to regenerate byproducts when they are missing.  It is

Help/command/add_subdirectory.rst

@@ -5,7 +5,7 @@ Add a subdirectory to the build.
 
 .. code-block:: cmake
 
-  add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
+  add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
 
 Adds a subdirectory to the build.  The source_dir specifies the
 directory in which the source CMakeLists.txt and code files are
@@ -33,3 +33,10 @@ dependencies supersede this exclusion.  If a target built by the
 parent project depends on a target in the subdirectory, the dependee
 target will be included in the parent project build system to satisfy
 the dependency.
+
+If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
+property of the subdirectory will be set to true.  This property is
+used to initialize the :prop_tgt:`SYSTEM` property of each target
+created in that subdirectory. The include directories of targets with
+:prop_tgt:`SYSTEM` set to true will be treated as ``SYSTEM`` when
+compiling consumers.

Help/command/block.rst

@@ -0,0 +1,76 @@
+block
+-----
+
+.. versionadded:: 3.25
+
+Evaluate a group of commands with a dedicated variable and/or policy scope.
+
+.. code-block:: cmake
+
+  block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE <var-name>...])
+    <commands>
+  endblock()
+
+All commands between ``block()`` and the matching :command:`endblock` are
+recorded without being invoked.  Once the :command:`endblock` is evaluated, the
+recorded list of commands is invoked inside the requested scopes, then the
+scopes created by the ``block()`` command are removed.
+
+``SCOPE_FOR``
+  Specify which scopes must be created.
+
+  ``POLICIES``
+    Create a new policy scope. This is equivalent to
+    :command:`cmake_policy(PUSH)`.
+
+  ``VARIABLES``
+    Create a new variable scope.
+
+  If ``SCOPE_FOR`` is not specified, this is equivalent to:
+
+  .. code-block:: cmake
+
+    block(SCOPE_FOR VARIABLES POLICIES)
+
+``PROPAGATE``
+  When a variable scope is created by the :command:`block` command, this
+  option sets or unsets the specified variables in the parent scope. This is
+  equivalent to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)`
+  commands.
+
+  .. code-block:: cmake
+
+    set(var1 "INIT1")
+    set(var2 "INIT2")
+
+    block(PROPAGATE var1 var2)
+      set(var1 "VALUE1")
+      unset(var2)
+    endblock()
+
+    # Now var1 holds VALUE1, and var2 is unset
+
+  This option is only allowed when a variable scope is created. An error will
+  be raised in the other cases.
+
+When the ``block()`` is inside a :command:`foreach` or :command:`while`
+command, the :command:`break` and :command:`continue` commands can be used
+inside the block.
+
+.. code-block:: cmake
+
+  while(TRUE)
+    block()
+       ...
+       # the break() command will terminate the while() command
+       break()
+    endblock()
+  endwhile()
+
+
+See Also
+^^^^^^^^
+
+  * :command:`endblock`
+  * :command:`return`
+  * :command:`cmake_policy`

Help/command/build_command.rst

@@ -24,12 +24,12 @@ options, if any.  The trailing ``-- -i`` option is added for
 :ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to
 ``NEW``.
 
-When invoked, this ``cmake --build`` command line will launch the
+When invoked, this :option:`cmake --build` command line will launch the
 underlying build system tool.
 
 .. versionadded:: 3.21
-  The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel``
+  The ``PARALLEL_LEVEL`` argument can be used to set the
-  flag.
+  :option:`--parallel <cmake--build --parallel>` flag.
 
 .. code-block:: cmake
 
@@ -39,7 +39,7 @@ This second signature is deprecated, but still available for backwards
 compatibility.  Use the first signature instead.
 
 It sets the given ``<cachevariable>`` to a command-line string as
-above but without the ``--target`` option.
+above but without the :option:`--target <cmake--build --target>` option.
 The ``<makecommand>`` is ignored but should be the full path to
 devenv, nmake, make or one of the end user build tools
 for legacy invocations.

Help/command/cmake_language.rst

@@ -14,6 +14,7 @@ Synopsis
   cmake_language(`EVAL`_ CODE <code>...)
   cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
   cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
+  cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
 
 Introduction
 ^^^^^^^^^^^^
@@ -50,6 +51,7 @@ is equivalent to
   To ensure consistency of the code, the following commands are not allowed:
 
   * ``if`` / ``elseif`` / ``else`` / ``endif``
+  * ``block`` / ``endblock``
   * ``while`` / ``endwhile``
   * ``foreach`` / ``endforeach``
   * ``function`` / ``endfunction``
@@ -491,3 +493,29 @@ calling the provider command recursively for the same dependency.
     SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
     SUPPORTED_METHODS FIND_PACKAGE
   )
+
+Getting current message log level
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.25
+
+.. _GET_MESSAGE_LOG_LEVEL:
+.. _query_message_log_level:
+
+.. code-block:: cmake
+
+  cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
+
+Writes the current :command:`message` logging level
+into the given ``<output_variable>``.
+
+See :command:`message` for the possible logging levels.
+
+The current message logging level can be set either using the
+:option:`--log-level <cmake --log-level>`
+command line option of the :manual:`cmake(1)` program or using
+the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
+
+If both the command line option and the variable are set, the command line
+option takes precedence. If neither are set, the default logging level
+is returned.

Help/command/cmake_policy.rst

@@ -103,6 +103,47 @@ Calls to the :command:`cmake_minimum_required(VERSION)`,
 ``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands
 influence only the current top of the policy stack.
 
+.. versionadded:: 3.25
+  The :command:`block` and :command:`endblock` commands offer a more flexible
+  and more secure way to manage the policy stack. The pop action is done
+  automatically when the :command:`endblock` command is executed, so it avoid
+  to call the :command:`cmake_policy(POP)` command before each
+  :command:`return` command.
+
+  .. code-block:: cmake
+
+    # stack management with cmake_policy()
+    function(my_func)
+      cmake_policy(PUSH)
+      cmake_policy(SET ...)
+      if (<cond1>)
+        ...
+        cmake_policy(POP)
+        return()
+      elseif(<cond2>)
+        ...
+        cmake_policy(POP)
+        return()
+      endif()
+      ...
+      cmake_policy(POP)
+    endfunction()
+
+    # stack management with block()/endblock()
+    function(my_func)
+      block(SCOPE_FOR POLICIES)
+        cmake_policy(SET ...)
+        if (<cond1>)
+          ...
+          return()
+        elseif(<cond2>)
+          ...
+          return()
+        endif()
+        ...
+      endblock()
+    endfunction()
+
 Commands created by the :command:`function` and :command:`macro`
 commands record policy settings when they are created and
 use the pre-record policies when they are invoked.  If the function or

Help/command/continue.rst

@@ -9,8 +9,8 @@ Continue to the top of enclosing foreach or while loop.
 
   continue()
 
-The ``continue`` command allows a cmake script to abort the rest of a block
+The ``continue()`` command allows a cmake script to abort the rest of the
-in a :command:`foreach` or :command:`while` loop, and start at the top of
+current iteration of a :command:`foreach` or :command:`while` loop, and start
-the next iteration.
+at the top of the next iteration.
 
 See also the :command:`break` command.

Help/command/ctest_build.rst

@@ -40,8 +40,8 @@ The options are:
 ``CONFIGURATION <config>``
   Specify the build configuration (e.g. ``Debug``).  If not
   specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
-  Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
+  Otherwise the :option:`-C \<cfg\> <ctest -C>` option given to the
-  command will be used, if any.
+  :manual:`ctest(1)` command will be used, if any.
 
 ``PARALLEL_LEVEL <parallel>``
   .. versionadded:: 3.21
@@ -54,7 +54,7 @@ The options are:
   Pass additional arguments to the underlying build command.
   If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
   This can, e.g., be used to trigger a parallel build using the
-  ``-j`` option of make. See the :module:`ProcessorCount` module
+  ``-j`` option of ``make``. See the :module:`ProcessorCount` module
   for an example.
 
 ``PROJECT_NAME <project-name>``

Help/command/ctest_run_script.rst

@@ -1,15 +1,15 @@
 ctest_run_script
 ----------------
 
-runs a ctest -S script
+runs a :option:`ctest -S` script
 
 ::
 
   ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
               script_file_name2 ... [RETURN_VALUE var])
 
-Runs a script or scripts much like if it was run from ctest -S.  If no
+Runs a script or scripts much like if it was run from :option:`ctest -S`.
-argument is provided then the current script is run using the current
+If no argument is provided then the current script is run using the current
 settings of the variables.  If ``NEW_PROCESS`` is specified then each
 script will be run in a separate process.If ``RETURN_VALUE`` is specified
 the return value of the last script run will be put into ``var``.

Help/command/ctest_start.rst

@@ -45,7 +45,7 @@ The parameters are as follows:
 
     ctest_start(Experimental GROUP GroupExperimental)
 
-  Later, in another ``ctest -S`` script:
+  Later, in another :option:`ctest -S` script:
 
   .. code-block:: cmake
 

Help/command/ctest_test.rst

@@ -109,8 +109,9 @@ The options are:
   While running tests in parallel, try not to start tests when they
   may cause the CPU load to pass above a given threshold.  If not
   specified the :variable:`CTEST_TEST_LOAD` variable will be checked,
-  and then the ``--test-load`` command-line argument to :manual:`ctest(1)`.
+  and then the :option:`--test-load <ctest --test-load>` command-line
-  See also the ``TestLoad`` setting in the :ref:`CTest Test Step`.
+  argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting
+  in the :ref:`CTest Test Step`.
 
 ``REPEAT <mode>:<n>``
   .. versionadded:: 3.17
@@ -176,8 +177,9 @@ See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`,
 :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and
 :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their
 corresponding :manual:`ctest(1)` command line options
-``--test-output-size-passed``, ``--test-output-size-failed``, and
+:option:`--test-output-size-passed <ctest --test-output-size-passed>`,
-``--test-output-truncation``.
+:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and
+:option:`--test-output-truncation <ctest --test-output-truncation>`.
 
 .. _`Additional Test Measurements`:
 

Help/command/enable_language.rst

@@ -1,13 +1,14 @@
 enable_language
 ---------------
-Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
+
+Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
 
 .. code-block:: cmake
 
-  enable_language(<lang> [OPTIONAL] )
+  enable_language(<lang>... [OPTIONAL])
 
-Enables support for the named language in CMake.  This is
+Enables support for the named languages in CMake.  This is the same as
-the same as the :command:`project` command but does not create any of the extra
+the :command:`project` command but does not create any of the extra
 variables that are created by the project command.  Example languages
 are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``,
 ``HIP``, ``ISPC``, and ``ASM``.

Help/command/endblock.rst

@@ -0,0 +1,11 @@
+endblock
+--------
+
+.. versionadded:: 3.25
+
+Ends a list of commands in a :command:`block` and removes the scopes
+created by the :command:`block` command.
+
+.. code-block:: cmake
+
+  endblock()

Help/command/export.rst

@@ -25,7 +25,8 @@ Exporting Targets
 .. code-block:: cmake
 
   export(TARGETS <target>... [NAMESPACE <namespace>]
-         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
+         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
+         [CXX_MODULES_DIRECTORY <directory>])
 
 Creates a file ``<filename>`` that may be included by outside projects to
 import targets named by ``<target>...`` from the current project's build tree.
@@ -52,6 +53,16 @@ The options are:
   in the export, even when policy :policy:`CMP0022` is NEW.  This is useful
   to support consumers using CMake versions older than 2.8.12.
 
+``CXX_MODULES_DIRECTORY <directory>``
+
+  .. note ::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+
+  Export C++ module properties to files under the given directory. Each file
+  will be named according to the target's export name (without any namespace).
+  These files will automatically be included from the export file.
+
 This signature requires all targets to be listed explicitly.  If a library
 target is included in the export, but a target to which it links is not
 included, the behavior is unspecified.  See the `export(EXPORT)`_ signature
@@ -95,7 +106,8 @@ Exporting Targets matching install(EXPORT)
 
 .. code-block:: cmake
 
-  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
+  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
+         [CXX_MODULES_DIRECTORY <directory>])
 
 Creates a file ``<filename>`` that may be included by outside projects to
 import targets from the current project's build tree.  This is the same

Help/command/file.rst

@@ -1121,8 +1121,11 @@ Additional options to ``DOWNLOAD`` are:
 
   Verify that the downloaded content hash matches the expected value, where
   ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``.
-  If it does not match, the operation fails with an error. It is an error to
+  If the file already exists and matches the hash, the download is skipped.
-  specify this if ``DOWNLOAD`` is not given a ``<file>``.
+  If the file already exists and does not match the hash, the file is
+  downloaded again. If after download the file does not match the hash, the
+  operation fails with an error. It is an error to specify this option if
+  ``DOWNLOAD`` is not given a ``<file>``.
 
 ``EXPECTED_MD5 <value>``
   Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to

Help/command/find_package.rst

@@ -285,29 +285,40 @@ CMake constructs a set of possible installation prefixes for the
 package.  Under each prefix several directories are searched for a
 configuration file.  The tables below show the directories searched.
 Each entry is meant for installation trees following Windows (``W``), UNIX
-(``U``), or Apple (``A``) conventions::
+(``U``), or Apple (``A``) conventions:
 
-  <prefix>/                                                       (W)
+==================================================================== ==========
-  <prefix>/(cmake|CMake)/                                         (W)
+ Entry                                                               Convention
-  <prefix>/<name>*/                                               (W)
+==================================================================== ==========
-  <prefix>/<name>*/(cmake|CMake)/                                 (W)
+ ``<prefix>/``                                                          W
-  <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/                 (U)
+ ``<prefix>/(cmake|CMake)/``                                            W
-  <prefix>/(lib/<arch>|lib*|share)/<name>*/                       (U)
+ ``<prefix>/<name>*/``                                                  W
-  <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/         (U)
+ ``<prefix>/<name>*/(cmake|CMake)/``                                    W
-  <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/         (W/U)
+ ``<prefix>/<name>*/(cmake|CMake)/<name>*/`` [#]_                       W
-  <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/               (W/U)
+ ``<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/``                    U
-  <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
+ ``<prefix>/(lib/<arch>|lib*|share)/<name>*/``                          U
+ ``<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/``            U
+ ``<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/``            W/U
+ ``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/``                  W/U
+ ``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/``    W/U
+==================================================================== ==========
+
+.. [#] .. versionadded:: 3.25
 
 On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the
 following directories are searched for Frameworks or Application Bundles
-containing a configuration file::
+containing a configuration file:
 
-  <prefix>/<name>.framework/Resources/                    (A)
+=========================================================== ==========
-  <prefix>/<name>.framework/Resources/CMake/              (A)
+ Entry                                                      Convention
-  <prefix>/<name>.framework/Versions/*/Resources/         (A)
+=========================================================== ==========
-  <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
+ ``<prefix>/<name>.framework/Resources/``                      A
-  <prefix>/<name>.app/Contents/Resources/                 (A)
+ ``<prefix>/<name>.framework/Resources/CMake/``                A
-  <prefix>/<name>.app/Contents/Resources/CMake/           (A)
+ ``<prefix>/<name>.framework/Versions/*/Resources/``           A
+ ``<prefix>/<name>.framework/Versions/*/Resources/CMake/``     A
+ ``<prefix>/<name>.app/Contents/Resources/``                   A
+ ``<prefix>/<name>.app/Contents/Resources/CMake/``             A
+=========================================================== ==========
 
 In all cases the ``<name>`` is treated as case-insensitive and corresponds
 to any of the names specified (``<PackageName>`` or names given by ``NAMES``).
@@ -368,7 +379,7 @@ enabled.
     See policy :policy:`CMP0074`.
 
 2. Search paths specified in cmake-specific cache variables.  These
-   are intended to be used on the command line with a ``-DVAR=value``.
+   are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`.
    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``:

Help/command/foreach.rst

@@ -130,3 +130,11 @@ yields
   -- en=two, ba=dua
   -- en=three, ba=tiga
   -- en=four, ba=
+
+See Also
+^^^^^^^^
+
+* :command:`break`
+* :command:`continue`
+* :command:`endforeach`
+* :command:`while`

Help/command/function.rst

@@ -73,3 +73,9 @@ argument.  Referencing to ``ARGV#`` arguments beyond ``ARGC`` have
 undefined behavior.  Checking that ``ARGC`` is greater than ``#`` is
 the only way to ensure that ``ARGV#`` was passed to the function as an
 extra argument.
+
+See Also
+^^^^^^^^
+
+* :command:`endfunction`
+* :command:`return`

Help/command/get_test_property.rst

@@ -16,6 +16,7 @@ relevant parent scope as described for the :command:`define_property`
 command and if still unable to find the property, ``VAR`` will be set to
 an empty string.
 
-For a list of standard properties you can type ``cmake --help-property-list``.
+For a list of standard properties you can type
+:option:`cmake --help-property-list`.
 
 See also the more general :command:`get_property` command.

Help/command/if.rst

@@ -424,3 +424,10 @@ There is no automatic evaluation for environment or cache
 :ref:`Variable References`.  Their values must be referenced as
 ``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
 condition syntax accepts ``<variable|string>``.
+
+See also
+^^^^^^^^
+
+  * :command:`else`
+  * :command:`elseif`
+  * :command:`endif`

Help/command/install.rst

@@ -132,7 +132,7 @@ Installing Targets
   install(TARGETS targets... [EXPORT <export-name>]
           [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
           [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
-            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>]
+            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI]
            [DESTINATION <dir>]
            [PERMISSIONS permissions...]
            [CONFIGURATIONS [Debug|Release|...]]
@@ -215,11 +215,21 @@ that may be installed:
   ``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
   would be installed to ``myproj/here.h`` below the destination.
 
+``CXX_MODULES_BMI``
+
+  .. note ::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+
+  Any module files from C++ modules from ``PUBLIC`` sources in a file set of
+  type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All
+  modules are placed directly in the destination as no directory structure is
+  derived from the names of the modules. An empty ``DESTINATION`` may be used
+  to suppress installing these files (for use in generic code).
+
 For each of these arguments given, the arguments following them only apply
 to the target or file type specified in the argument. If none is given, the
-installation properties apply to all target types. If only one is given then
+installation properties apply to all target types.
-only targets of that type will be installed (which can be used to install
-just a DLL or just an import library.)
 
 For regular executables, static libraries and shared libraries, the
 ``DESTINATION`` argument is not required.  For these target types, when
@@ -233,6 +243,14 @@ Apple bundles and frameworks.  A destination can be omitted for interface and
 object libraries, but they are handled differently (see the discussion of this
 topic toward the end of this section).
 
+For shared libraries on DLL platforms, if neither ``RUNTIME`` nor ``ARCHIVE``
+destinations are specified, both the ``RUNTIME`` and ``ARCHIVE`` components are
+installed to their default destinations. If either a ``RUNTIME`` or ``ARCHIVE``
+destination is specified, the component is installed to that destination, and
+the other component is not installed. If both ``RUNTIME`` and ``ARCHIVE``
+destinations are specified, then both components are installed to their
+respective destinations.
+
 The following table shows the target types with their associated variables and
 built-in defaults that apply when no destination is given:
 
@@ -778,9 +796,10 @@ Installing Exports
 .. code-block:: cmake
 
   install(EXPORT <export-name> DESTINATION <dir>
-          [NAMESPACE <namespace>] [[FILE <name>.cmake]|
+          [NAMESPACE <namespace>] [FILE <name>.cmake]
           [PERMISSIONS permissions...]
-          [CONFIGURATIONS [Debug|Release|...]]
+          [CONFIGURATIONS [Debug|Release|...]
+          [CXX_MODULES_DIRECTORY <directory>]
           [EXPORT_LINK_INTERFACE_LIBRARIES]
           [COMPONENT <component>]
           [EXCLUDE_FROM_ALL])
@@ -836,6 +855,18 @@ library is always installed if the headers and CMake export file are present.
   to an ndk build system complete with transitive dependencies, include flags
   and defines required to use the libraries.
 
+``CXX_MODULES_DIRECTORY``
+
+  .. note ::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+
+  Specify a subdirectory to store C++ module information for targets in the
+  export set. This directory will be populated with files which add the
+  necessary target property information to the relevant targets. Note that
+  without this information, none of the C++ modules which are part of the
+  targets in the export set will support being imported in consuming targets.
+
 The ``EXPORT`` form is useful to help outside projects use targets built
 and installed by the current project.  For example, the code
 
@@ -932,12 +963,12 @@ Generated Installation Script
 .. note::
 
   Use of this feature is not recommended. Please consider using the
-  ``--install`` argument of :manual:`cmake(1)` instead.
+  :option:`cmake --install` 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
+and by CPack. You can also invoke this script manually with
-script accepts several variables:
+:option:`cmake -P`. This script accepts several variables:
 
 ``COMPONENT``
   Set this variable to install only a single CPack component as opposed to all

Help/command/message.rst

@@ -83,8 +83,9 @@ are sent to stderr and are not prefixed with hyphens.  The
 :manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area.
 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
+interactive pop-up box.  The :option:`--log-level <cmake --log-level>`
-these tools can be used to control which messages will be shown.
+command-line option to each of these tools can be used to control which
+messages will be shown.
 
 .. versionadded:: 3.17
   To make a log level persist between CMake runs, the
@@ -104,7 +105,7 @@ these tools can be used to control which messages will be shown.
   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``
+  enabled by giving the :option:`cmake --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.

Help/command/return.rst

@@ -5,16 +5,87 @@ Return from a file, directory or function.
 
 .. code-block:: cmake
 
-  return()
+  return([PROPAGATE <var-name>...])
 
-Returns from a file, directory or function.  When this command is
+When this command is encountered in an included file (via :command:`include` or
-encountered in an included file (via :command:`include` or
 :command:`find_package`), it causes processing of the current file to stop
 and control is returned to the including file.  If it is encountered in a
-file which is not included by another file, e.g.  a ``CMakeLists.txt``,
+file which is not included by another file, e.g. a ``CMakeLists.txt``,
 deferred calls scheduled by :command:`cmake_language(DEFER)` are invoked and
-control is returned to the parent directory if there is one.  If return is
+control is returned to the parent directory if there is one.
-called in a function, control is returned to the caller of the function.
 
-Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
+If ``return()`` is called in a function, control is returned to the caller
+of that function.  Note that a :command:`macro`, unlike a :command:`function`,
 is expanded in place and therefore cannot handle ``return()``.
+
+Policy :policy:`CMP0140` controls the behavior regarding the arguments of the
+command.  All arguments are ignored unless that policy is set to ``NEW``.
+
+``PROPAGATE``
+  .. versionadded:: 3.25
+
+  This option sets or unsets the specified variables in the parent directory or
+  function caller scope. This is equivalent to :command:`set(PARENT_SCOPE)` or
+  :command:`unset(PARENT_SCOPE)` commands, except for the way it interacts
+  with the :command:`block` command, as described below.
+
+  The ``PROPAGATE`` option can be very useful in conjunction with the
+  :command:`block` command.  A :command:`return` will propagate the
+  specified variables through any enclosing block scopes created by the
+  :command:`block` commands.  Inside a function, this ensures the variables
+  are propagated to the function's caller, regardless of any blocks within
+  the function.  If not inside a function, it ensures the variables are
+  propagated to the parent file or directory scope. For example:
+
+  .. code-block:: cmake
+    :caption: CMakeLists.txt
+
+    cmake_version_required(VERSION 3.25)
+    project(example)
+
+    set(var1 "top-value")
+
+    block(SCOPE_FOR VARIABLES)
+      add_subdirectory(subDir)
+      # var1 has the value "block-nested"
+    endblock()
+
+    # var1 has the value "top-value"
+
+  .. code-block:: cmake
+    :caption: subDir/CMakeLists.txt
+
+    function(multi_scopes result_var1 result_var2)
+      block(SCOPE_FOR VARIABLES)
+        # This would only propagate out of the immediate block, not to
+        # the caller of the function.
+        #set(${result_var1} "new-value" PARENT_SCOPE)
+        #unset(${result_var2} PARENT_SCOPE)
+
+        # This propagates the variables through the enclosing block and
+        # out to the caller of the function.
+        set(${result_var1} "new-value")
+        unset(${result_var2})
+        return(PROPAGATE ${result_var1} ${result_var2})
+      endblock()
+    endfunction()
+
+    set(var1 "some-value")
+    set(var2 "another-value")
+
+    multi_scopes(var1 var2)
+    # Now var1 will hold "new-value" and var2 will be unset
+
+    block(SCOPE_FOR VARIABLES)
+      # This return() will set var1 in the directory scope that included us
+      # via add_subdirectory(). The surrounding block() here does not limit
+      # propagation to the current file, but the block() in the parent
+      # directory scope does prevent propagation going any further.
+      set(var1 "block-nested")
+      return(PROPAGATE var1)
+    endblock()
+
+See Also
+^^^^^^^^
+
+  * :command:`block`

Help/command/set.rst

@@ -22,12 +22,17 @@ Set Normal Variable
 Sets the given ``<variable>`` in the current function or directory scope.
 
 If the ``PARENT_SCOPE`` option is given the variable will be set in
-the scope above the current scope.  Each new directory or function
+the scope above the current scope.  Each new directory or :command:`function`
-creates a new scope.  This command will set the value of a variable
+command creates a new scope.  A scope can also be created with the
-into the parent directory or calling function (whichever is applicable
+:command:`block` command. This command will set the value of a variable into
-to the case at hand). The previous state of the variable's value stays the
+the parent directory, calling function or encompassing scope (whichever is
-same in the current scope (e.g., if it was undefined before, it is still
+applicable to the case at hand). The previous state of the variable's value
-undefined and if it had a value, it is still that value).
+stays the same in the current scope (e.g., if it was undefined before, it is
+still undefined and if it had a value, it is still that value).
+
+The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can
+be used as an alternate method to the :command:`set(PARENT_SCOPE)` and
+:command:`unset(PARENT_SCOPE)` commands to update the parent scope.
 
 Set Cache Entry
 ^^^^^^^^^^^^^^^
@@ -78,7 +83,7 @@ option is given then the cache entry will be set to the given value.
 
 It is possible for the cache entry to exist prior to the call but
 have no type set if it was created on the :manual:`cmake(1)` command
-line by a user through the ``-D<var>=<value>`` option without
+line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option without
 specifying a type.  In this case the ``set`` command will add the
 type.  Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
 and the ``<value>`` provided on the command line is a relative path,

Help/command/target_compile_definitions.rst

@@ -15,9 +15,9 @@ named ``<target>`` must have been created by a command such as
 :ref:`ALIAS target <Alias Targets>`.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
+specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
-items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of
+``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS`
-``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
+property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``.
 The following arguments specify compile definitions.  Repeated calls for the
 same ``<target>`` append items in the order called.

Help/command/target_compile_options.rst

@@ -22,9 +22,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property
 instead of being appended.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
+specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
-items will populate the :prop_tgt:`COMPILE_OPTIONS` property of
+``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS`
-``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
+property of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``.
 The following arguments specify compile options.  Repeated calls for the same
 ``<target>`` append items in the order called.

Help/command/target_include_directories.rst

@@ -18,9 +18,9 @@ By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending
 and prepending, independent of the default.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
-the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC`` items will
+the :ref:`scope <Target Usage Requirements>` of the following arguments.
-populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``.
+``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES`
-``PUBLIC`` and ``INTERFACE`` items will populate the
+property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.
 The following arguments specify include directories.
 

Help/command/target_link_directories.rst

@@ -21,11 +21,12 @@ The named ``<target>`` must have been created by a command such as
 :ref:`ALIAS target <Alias Targets>`.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the items that follow them.  ``PRIVATE`` and
+specify the :ref:`scope <Target Usage Requirements>` of the items that follow
-``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property
+them. ``PRIVATE`` and ``PUBLIC`` items will populate the
-of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
+:prop_tgt:`LINK_DIRECTORIES` property of ``<target>``.  ``PUBLIC`` and
-:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>``
+``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
-(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
+property of ``<target>`` (:ref:`IMPORTED targets <Imported Targets>` only
+support ``INTERFACE`` items).
 Each item specifies a link directory and will be converted to an absolute
 path if necessary before adding it to the relevant property.  Repeated
 calls for the same ``<target>`` append items in the order called.

Help/command/target_link_libraries.rst

@@ -146,8 +146,10 @@ Libraries for a Target and/or its Dependents
                         <PRIVATE|PUBLIC|INTERFACE> <item>...
                        [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
 
-The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
+The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
+:ref:`scope <Target Usage Requirements>` keywords can be used to
 specify both the link dependencies and the link interface in one command.
+
 Libraries and targets following ``PUBLIC`` are linked to, and are made
 part of the link interface.  Libraries and targets following ``PRIVATE``
 are linked to, but are not made part of the link interface.  Libraries

Help/command/target_link_options.rst

@@ -32,9 +32,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property
 instead of being appended.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
+specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
-items will populate the :prop_tgt:`LINK_OPTIONS` property of
+``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS`
-``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
+property of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.
 The following arguments specify link options.  Repeated calls for the same
 ``<target>`` append items in the order called.

Help/command/target_precompile_headers.rst

@@ -25,9 +25,9 @@ The named ``<target>`` must have been created by a command such as
 :ref:`ALIAS target <Alias Targets>`.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
+specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
-items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of
+``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS`
-``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
+property of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``
 (:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
 Repeated calls for the same ``<target>`` will append items in the order called.

Help/command/target_sources.rst

@@ -22,10 +22,10 @@ The named ``<target>`` must have been created by a command such as
   ``<target>`` can be a custom target.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the source file paths (``<items>``) that follow
+specify the :ref:`scope <Target Usage Requirements>` of the source file paths
-them.  ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES`
+(``<items>``) that follow them.  ``PRIVATE`` and ``PUBLIC`` items will
-property of ``<target>``, which are used when building the target itself.
+populate the :prop_tgt:`SOURCES` property of ``<target>``, which are used when
-``PUBLIC`` and ``INTERFACE`` items will populate the
+building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
 when building dependents.  A target created by :command:`add_custom_target`
 can only have ``PRIVATE`` scope.
@@ -75,9 +75,33 @@ File Sets
 Adds a file set to a target, or adds files to an existing file set. Targets
 have zero or more named file sets. Each file set has a name, a type, a scope of
 ``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and
-files within those directories. The only acceptable type is ``HEADERS``. The
+files within those directories. The acceptable types include:
-optional default file sets are named after their type. The target may not be a
+
-custom target or :prop_tgt:`FRAMEWORK` target.
+``HEADERS``
+
+  Sources intended to be used via a language's ``#include`` mechanism.
+
+``CXX_MODULES``
+
+  .. note ::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+
+  Sources which contain C++ interface module or partition units (i.e., those
+  using the ``export`` keyword). This file set type may not have an
+  ``INTERFACE`` scope except on ``IMPORTED`` targets.
+
+``CXX_MODULE_HEADER_UNITS``
+
+  .. note ::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+
+  C++ header sources which may be imported by other C++ source code. This file
+  set type may not have an ``INTERFACE`` scope except on ``IMPORTED`` targets.
+
+The optional default file sets are named after their type. The target may not
+be a custom target or :prop_tgt:`FRAMEWORK` target.
 
 Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
 the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets
@@ -93,16 +117,17 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o
 
   The name of the file set to create or add to. It must contain only letters,
   numbers and underscores. Names starting with a capital letter are reserved
-  for built-in file sets predefined by CMake. The only predefined set name is
+  for built-in file sets predefined by CMake. The only predefined set names
-  ``HEADERS``. All other set names must not start with a capital letter or
+  are those matching the acceptable types. All other set names must not start
+  with a capital letter or
   underscore.
 
 ``TYPE <type>``
 
-  Every file set is associated with a particular type of file. ``HEADERS``
+  Every file set is associated with a particular type of file. Only types
-  is currently the only defined type and it is an error to specify anything
+  specified above may be used and it is an error to specify anything else. As
-  else. As a special case, if the name of the file set is ``HEADERS``, the
+  a special case, if the name of the file set is one of the types, the type
-  type does not need to be specified and the ``TYPE <type>`` arguments can be
+  does not need to be specified and the ``TYPE <type>`` arguments can be
   omitted. For all other file set names, ``TYPE`` is required.
 
 ``BASE_DIRS <dirs>...``
@@ -134,6 +159,8 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o
 The following target properties are set by ``target_sources(FILE_SET)``,
 but they should not generally be manipulated directly:
 
+For file sets of type ``HEADERS``:
+
 * :prop_tgt:`HEADER_SETS`
 * :prop_tgt:`INTERFACE_HEADER_SETS`
 * :prop_tgt:`HEADER_SET`
@@ -141,17 +168,37 @@ but they should not generally be manipulated directly:
 * :prop_tgt:`HEADER_DIRS`
 * :prop_tgt:`HEADER_DIRS_<NAME>`
 
+For file sets of type ``CXX_MODULES``:
+
+* :prop_tgt:`CXX_MODULE_SETS`
+* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
+* :prop_tgt:`CXX_MODULE_SET`
+* :prop_tgt:`CXX_MODULE_SET_<NAME>`
+* :prop_tgt:`CXX_MODULE_DIRS`
+* :prop_tgt:`CXX_MODULE_DIRS_<NAME>`
+
+For file sets of type ``CXX_MODULE_HEADER_UNITS``:
+
+* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SETS`
+* :prop_tgt:`INTERFACE_CXX_MODULE_HEADER_UNIT_SETS`
+* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET`
+* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET_<NAME>`
+* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS`
+* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS_<NAME>`
+
 Target properties related to include directories are also modified by
 ``target_sources(FILE_SET)`` as follows:
 
 :prop_tgt:`INCLUDE_DIRECTORIES`
 
-  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE``
+  If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope
-  or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in
+  of the file set is ``PRIVATE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of
-  :genex:`$<BUILD_INTERFACE>` and appended to this property.
+  the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this
+  property.
 
 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
 
-  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is
+  If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope
-  ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are
+  of the file set is ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of
-  wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property.
+  the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this
+  property.

Help/command/try_compile.rst

@@ -14,10 +14,16 @@ Try Compiling Whole Projects
 
 .. code-block:: cmake
 
-  try_compile(<resultVar> <bindir> <srcdir>
+  try_compile(<resultVar> PROJECT <projectName>
-              <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
+              SOURCE_DIR <srcdir>
+              [BINARY_DIR <bindir>]
+              [TARGET <targetName>]
+              [NO_CACHE]
+              [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
 
+.. versionadded:: 3.25
+
 Try building a project.  The success or failure of the ``try_compile``,
 i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
 
@@ -34,6 +40,17 @@ below for the meaning of other options.
   Previously this was only done by the
   :ref:`source file <Try Compiling Source Files>` signature.
 
+This command also supports an alternate signature
+which was present in older versions of CMake:
+
+.. code-block:: cmake
+
+  try_compile(<resultVar> <bindir> <srcdir>
+              <projectName> [<targetName>]
+              [NO_CACHE]
+              [CMAKE_FLAGS <flags>...]
+              [OUTPUT_VARIABLE <var>])
+
 .. _`Try Compiling Source Files`:
 
 Try Compiling Source Files
@@ -41,7 +58,12 @@ Try Compiling Source Files
 
 .. code-block:: cmake
 
-  try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
+  try_compile(<resultVar>
+              <SOURCES <srcfile...>                 |
+               SOURCE_FROM_CONTENT <name> <content> |
+               SOURCE_FROM_VAR <name> <var>         |
+               SOURCE_FROM_FILE <name> <path>       >...
+              [NO_CACHE]
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
               [LINK_OPTIONS <options>...]
@@ -53,15 +75,19 @@ Try Compiling Source Files
               [<LANG>_EXTENSIONS <bool>]
               )
 
+.. versionadded:: 3.25
+
 Try building an executable or static library from one or more source files
 (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
 variable).  The success or failure of the ``try_compile``, i.e. ``TRUE`` or
 ``FALSE`` respectively, is returned in ``<resultVar>``.
 
-In this form, one or more source files must be provided.  If
+In this form, one or more source files must be provided. Additionally, one of
-:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``,
+``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords.
-the sources must include a definition for ``main`` and CMake will create a
+
-``CMakeLists.txt`` file to build the source(s) as an executable.
+If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to
+``EXECUTABLE``, the sources must include a definition for ``main`` and CMake
+will create a ``CMakeLists.txt`` file to build the source(s) as an executable.
 If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``,
 a static library will be built instead and no definition for ``main`` is
 required.  For an executable, the generated ``CMakeLists.txt`` file would
@@ -76,11 +102,45 @@ contain something like the following:
   target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
   target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
 
+CMake automatically generates, for each ``try_compile`` operation, a
+unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch``
+with an unspecified name.  These directories are cleaned automatically unless
+:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``.
+Such directories from previous runs are also unconditionally cleaned at the
+beginning of any ``cmake`` execution.
+
+This command also supports an alternate signature
+which was present in older versions of CMake:
+
+.. code-block:: cmake
+
+  try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
+              [NO_CACHE]
+              [CMAKE_FLAGS <flags>...]
+              [COMPILE_DEFINITIONS <defs>...]
+              [LINK_OPTIONS <options>...]
+              [LINK_LIBRARIES <libs>...]
+              [OUTPUT_VARIABLE <var>]
+              [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
+              [<LANG>_STANDARD <std>]
+              [<LANG>_STANDARD_REQUIRED <bool>]
+              [<LANG>_EXTENSIONS <bool>]
+              )
+
+In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
+its operation, and all such files will be cleaned automatically.
+For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
+passed to ``cmake`` to avoid this clean.  However, multiple sequential
+``try_compile`` operations, if given the same ``<bindir>``, will reuse this
+single output directory, such that you can only debug one such ``try_compile``
+call at a time.  Use of the newer signature is recommended to simplify
+debugging of multiple ``try_compile`` operations.
+
 The options are:
 
 ``CMAKE_FLAGS <flags>...``
-  Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
+  Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
-  the ``cmake`` command-line used to drive the test build.
+  to the :manual:`cmake(1)` command-line used to drive the test build.
   The above example shows how values for variables
   ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
   are used.
@@ -111,9 +171,61 @@ The options are:
   set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
   project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
 
+``NO_CACHE``
+  .. versionadded:: 3.25
+
+  The result will be stored in a normal variable rather than a cache entry.
+
+  The result variable is normally cached so that a simple pattern can be used
+  to avoid repeating the test on subsequent executions of CMake:
+
+  .. code-block:: cmake
+
+    if(NOT DEFINED RESULTVAR)
+      # ...(check-specific setup code)...
+      try_compile(RESULTVAR ...)
+      # ...(check-specific logging and cleanup code)...
+    endif()
+
+  If the guard variable and result variable are not the same (for example, if
+  the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid
+  leaking the intermediate result variable into the cache.
+
 ``OUTPUT_VARIABLE <var>``
   Store the output from the build process in the given variable.
 
+``SOURCE_FROM_CONTENT <name> <content>``
+  .. versionadded:: 3.25
+
+  Write ``<content>`` to a file named ``<name>`` in the operation directory.
+  This can be used to bypass the need to separately write a source file when
+  the contents of the file are dynamically specified. The specified ``<name>``
+  is not allowed to contain path components.
+
+  ``SOURCE_FROM_CONTENT`` may be specified multiple times.
+
+``SOURCE_FROM_FILE <name> <path>``
+  .. versionadded:: 3.25
+
+  Copy ``<path>`` to a file named ``<name>`` in the operation directory. This
+  can be used to consolidate files into the operation directory, which may be
+  useful if a source which already exists (i.e. as a stand-alone file in a
+  project's source repository) needs to refer to other file(s) created by
+  ``SOURCE_FROM_*``. (Otherwise, ``SOURCES`` is usually more convenient.) The
+  specified ``<name>`` is not allowed to contain path components.
+
+``SOURCE_FROM_VAR <name> <var>``
+  .. versionadded:: 3.25
+
+  Write the contents of ``<var>`` to a file named ``<name>`` in the operation
+  directory. This is the same as ``SOURCE_FROM_CONTENT``, but takes the
+  contents from the specified CMake variable, rather than directly, which may
+  be useful when passing arguments through a function which wraps
+  ``try_compile``. The specified ``<name>`` is not allowed to contain path
+  components.
+
+  ``SOURCE_FROM_VAR`` may be specified multiple times.
+
 ``<LANG>_STANDARD <std>``
   .. versionadded:: 3.8
 
@@ -136,17 +248,6 @@ The options are:
   :prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`,
   or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.
 
-In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
-cleaned automatically.  For debugging, ``--debug-trycompile`` can be
-passed to ``cmake`` to avoid this clean.  However, multiple sequential
-``try_compile`` operations reuse this single output directory.  If you use
-``--debug-trycompile``, you can only debug one ``try_compile`` call at a time.
-The recommended procedure is to protect all ``try_compile`` calls in your
-project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake
-all the way through once, then delete the cache entry associated with
-the try_compile call of interest, and then re-run cmake again with
-``--debug-trycompile``.
-
 Other Behavior Settings
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -214,9 +315,15 @@ a build configuration.
   the generated project (unless overridden by an explicit option).
 
 .. versionchanged:: 3.14
-  For the :generator:`Green Hills MULTI` generator the GHS toolset and target
+  For the :generator:`Green Hills MULTI` generator, the GHS toolset and target
-  system customization cache variables are also propagated into the test project.
+  system customization cache variables are also propagated into the test
+  project.
 
 .. versionadded:: 3.24
   The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be
   set to disable passing platform variables into the test project.
+
+.. versionadded:: 3.25
+  If :policy:`CMP0141` is set to ``NEW``, one can use
+  :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
+  information format.

Help/command/try_run.rst

@@ -13,68 +13,99 @@ Try Compiling and Running Source Files
 .. code-block:: cmake
 
   try_run(<runResultVar> <compileResultVar>
-          <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
+          <SOURCES <srcfile...>                 |
+           SOURCE_FROM_CONTENT <name> <content> |
+           SOURCE_FROM_VAR <name> <var>         |
+           SOURCE_FROM_FILE <name> <path>       >...
+          [NO_CACHE]
+          [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
           [LINK_OPTIONS <options>...]
           [LINK_LIBRARIES <libs>...]
           [COMPILE_OUTPUT_VARIABLE <var>]
+          [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
+          [<LANG>_STANDARD <std>]
+          [<LANG>_STANDARD_REQUIRED <bool>]
+          [<LANG>_EXTENSIONS <bool>]
           [RUN_OUTPUT_VARIABLE <var>]
+          [RUN_OUTPUT_STDOUT_VARIABLE <var>]
+          [RUN_OUTPUT_STDERR_VARIABLE <var>]
           [OUTPUT_VARIABLE <var>]
           [WORKING_DIRECTORY <var>]
-          [ARGS <args>...])
+          [ARGS <args>...]
+          )
+
+.. versionadded:: 3.25
 
 Try compiling a ``<srcfile>``.  Returns ``TRUE`` or ``FALSE`` for success
 or failure in ``<compileResultVar>``.  If the compile succeeded, runs the
 executable and returns its exit code in ``<runResultVar>``.  If the
 executable was built, but failed to run, then ``<runResultVar>`` will be
 set to ``FAILED_TO_RUN``.  See the :command:`try_compile` command for
-information on how the test project is constructed to build the source file.
+documentation of options common to both commands, and for information on how
+the test project is constructed to build the source file.
 
-The options are:
+One or more source files must be provided. Additionally, one of ``SOURCES``
+and/or ``SOURCE_FROM_*`` must precede other keywords.
 
-``CMAKE_FLAGS <flags>...``
+This command also supports an alternate signature
-  Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
+which was present in older versions of CMake:
-  the ``cmake`` command-line used to drive the test build.
-  The example in :command:`try_compile` shows how values for variables
-  ``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
-  are used.
 
-``COMPILE_DEFINITIONS <defs>...``
+.. code-block:: cmake
-  Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
+
-  in the generated test project.
+  try_run(<runResultVar> <compileResultVar>
+          <bindir> <srcfile|SOURCES srcfile...>
+          [NO_CACHE]
+          [CMAKE_FLAGS <flags>...]
+          [COMPILE_DEFINITIONS <defs>...]
+          [LINK_OPTIONS <options>...]
+          [LINK_LIBRARIES <libs>...]
+          [COMPILE_OUTPUT_VARIABLE <var>]
+          [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
+          [<LANG>_STANDARD <std>]
+          [<LANG>_STANDARD_REQUIRED <bool>]
+          [<LANG>_EXTENSIONS <bool>]
+          [RUN_OUTPUT_VARIABLE <var>]
+          [RUN_OUTPUT_STDOUT_VARIABLE <var>]
+          [RUN_OUTPUT_STDERR_VARIABLE <var>]
+          [OUTPUT_VARIABLE <var>]
+          [WORKING_DIRECTORY <var>]
+          [ARGS <args>...]
+          )
+
+The options specific to ``try_run`` are:
 
 ``COMPILE_OUTPUT_VARIABLE <var>``
   Report the compile step build output in a given variable.
 
-``LINK_LIBRARIES <libs>...``
-  .. versionadded:: 3.2
-
-  Specify libraries to be linked in the generated project.
-  The list of libraries may refer to system libraries and to
-  :ref:`Imported Targets <Imported Targets>` from the calling project.
-
-  If this option is specified, any ``-DLINK_LIBRARIES=...`` value
-  given to the ``CMAKE_FLAGS`` option will be ignored.
-
-``LINK_OPTIONS <options>...``
-  .. versionadded:: 3.14
-
-  Specify link step options to pass to :command:`target_link_options` in the
-  generated project.
-
 ``OUTPUT_VARIABLE <var>``
   Report the compile build output and the output from running the executable
-  in the given variable.  This option exists for legacy reasons.  Prefer
+  in the given variable.  This option exists for legacy reasons and is only
-  ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
+  supported by the old ``try_run`` signature.
+  Prefer ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
 
 ``RUN_OUTPUT_VARIABLE <var>``
   Report the output from running the executable in a given variable.
 
+``RUN_OUTPUT_STDOUT_VARIABLE <var>``
+  .. versionadded:: 3.25
+
+  Report the output of stdout from running the executable in a given variable.
+
+``RUN_OUTPUT_STDERR_VARIABLE <var>``
+  .. versionadded:: 3.25
+
+  Report the output of stderr from running the executable in a given variable.
+
 ``WORKING_DIRECTORY <var>``
   .. versionadded:: 3.20
 
   Run the executable in the given directory. If no ``WORKING_DIRECTORY`` is
-  specified, the executable will run in ``<bindir>``.
+  specified, the executable will run in ``<bindir>`` or the current build
+  directory.
+
+``ARGS <args>...``
+  Additional arguments to pass to the executable when running it.
 
 Other Behavior Settings
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -110,6 +141,7 @@ These cache entries are:
 
 In order to make cross compiling your project easier, use ``try_run``
 only if really required.  If you use ``try_run``, use the
+``RUN_OUTPUT_STDOUT_VARIABLE``, ``RUN_OUTPUT_STDERR_VARIABLE``,
 ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really
 required.  Using them will require that when cross-compiling, the cache
 variables will have to be set manually to the output of the executable.

Help/command/while.rst

@@ -23,3 +23,11 @@ Per legacy, the :command:`endwhile` command admits
 an optional ``<condition>`` argument.
 If used, it must be a verbatim repeat of the argument of the opening
 ``while`` command.
+
+See Also
+^^^^^^^^
+
+  * :command:`break`
+  * :command:`continue`
+  * :command:`foreach`
+  * :command:`endwhile`

Help/cpack_gen/archive.rst

@@ -57,6 +57,12 @@ Variables specific to CPack Archive generator
   .. versionadded:: 3.9
     Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables.
 
+.. variable:: CPACK_ARCHIVE_FILE_EXTENSION
+
+  .. versionadded:: 3.25
+
+  Package file extension. Default values are given in the list above.
+
 .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
 
   Enable component packaging. If enabled (ON), then the archive generator

Help/cpack_gen/deb.rst

@@ -57,7 +57,7 @@ List of CPack DEB generator specific variables:
  .. versionadded:: 3.5
   Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME`` variables.
 
- See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
+ See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
 
 .. variable:: CPACK_DEBIAN_FILE_NAME
               CPACK_DEBIAN_<COMPONENT>_FILE_NAME
@@ -399,7 +399,7 @@ List of CPack DEB generator specific variables:
  .. versionadded:: 3.4
   Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`` variables.
 
- See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
+ See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES
@@ -419,7 +419,7 @@ List of CPack DEB generator specific variables:
  .. versionadded:: 3.4
   Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`` variables.
 
- See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
+ See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_BREAKS
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS
@@ -508,7 +508,7 @@ List of CPack DEB generator specific variables:
  .. versionadded:: 3.4
   Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`` variables.
 
- See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
+ See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS
@@ -527,7 +527,7 @@ List of CPack DEB generator specific variables:
  .. versionadded:: 3.4
   Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`` variables.
 
- See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
+ See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS
@@ -545,7 +545,7 @@ List of CPack DEB generator specific variables:
  .. versionadded:: 3.4
   Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`` variables.
 
- See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
+ See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS
 
@@ -639,7 +639,7 @@ List of CPack DEB generator specific variables:
    - :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based
      installations.
 
- See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
+ See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
 
  .. note::
 

Help/cpack_gen/external.rst

@@ -207,8 +207,8 @@ following fields in the root:
   set.
 
 ``buildConfig``
-  The build configuration given to CPack with the ``-C`` option. Only present
+  The build configuration given to CPack with the :option:`cpack -C` option.
-  if this option is set.
+  Only present if this option is set.
 
 ``defaultDirectoryPermissions``
   The default directory permissions given in

Help/cpack_gen/freebsd.rst

@@ -62,8 +62,6 @@ the RPM information (e.g. package license).
 
     - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
       by CPack itself, if nothing else sets it explicitly).
-    - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION
-      parameter for :command:`project`).
 
 .. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION
 
@@ -75,6 +73,10 @@ the RPM information (e.g. package license).
 
     - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already
       for Debian packaging, so it is used as a fallback).
+    - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
+      by CPack itself, if nothing else sets it explicitly).
+    - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION
+      parameter for :command:`project`).
 
 .. variable:: CPACK_FREEBSD_PACKAGE_WWW
 
@@ -85,12 +87,12 @@ the RPM information (e.g. package license).
   * Mandatory: YES
   * Default:
 
-   - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set,
+   - :variable:`CPACK_PACKAGE_HOMEPAGE_URL`, or if that is not set,
-     :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already
+   - :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already
      for Debian packaging, so it is used as a fallback).
 
   .. versionadded:: 3.12
-    The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
+    The ``CPACK_PACKAGE_HOMEPAGE_URL`` variable.
 
 .. variable:: CPACK_FREEBSD_PACKAGE_LICENSE
 

Help/cpack_gen/ifw.rst

@@ -14,7 +14,7 @@ Overview
 
 This :manual:`cpack generator <cpack-generators(7)>` generates
 configuration and meta information for the `Qt Installer Framework
-<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
+<https://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
 and runs QtIFW tools to generate a Qt installer.
 
 QtIFW provides tools and utilities to create installers for

Help/cpack_gen/nsis.rst

@@ -207,3 +207,34 @@ on Windows Nullsoft Scriptable Install System.
  .. versionadded:: 3.22
 
  If set, do not display the page containing the license during installation.
+
+.. variable:: CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS
+
+ .. versionadded:: 3.25
+
+ This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
+ arguments to prepend to the nsis script to run.
+ If the arguments do not start with a ``/`` or a ``-``, it will add one
+ automatically to the corresponding arguments.
+ The command that will be run is::
+
+    makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...
+
+ where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
+ and ``<postArgs>...``  is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.
+
+
+.. variable:: CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS
+
+ .. versionadded:: 3.25
+
+ This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
+ arguments to append to the nsis script to run.
+ If the arguments do not start with a ``/`` or a ``-``, it will add one
+ automatically to the corresponding arguments.
+ The command that will be run is::
+
+    makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...
+
+ where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
+ and ``<postArgs>...``  is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.

Help/cpack_gen/nuget.rst

@@ -110,7 +110,7 @@ List of CPack NuGet generator specific variables:
  .. deprecated:: 3.20
   Use a local license file
   (:variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`)
-  or a `(SPDX) license identifier`_
+  or a `SPDX license identifier`_
   (:variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`) instead.
 
  An URL for the package's license, often shown in UI displays as well
@@ -124,7 +124,7 @@ List of CPack NuGet generator specific variables:
 
  .. versionadded:: 3.20
 
- A Software Package Data Exchange `(SPDX) license identifier`_ such as
+ A Software Package Data Exchange `SPDX license identifier`_ such as
  ``MIT``, ``BSD-3-Clause``, or ``LGPL-3.0-or-later``. In the case of a
  choice of licenses or more complex restrictions, compound license
  expressions may be formed using boolean operators, for example
@@ -162,6 +162,14 @@ List of CPack NuGet generator specific variables:
  * Mandatory : NO
  * Default   : -
 
+.. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE
+
+ When set to a true value, the user will be prompted to accept the license
+ before installing the package.
+
+ * Mandatory : NO
+ * Default   : -
+
 .. variable:: CPACK_NUGET_PACKAGE_ICON
               CPACK_NUGET_<compName>_PACKAGE_ICON
 
@@ -247,9 +255,9 @@ List of CPack NuGet generator specific variables:
  * Default   : OFF
 
 
-.. _nuget.org: http://nuget.org
+.. _nuget.org: https://www.nuget.org
-.. _version specification: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards
+.. _version specification: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges
-.. _(SPDX) license identifier: https://spdx.org/licenses/
+.. _SPDX license identifier: https://spdx.github.io/spdx-spec/SPDX-license-list
-.. _SPDX specification: https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/
+.. _SPDX specification: https://spdx.github.io/spdx-spec/SPDX-license-expressions
 
 .. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec

Help/cpack_gen/rpm.rst

@@ -18,7 +18,7 @@ The CPack RPM generator has specific features which are controlled by the specif
 **grouping name** written in upper case. It may be either a component name or
 a component GROUP name. Usually those variables correspond to RPM spec file
 entities. One may find information about spec files here
-http://www.rpm.org/wiki/Docs
+https://rpm.org/documentation
 
 .. versionchanged:: 3.6
 
@@ -972,7 +972,7 @@ For CMake projects SRPM package would be produced by executing::
  Produced SRPM package is expected to be built with :manual:`cmake(1)` executable
  and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be
  located in root source directory and must be able to generate binary rpm
- packages by executing ``cpack -G`` command. The two executables as well as
+ packages by executing :option:`cpack -G` command. The two executables as well as
  rpmbuild must also be present when generating binary rpm packages from the
  produced SRPM package.
 

Help/cpack_gen/wix.rst

@@ -111,7 +111,7 @@ Windows using WiX.
  simply provide the name of the culture.  If you specify more than one
  culture identifier in a comma or semicolon delimited list, the first one
  that is found will be used.  You can find a list of supported languages at:
- http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm
+ https://wixtoolset.org//documentation/manual/v3/wixui/wixui_localization.html
 
 .. variable:: CPACK_WIX_TEMPLATE
 

Help/dev/experimental.rst

@@ -7,6 +7,23 @@ See documentation on `CMake Development`_ for more information.
 
 .. _`CMake Development`: README.rst
 
+Features are gated behind ``CMAKE_EXPERIMENTAL_`` variables which must be set
+to specific values in order to enable their gated behaviors. Note that the
+specific values will change over time to reinforce their experimental nature.
+When used, a warning will be generated to indicate that an experimental
+feature is in use and that the affected behavior in the project is not part of
+CMake's stability guarantees.
+
+C++20 Module APIs
+=================
+
+Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+Value: ``3c375311-a3c9-4396-a187-3227ef642046``
+
+In order to support C++20 modules, there are a number of behaviors that have
+CMake APIs to provide the required features to build and export them from a
+project.
+
 C++20 Module Dependencies
 =========================
 
@@ -22,6 +39,10 @@ they can use it to develop and test their dependency scanning tool.
 The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` variable must also be set
 to tell CMake how to invoke the C++20 module dependency scanning tool.
 
+MSVC 19.34 (provided with Visual Studio 17.4) and above contains the support
+that CMake needs and has these variables already set up as required and only
+the UUID variable needs to be set.
+
 For example, add code like the following to a test project:
 
 .. code-block:: cmake
@@ -40,13 +61,8 @@ dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
 ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
 for scandep rules which use ``msvc``-style dependency reporting.
 
-For tools which need to know the file set the source belongs to, the
-``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may
-be provided so that different source types can be distinguished prior to
-scanning.
-
 The module dependencies should be written in the format described
-by the `P1689r4`_ paper.
+by the `P1689r5`_ paper.
 
 Compiler writers may try out their scanning functionality using
 the `cxx-modules-sandbox`_ test project, modified to set variables
@@ -73,5 +89,5 @@ the GCC documentation, but the relevant section for the purposes of CMake is:
     -- GCC module mapper documentation
 
 .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html
-.. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html
+.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html
 .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox

Help/envvar/ASM_DIALECTFLAGS.rst

@@ -3,13 +3,16 @@ ASM<DIALECT>FLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling a specific dialect of an
+Add default compilation flags to be used when compiling a specific dialect
-assembly language. ``ASM<DIALECT>FLAGS`` can be ``ASMFLAGS``, ``ASM_NASMFLAGS``,
+of an assembly language.  ``ASM<DIALECT>FLAGS`` can be one of:
-``ASM_MASMFLAGS`` or ``ASM-ATTFLAGS``. Will only be used by CMake on the
+
-first configuration to determine ``ASM_<DIALECT>`` default compilation
+* ``ASMFLAGS``
-flags, after which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache
+* ``ASM_NASMFLAGS``
-as ``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>``.  For any configuration
+* ``ASM_MASMFLAGS``
-run (including the first), the environment variable will be ignored, if the
+* ``ASM-ATTFLAGS``
-``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`` variable is defined.
+
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`
+.. |LANG| replace:: ``ASM<DIALECT>``
+.. include:: LANG_FLAGS.txt
 
 See also :variable:`CMAKE_ASM<DIALECT>_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/CFLAGS.rst

@@ -3,11 +3,10 @@ CFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``C`` files. Will only be
+Add default compilation flags to be used when compiling ``C`` files.
-used by CMake on the first configuration to determine ``CC`` default compilation
+
-flags, after which the value for ``CFLAGS`` is stored in the cache
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`
-as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run
+.. |LANG| replace:: ``C``
-(including the first), the environment variable will be ignored if the
+.. include:: LANG_FLAGS.txt
-:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
 
 See also :variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/CMAKE_GENERATOR.rst

@@ -6,9 +6,9 @@ CMAKE_GENERATOR
 .. include:: ENV_VAR.txt
 
 Specifies the CMake default generator to use when no generator is supplied
-with ``-G``. If the provided value doesn't name a generator known by CMake,
+with :option:`-G <cmake -G>`. If the provided value doesn't name a generator
-the internal default is used.  Either way the resulting generator selection
+known by CMake, the internal default is used.  Either way the resulting
-is stored in the :variable:`CMAKE_GENERATOR` variable.
+generator selection is stored in the :variable:`CMAKE_GENERATOR` variable.
 
 Some generators may be additionally configured using the environment
 variables:

Help/envvar/CMAKE_GENERATOR_PLATFORM.rst

@@ -6,5 +6,5 @@ CMAKE_GENERATOR_PLATFORM
 .. include:: ENV_VAR.txt
 
 Default value for :variable:`CMAKE_GENERATOR_PLATFORM` if no Cache entry
-is present and no value is specified by :manual:`cmake(1)` ``-A`` option.
+is present and no value is specified by :option:`cmake -A` option.
 This value is only applied if :envvar:`CMAKE_GENERATOR` is set.

Help/envvar/CMAKE_GENERATOR_TOOLSET.rst

@@ -6,5 +6,5 @@ CMAKE_GENERATOR_TOOLSET
 .. include:: ENV_VAR.txt
 
 Default value for :variable:`CMAKE_GENERATOR_TOOLSET` if no Cache entry
-is present and no value is specified by :manual:`cmake(1)` ``-T`` option.
+is present and no value is specified by :option:`cmake -T` option.
 This value is only applied if :envvar:`CMAKE_GENERATOR` is set.

Help/envvar/CSFLAGS.rst

@@ -5,11 +5,10 @@ CSFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``CSharp`` files. Will only be
+Add default compilation flags to be used when compiling ``CSharp`` files.
-used by CMake on the first configuration to determine ``CSharp`` default
+
-compilation flags, after which the value for ``CSFLAGS`` is stored in the cache
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`
-as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+.. |LANG| replace:: ``CSharp``
-run (including the first), the environment variable will be ignored if the
+.. include:: LANG_FLAGS.txt
-:variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
 
 See also :variable:`CMAKE_CSharp_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/CTEST_PROGRESS_OUTPUT.rst

@@ -14,5 +14,5 @@ variable is not set or has a value that evaluates to false, output is reported
 normally with each test having its own start and end lines logged to the
 output.
 
-The ``--progress`` option to :manual:`ctest <ctest(1)>` overrides this
+The :option:`--progress <ctest --progress>` option to :manual:`ctest <ctest(1)>`
-environment variable if both are given.
+overrides this environment variable if both are given.

Help/envvar/CUDAFLAGS.rst

@@ -5,11 +5,10 @@ CUDAFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``CUDA`` files. Will only be
+Add default compilation flags to be used when compiling ``CUDA`` files.
-used by CMake on the first configuration to determine ``CUDA`` default
+
-compilation flags, after which the value for ``CUDAFLAGS`` is stored in the
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`
-cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+.. |LANG| replace:: ``CUDA``
-run (including the first), the environment variable will be ignored if
+.. include:: LANG_FLAGS.txt
-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

@@ -3,11 +3,10 @@ CXXFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``CXX`` (C++) files. Will
+Add default compilation flags to be used when compiling ``CXX`` (C++) files.
-only be used by CMake on the first configuration to determine ``CXX`` default
+
-compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`
-as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run (
+.. |LANG| replace:: ``CXX``
-including the first), the environment variable will be ignored if
+.. include:: LANG_FLAGS.txt
-the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
 
 See also :variable:`CMAKE_CXX_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/DESTDIR.rst

@@ -20,8 +20,9 @@ The packaging tool may then construct the package from the content of the
 
 See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the
 installation prefix when configuring a build tree.  Or, when using
-the :manual:`cmake(1)` command-line tool's ``--install`` mode,
+the :manual:`cmake(1)` command-line tool's :option:`--install <cmake --install>`
-one may specify a different prefix using the ``--prefix`` option.
+mode, one may specify a different prefix using the
+:option:`--prefix <cmake--install --prefix>` option.
 
 .. note::
 

Help/envvar/FFLAGS.rst

@@ -3,11 +3,10 @@ FFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``Fortran`` files. Will only
+Add default compilation flags to be used when compiling ``Fortran`` files.
-be used by CMake on the first configuration to determine ``Fortran`` default
+
-compilation flags, after which the value for ``FFLAGS`` is stored in the cache
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`
-as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+.. |LANG| replace:: ``Fortran``
-run (including the first), the environment variable will be ignored if
+.. include:: LANG_FLAGS.txt
-the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
 
 See also :variable:`CMAKE_Fortran_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/HIPFLAGS.rst

@@ -5,11 +5,10 @@ HIPFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``HIP`` files. Will only be
+Add default compilation flags to be used when compiling ``HIP`` files.
-used by CMake on the first configuration to determine ``HIP`` default
+
-compilation flags, after which the value for ``HIPFLAGS`` is stored in the
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>`
-cache as :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
+.. |LANG| replace:: ``HIP``
-run (including the first), the environment variable will be ignored if
+.. include:: LANG_FLAGS.txt
-the :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
 
 See also :variable:`CMAKE_HIP_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/ISPCFLAGS.rst

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

Help/envvar/LANG_FLAGS.txt

@@ -0,0 +1,6 @@
+CMake uses this environment variable value, in combination with its own
+builtin default flags for the toolchain, to initialize and store the
+|CMAKE_LANG_FLAGS| cache entry.
+This occurs the first time a build tree is configured for language |LANG|.
+For any configuration run (including the first), the environment variable
+will be ignored if the |CMAKE_LANG_FLAGS| variable is already defined.

Help/envvar/RCFLAGS.rst

@@ -3,11 +3,10 @@ RCFLAGS
 
 .. include:: ENV_VAR.txt
 
-Default compilation flags to be used when compiling ``resource`` files. Will
+Add default compilation flags to be used when compiling ``RC`` (resource) files.
-only be used by CMake on the first configuration to determine ``resource``
+
-default compilation flags, after which the value for ``RCFLAGS`` is stored in
+.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`
-the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any
+.. |LANG| replace:: ``RC``
-configuration run (including the first), the environment variable will be ignored
+.. include:: LANG_FLAGS.txt
-if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
 
 See also :variable:`CMAKE_RC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

Help/envvar/SSL_CERT_DIR.rst

@@ -0,0 +1,9 @@
+SSL_CERT_DIR
+------------
+
+.. versionadded:: 3.25
+
+.. include:: ENV_VAR.txt
+
+Specify default directory containing CA certificates.  It overrides
+the default CA directory used.

Help/envvar/SSL_CERT_FILE.rst

@@ -0,0 +1,9 @@
+SSL_CERT_FILE
+-------------
+
+.. versionadded:: 3.25
+
+.. include:: ENV_VAR.txt
+
+Specify the file name containing CA certificates.  It overrides the
+default, os-specific CA file used.

Help/generator/Green Hills MULTI.rst

@@ -28,12 +28,12 @@ Otherwise the ``primaryTarget`` will be composed from the values of :variable:`C
 and ``GHS_TARGET_PLATFORM``. Defaulting to the value of ``arm_integrity.tgt``
 
 * The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-  via the :manual:`cmake(1)` ``-A`` option.
+  via the :option:`cmake -A` option.
 
   | Typical values of ``arm``, ``ppc``, ``86``, etcetera, are used.
 
-* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :manual:`cmake(1)`
+* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :option:`cmake -D`
-  ``-D`` option.
+  option.
 
   | Defaults to ``integrity``.
   | Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``,
@@ -55,11 +55,11 @@ The generator searches for the latest compiler or can be given a location to use
 ``GHS_TOOLSET_ROOT`` is the directory that is checked for the latest compiler.
 
 * The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-  via the :manual:`cmake(1)` ``-T`` option, to specify the location of the toolset.
+  via the :option:`cmake -T` option, to specify the location of the toolset.
   Both absolute and relative paths are valid. Paths are relative to ``GHS_TOOLSET_ROOT``.
 
-* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :manual:`cmake(1)`
+* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :option:`cmake -D`
-  ``-D`` option.
+  option.
 
   | Root path for toolset searches and relative paths.
   | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux.

Help/generator/Ninja Multi-Config.rst

@@ -20,8 +20,8 @@ are intended to be run with ``ninja -f build-<Config>.ninja``. A
 :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
+to build. If no :option:`--config <cmake--build --config>` argument is
-use ``build.ninja``.
+specified, :option:`cmake --build . <cmake --build>` will use ``build.ninja``.
 
 Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as
 ``<target>:<Config>`` targets, where ``<Config>`` is the same as the

Help/generator/Visual Studio 10 2010.rst

@@ -1,52 +1,8 @@
 Visual Studio 10 2010
 ---------------------
 
-Deprecated.  Generates Visual Studio 10 (VS 2010) project files.
+Removed.  This once generated Visual Studio 10 2010 project files, but
-
+the generator has been removed since CMake 3.25.  It is still possible
-.. note::
+to build with VS 10 2010 tools using the :generator:`Visual Studio 12 2013`
-  This generator is deprecated and will be removed in a future version
+(or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to
-  of CMake.  It will still be possible to build with VS 10 2010 tools
+``v100``, or by using the :generator:`NMake Makefiles` generator.
-  using the :generator:`Visual Studio 11 2012` (or above) generator
-  with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``, or by
-  using the :generator:`NMake Makefiles` generator.
-
-For compatibility with CMake versions prior to 3.0, one may specify this
-generator using the name ``Visual Studio 10`` without the year component.
-
-Project Types
-^^^^^^^^^^^^^
-
-Only Visual C++ and C# projects may be generated (and Fortran with
-Intel compiler integration).  Other types of projects (Database,
-Website, etc.) are not supported.
-
-Platform Selection
-^^^^^^^^^^^^^^^^^^
-
-The default target platform name (architecture) is ``Win32``.
-
-.. versionadded:: 3.1
-  The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-  via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
-  name (architecture).  For example:
-
-  * ``cmake -G "Visual Studio 10 2010" -A Win32``
-  * ``cmake -G "Visual Studio 10 2010" -A x64``
-  * ``cmake -G "Visual Studio 10 2010" -A Itanium``
-
-For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of the generator name.
-This is supported only for:
-
-``Visual Studio 10 2010 Win64``
-  Specify target platform ``x64``.
-
-``Visual Studio 10 2010 IA64``
-  Specify target platform ``Itanium``.
-
-Toolset Selection
-^^^^^^^^^^^^^^^^^
-
-The ``v100`` toolset that comes with Visual Studio 10 2010 is selected by
-default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.

Help/generator/Visual Studio 11 2012.rst

@@ -1,7 +1,14 @@
 Visual Studio 11 2012
 ---------------------
 
-Generates Visual Studio 11 (VS 2012) project files.
+Deprecated.  Generates Visual Studio 11 (VS 2012) project files.
+
+.. note::
+  This generator is deprecated and will be removed in a future version
+  of CMake.  It will still be possible to build with VS 11 2012 tools
+  using the :generator:`Visual Studio 12 2013` (or above) generator
+  with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``, or by
+  using the :generator:`NMake Makefiles` generator.
 
 For compatibility with CMake versions prior to 3.0, one may specify this
 generator using the name "Visual Studio 11" without the year component.
@@ -20,7 +27,7 @@ The default target platform name (architecture) is ``Win32``.
 
 .. versionadded:: 3.1
   The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-  via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+  via the :option:`cmake -A` option, to specify a target platform
   name (architecture).  For example:
 
   * ``cmake -G "Visual Studio 11 2012" -A Win32``
@@ -47,4 +54,4 @@ Toolset Selection
 
 The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by
 default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+via the :option:`cmake -T` option, to specify another toolset.

Help/generator/Visual Studio 12 2013.rst

@@ -20,7 +20,7 @@ The default target platform name (architecture) is ``Win32``.
 
 .. versionadded:: 3.1
   The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-  via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+  via the :option:`cmake -A` option, to specify a target platform
   name (architecture).  For example:
 
   * ``cmake -G "Visual Studio 12 2013" -A Win32``
@@ -42,7 +42,7 @@ Toolset Selection
 
 The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by
 default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+via the :option:`cmake -T` option, to specify another toolset.
 
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 32-bit variant even on a 64-bit host.

Help/generator/Visual Studio 14 2015.rst

@@ -18,7 +18,7 @@ Platform Selection
 The default target platform name (architecture) is ``Win32``.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+via the :option:`cmake -A` option, to specify a target platform
 name (architecture).  For example:
 
 * ``cmake -G "Visual Studio 14 2015" -A Win32``
@@ -40,7 +40,7 @@ Toolset Selection
 
 The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by
 default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+via the :option:`cmake -T` option, to specify another toolset.
 
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 32-bit variant even on a 64-bit host.

Help/generator/Visual Studio 15 2017.rst

@@ -26,7 +26,7 @@ Platform Selection
 The default target platform name (architecture) is ``Win32``.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+via the :option:`cmake -A` option, to specify a target platform
 name (architecture).  For example:
 
 * ``cmake -G "Visual Studio 15 2017" -A Win32``
@@ -49,7 +49,7 @@ Toolset Selection
 
 The ``v141`` toolset that comes with Visual Studio 15 2017 is selected by
 default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+via the :option:`cmake -T` option, to specify another toolset.
 
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 32-bit variant even on a 64-bit host.

Help/generator/Visual Studio 16 2019.rst

@@ -25,7 +25,7 @@ The default target platform name (architecture) is that of the host
 and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+via the :option:`cmake -A` option, to specify a target platform
 name (architecture).  For example:
 
 * ``cmake -G "Visual Studio 16 2019" -A Win32``
@@ -38,7 +38,7 @@ Toolset Selection
 
 The ``v142`` toolset that comes with Visual Studio 16 2019 is selected by
 default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+via the :option:`cmake -T` option, to specify another toolset.
 
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 64-bit variant on x64 hosts and

Help/generator/Visual Studio 17 2022.rst

@@ -25,7 +25,7 @@ The default target platform name (architecture) is that of the host
 and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+via the :option:`cmake -A` option, to specify a target platform
 name (architecture).  For example:
 
 * ``cmake -G "Visual Studio 17 2022" -A Win32``
@@ -38,7 +38,7 @@ Toolset Selection
 
 The ``v143`` toolset that comes with VS 17 2022 is selected by default.
 The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+via the :option:`cmake -T` option, to specify another toolset.
 
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 64-bit variant on x64 hosts and

Help/generator/Visual Studio 9 2008.rst

@@ -10,7 +10,7 @@ The default target platform name (architecture) is ``Win32``.
 
 .. versionadded:: 3.1
   The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-  via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+  via the :option:`cmake -A` option, to specify a target platform
   name (architecture).  For example:
 
   * ``cmake -G "Visual Studio 9 2008" -A Win32``

Help/generator/Xcode.rst

@@ -13,7 +13,7 @@ Toolset and Build System Selection
 
 By default Xcode is allowed to select its own default toolchain.
 The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+via the :option:`cmake -T` option, to specify another toolset.
 
 .. versionadded:: 3.19
   This generator supports toolset specification using one of these forms:
@@ -34,7 +34,7 @@ Supported pairs are:
   See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable for allowed values.
 
   For example, to select the original build system under Xcode 12,
-  run :manual:`cmake(1)` with the option ``-T buildsystem=1``.
+  run :manual:`cmake(1)` with the option :option:`-T buildsystem=1 <cmake -T>`.
 
 Swift Support
 ^^^^^^^^^^^^^
@@ -44,3 +44,13 @@ Swift Support
 When using the :generator:`Xcode` generator with Xcode 6.1 or higher,
 one may enable the ``Swift`` language with the :command:`enable_language`
 command or the :command:`project`.
+
+Limitations
+^^^^^^^^^^^
+
+The Xcode generator does not support per-configuration sources.
+Code like the following will result in a generation error:
+
+.. code-block:: cmake
+
+  add_executable(MyApp mymain-$<CONFIG>.cpp)

Help/guide/ide-integration/index.rst

@@ -47,8 +47,9 @@ does, and present the user with the presets listed in the file. Users should be
 able to see (and possibly edit) the CMake cache variables, environment
 variables, and command line options that are defined for a given preset. The
 IDE should then construct the list of appropriate :manual:`cmake(1)` command
-line arguments based on these settings, rather than using the ``--preset=``
+line arguments based on these settings, rather than using the
-option directly. The ``--preset=`` option is intended only as a convenient
+:option:`--preset= <cmake --preset>` option directly. The
+:option:`--preset= <cmake --preset>` option is intended only as a convenient
 frontend for command line users, and should not be used by the IDE.
 
 For example, if a preset named ``ninja`` specifies ``Ninja`` as the generator
@@ -66,10 +67,9 @@ run:
   cmake -S /path/to/source -B /path/to/source/build -G Ninja
 
 In cases where a preset contains lots of cache variables, and passing all of
-them as ``-D`` flags would cause the command line length limit of the platform
+them as :option:`-D <cmake -D>` flags would cause the command line length limit
-to be exceeded, the IDE should instead construct a temporary cache script and
+of the platform to be exceeded, the IDE should instead construct a temporary
-pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the
+cache script and pass it with the :option:`-C <cmake -C>` flag.
-``-C`` flag is used.
 
 While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is
 straightforward, it is not trivial. In addition to the documentation, IDE
@@ -110,8 +110,9 @@ Building
 
 If a Makefile or Ninja generator is used to generate the build tree, it is not
 recommended to invoke ``make`` or ``ninja`` directly. Instead, it is
-recommended that the IDE invoke :manual:`cmake(1)` with the ``--build``
+recommended that the IDE invoke :manual:`cmake(1)` with the
-argument, which will in turn invoke the appropriate build tool.
+:option:`--build <cmake --build>` argument, which will in turn invoke the
+appropriate build tool.
 
 If an IDE project generator is used, such as :generator:`Xcode` or one of the
 Visual Studio generators, and the IDE understands the project format used, the

Help/guide/tutorial/A Basic Starting Point.rst

@@ -1,34 +1,81 @@
 Step 1: A Basic Starting Point
 ==============================
 
-The most basic project is an executable built from source code files.
+Where do I start with CMake? This step will provide an introduction to some of
-For simple projects, a three line ``CMakeLists.txt`` file is all that is
+CMake's basic syntax, commands, and variables. As these concepts are
-required. This will be the starting point for our tutorial. Create a
+introduced, we will work through three exercises and create a simple CMake
-``CMakeLists.txt`` file in the ``Step1`` directory that looks like:
+project.
 
-.. code-block:: cmake
+Each exercise in this step will start with some background information. Then, a
-  :caption: CMakeLists.txt
+goal and list of helpful resources are provided. Each file in the
-  :name: CMakeLists.txt-start
+``Files to Edit`` section is in the ``Step1`` directory and contains one or
+more ``TODO`` comments. Each ``TODO`` represents a line or two of code to
+change or add. The ``TODO`` s are intended to be completed in numerical order,
+first complete  ``TODO 1`` then ``TODO 2``, etc. The ``Getting Started``
+section will give some helpful hints and guide you through the exercise. Then
+the ``Build and Run`` section will walk step-by-step through how to build and
+test the exercise. Finally, at the end of each exercise the intended solution
+is discussed.
 
-  cmake_minimum_required(VERSION 3.10)
+Also note that each step in the tutorial builds on the next. So, for example,
+the starting code for ``Step2`` is the complete solution to ``Step1``.
 
-  # set the project name
+Exercise 1 - Building a Basic Project
-  project(Tutorial)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  # add the executable
+The most basic CMake project is an executable built from a single source code
-  add_executable(Tutorial tutorial.cxx)
+file. For simple projects like this, a ``CMakeLists.txt`` file with three
+commands is all that is required.
 
+**Note:** Although upper, lower and mixed case commands are supported by CMake,
+lower case commands are preferred and will be used throughout the tutorial.
 
-Note that this example uses lower case commands in the ``CMakeLists.txt`` file.
+Any project's top most CMakeLists.txt must start by specifying a minimum CMake
-Upper, lower, and mixed case commands are supported by CMake. The source
+version using the :command:`cmake_minimum_required` command. This establishes
-code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be
+policy settings and ensures that the following CMake functions are run with a
-used to compute the square root of a number.
+compatible version of CMake.
+
+To start a project, we use the :command:`project` command to set the project
+name. This call is required with every project and should be called soon after
+:command:`cmake_minimum_required`. As we will see later, this command can
+also be used to specify other project level information such as the language
+or version number.
+
+Finally, the :command:`add_executable` command tells CMake to create an
+executable using the specified source code files.
+
+Goal
+----
+
+Understand how to create a simple CMake project.
+
+Helpful Resources
+-----------------
+
+* :command:`add_executable`
+* :command:`cmake_minimum_required`
+* :command:`project`
+
+Files to Edit
+-------------
+
+* ``CMakeLists.txt``
+
+Getting Started
+----------------
+
+The source code for ``tutorial.cxx`` is provided in the
+``Help/guide/tutorial/Step1`` directory and can be used to compute the square
+root of a number. This file does not need to be edited in this step.
+
+In the same directory is a ``CMakeLists.txt`` file which you will complete.
+Start with ``TODO 1`` and work through ``TODO 3``.
 
 Build and Run
 -------------
 
-That's all that is needed - we can build and run our project now! First, run
+Once ``TODO 1`` through ``TODO 3`` have been completed, we are ready to build
-the :manual:`cmake <cmake(1)>` executable or the
+and run our project! First, 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.
 
@@ -40,8 +87,9 @@ build directory:
 
   mkdir Step1_build
 
-Next, navigate to the build directory and run CMake to configure the project
+Next, navigate to that build directory and run
-and generate a native build system:
+:manual:`cmake <cmake(1)>` to configure the project and generate a native build
+system:
 
 .. code-block:: console
 
@@ -62,108 +110,113 @@ Finally, try to use the newly built ``Tutorial`` with these commands:
   Tutorial 10
   Tutorial
 
+Solution
+--------
 
-Adding a Version Number and Configured Header File
+As mentioned above, a three line ``CMakeLists.txt`` is all that we need to get
---------------------------------------------------
+up and running. The first line is to use :command:`cmake_minimum_required` to
+set the CMake version as follows:
 
-The first feature we will add is to provide our executable and project with a
+.. raw:: html
-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 use the :command:`project` command
+  <details><summary>TODO 1: Click to show/hide answer</summary>
-to set the project name and version number.
 
 .. literalinclude:: Step2/CMakeLists.txt
-  :caption: CMakeLists.txt
+  :caption: TODO 1: CMakeLists.txt
-  :name: CMakeLists.txt-project-VERSION
+  :name: CMakeLists.txt-cmake_minimum_required
   :language: cmake
-  :end-before: # specify the C++ standard
+  :end-before: # set the project name and version
 
-Then, configure a header file to pass the version number to the source
+.. raw:: html
-code:
+
+  </details>
+
+The next step to make a basic project is to use the :command:`project`
+command as follows to set the project name:
+
+.. raw:: html
+
+  <details><summary>TODO 2: Click to show/hide answer</summary>
+
+.. code-block:: cmake
+  :caption: TODO 2: CMakeLists.txt
+  :name: CMakeLists.txt-project
+
+  project(Tutorial)
+
+.. raw:: html
+
+  </details>
+
+The last command to call for a basic project is
+:command:`add_executable`. We call it as follows:
+
+.. raw:: html
+
+  <details><summary>TODO 3: Click to show/hide answer</summary>
 
 .. literalinclude:: Step2/CMakeLists.txt
-  :caption: CMakeLists.txt
+  :caption: TODO 3: CMakeLists.txt
-  :name: CMakeLists.txt-configure_file
+  :name: CMakeLists.txt-add_executable
   :language: cmake
-  :start-after: # to the source code
+  :start-after: # add the executable
-  :end-before: # add the executable
+  :end-before: # TODO 9:
 
-Since the configured file will be written into the binary tree, we
+.. raw:: html
-must add that directory to the list of paths to search for include
-files. Add the following lines to the end of the ``CMakeLists.txt`` file:
 
-.. literalinclude:: Step2/CMakeLists.txt
+  </details>
-  :caption: CMakeLists.txt
-  :name: CMakeLists.txt-target_include_directories
-  :language: cmake
-  :start-after: # so that we will find TutorialConfig.h
 
-Using your favorite editor, create ``TutorialConfig.h.in`` in the source
+Exercise 2 - Specifying the C++ Standard
-directory with the following contents:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. literalinclude:: Step2/TutorialConfig.h.in
+CMake has some special variables that are either created behind the scenes or
-  :caption: TutorialConfig.h.in
+have meaning to CMake when set by project code. Many of these variables start
-  :name: TutorialConfig.h.in
+with ``CMAKE_``. Avoid this naming convention when creating variables for your
-  :language: c++
+projects. Two of these special user settable variables are
+:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`.
+These may be used together to specify the C++ standard needed to build the
+project.
 
-When CMake configures this header file the values for
+Goal
-``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be
+----
-replaced.
 
-Next modify ``tutorial.cxx`` to include the configured header file,
+Add a feature that requires C++11.
-``TutorialConfig.h``.
 
-Finally, let's print out the executable name and version number by updating
+Helpful Resources
-``tutorial.cxx`` as follows:
+-----------------
 
-.. literalinclude:: Step2/tutorial.cxx
+* :variable:`CMAKE_CXX_STANDARD`
-  :caption: tutorial.cxx
+* :variable:`CMAKE_CXX_STANDARD_REQUIRED`
-  :name: tutorial.cxx-print-version
+* :command:`set`
-  :language: c++
-  :start-after: {
-  :end-before: // convert input to double
 
-Specify the C++ Standard
+Files to Edit
--------------------------
+-------------
 
-Next let's add some C++11 features to our project by replacing ``atof`` with
+* ``CMakeLists.txt``
-``std::stod`` in ``tutorial.cxx``.  At the same time, remove
+* ``tutorial.cxx``
-``#include <cstdlib>``.
 
-.. literalinclude:: Step2/tutorial.cxx
+Getting Started
-  :caption: tutorial.cxx
+---------------
-  :name: tutorial.cxx-cxx11
-  :language: c++
-  :start-after: // convert input to double
-  :end-before: // calculate square root
 
-We will need to explicitly state in the CMake code that it should use the
+Continue editing files in the ``Step1`` directory. Start with ``TODO 4`` and
-correct flags. The easiest way to enable support for a specific C++ standard
+complete through ``TODO 6``.
-in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this
-tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the
-``CMakeLists.txt`` file to ``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`
-to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the
-call to ``add_executable``.
 
-.. literalinclude:: Step2/CMakeLists.txt
+First, edit ``tutorial.cxx`` by adding a feature that requires C++11. Then
-  :caption: CMakeLists.txt
+update ``CMakeLists.txt`` to require C++11.
-  :name: CMakeLists.txt-CXX_STANDARD
-  :language: cmake
-  :end-before: # configure a header file to pass some of the CMake settings
 
-Rebuild
+Build and Run
--------
+-------------
 
-Let's build our project again. We already created a build directory and ran
+Let's build our project again. Since we already created a build directory and
-CMake, so we can skip to the build step:
+ran CMake for Exercise 1, we can skip to the build step:
 
 .. code-block:: console
 
   cd Step1_build
   cmake --build .
 
-Now we can try to use the newly built ``Tutorial`` with same commands as before:
+Now we can try to use the newly built ``Tutorial`` with same commands as
+before:
 
 .. code-block:: console
 
@@ -171,5 +224,238 @@ Now we can try to use the newly built ``Tutorial`` with same commands as before:
   Tutorial 10
   Tutorial
 
-Check that the version number is now reported when running the executable without
+Solution
-any arguments.
+--------
+
+We start by adding some C++11 features to our project by replacing
+``atof`` with ``std::stod`` in ``tutorial.cxx``. This looks like
+the following:
+
+.. raw:: html
+
+  <details><summary>TODO 4: Click to show/hide answer</summary>
+
+.. literalinclude:: Step2/tutorial.cxx
+  :caption: TODO 4: tutorial.cxx
+  :name: tutorial.cxx-cxx11
+  :language: c++
+  :start-after: // convert input to double
+  :end-before: // TODO 12:
+
+.. raw:: html
+
+  </details>
+
+To complete ``TODO 5``, simply remove ``#include <cstdlib>``.
+
+We will need to explicitly state in the CMake code that it should use the
+correct flags. One way to enable support for a specific C++ standard in CMake
+is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this tutorial, set
+the :variable:`CMAKE_CXX_STANDARD` variable in the ``CMakeLists.txt`` file to
+``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to ``True``. Make sure to
+add the :variable:`CMAKE_CXX_STANDARD` declarations above the call to
+:command:`add_executable`.
+
+.. raw:: html
+
+  <details><summary>TODO 6: Click to show/hide answer</summary>
+
+.. literalinclude:: Step2/CMakeLists.txt
+  :caption: TODO 6: CMakeLists.txt
+  :name: CMakeLists.txt-CXX_STANDARD
+  :language: cmake
+  :start-after: # specify the C++ standard
+  :end-before: # TODO 7:
+
+.. raw:: html
+
+  </details>
+
+Exercise 3 - Adding a Version Number and Configured Header File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes it may be useful to have a variable that is defined in your
+``CMakelists.txt`` file also be available in your source code. In this case, we
+would like to print the project version.
+
+One way to accomplish this is by using a configured header file. We create an
+input file with one or more variables to replace. These variables have special
+syntax which looks like ``@VAR@``.
+Then, we use the :command:`configure_file` command to copy the input file to a
+given output file and replace these variables with the current value of ``VAR``
+in the ``CMakelists.txt`` file.
+
+While we could edit the version directly in the source code, using this
+feature is preferred since it creates a single source of truth and avoids
+duplication.
+
+Goal
+----
+
+Define and report the project's version number.
+
+Helpful Resources
+-----------------
+
+* :variable:`<PROJECT-NAME>_VERSION_MAJOR`
+* :variable:`<PROJECT-NAME>_VERSION_MINOR`
+* :command:`configure_file`
+* :command:`target_include_directories`
+
+Files to Edit
+-------------
+
+* ``CMakeLists.txt``
+* ``tutorial.cxx``
+
+Getting Started
+---------------
+
+Continue to edit files from ``Step1``. Start on ``TODO 7`` and complete through
+``TODO 12``. In this exercise, we start by adding a project version number in
+``CMakeLists.txt``. In that same file, use :command:`configure_file` to copy a
+given input file to an output file and substitute some variable values in the
+input file content.
+
+Next, create an input header file ``TutorialConfig.h.in`` defining version
+numbers which will accept variables passed from :command:`configure_file`.
+
+Finally, update ``tutorial.cxx`` to print out its version number.
+
+Build and Run
+-------------
+
+Let's build our project again. As before, we already created a build directory
+and ran CMake so we can skip to the build step:
+
+.. code-block:: console
+
+  cd Step1_build
+  cmake --build .
+
+Verify that the version number is now reported when running the executable
+without any arguments.
+
+Solution
+--------
+
+In this exercise, we improve our executable by printing a version number.
+While we could do this exclusively in the source code, using ``CMakeLists.txt``
+lets us maintain a single source of data for the version number.
+
+First, we modify the ``CMakeLists.txt`` file to use the
+:command:`project` command to set both the project name and version number.
+When the :command:`project` command is called, CMake defines
+``Tutorial_VERSION_MAJOR`` and ``Tutorial_VERSION_MINOR`` behind the scenes.
+
+.. raw:: html
+
+  <details><summary>TODO 7: Click to show/hide answer</summary>
+
+.. literalinclude:: Step2/CMakeLists.txt
+  :caption: TODO 7: CMakeLists.txt
+  :name: CMakeLists.txt-project-VERSION
+  :language: cmake
+  :start-after: # set the project name and version
+  :end-before: # specify the C++ standard
+
+.. raw:: html
+
+  </details>
+
+Then we used :command:`configure_file` to copy the input file with the
+specified CMake variables replaced:
+
+.. raw:: html
+
+  <details><summary>TODO 8: Click to show/hide answer</summary>
+
+.. literalinclude:: Step2/CMakeLists.txt
+  :caption: TODO 8: CMakeLists.txt
+  :name: CMakeLists.txt-configure_file
+  :language: cmake
+  :start-after: # to the source code
+  :end-before: # TODO 8:
+
+.. raw:: html
+
+  </details>
+
+Since the configured file will be written into the project binary
+directory, we must add that directory to the list of paths to search for
+include files.
+
+**Note:** Throughout this tutorial, we will refer to the project build and
+the project binary directory interchangeably. These are the same and are not
+meant to refer to a `bin/` directory.
+
+We used :command:`target_include_directories` to specify
+where the executable target should look for include files.
+
+.. raw:: html
+
+  <details><summary>TODO 9: Click to show/hide answer</summary>
+
+.. literalinclude:: Step2/CMakeLists.txt
+  :caption: TODO 9: CMakeLists.txt
+  :name: CMakeLists.txt-target_include_directories
+  :language: cmake
+  :start-after: # so that we will find TutorialConfig.h
+
+.. raw:: html
+
+  </details>
+
+``TutorialConfig.h.in`` is the input header file to be configured.
+When :command:`configure_file` is called from our ``CMakeLists.txt``, the
+values for ``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will
+be replaced with the corresponding version numbers from the project in
+``TutorialConfig.h``.
+
+.. raw:: html
+
+  <details><summary>TODO 10: Click to show/hide answer</summary>
+
+.. literalinclude:: Step2/TutorialConfig.h.in
+  :caption: TODO 10: TutorialConfig.h.in
+  :name: TutorialConfig.h.in
+  :language: c++
+  :end-before: // TODO 13:
+
+.. raw:: html
+
+  </details>
+
+Next, we need to modify ``tutorial.cxx`` to include the configured header file,
+``TutorialConfig.h``.
+
+.. raw:: html
+
+  <details><summary>TODO 11: Click to show/hide answer</summary>
+
+.. code-block:: c++
+  :caption: TODO 11: tutorial.cxx
+
+  #include "TutorialConfig.h"
+
+.. raw:: html
+
+  </details>
+
+Finally, we print out the executable name and version number by updating
+``tutorial.cxx`` as follows:
+
+.. raw:: html
+
+  <details><summary>TODO 12: Click to show/hide answer</summary>
+
+.. literalinclude:: Step2/tutorial.cxx
+  :caption: TODO 12 : tutorial.cxx
+  :name: tutorial.cxx-print-version
+  :language: c++
+  :start-after: {
+  :end-before: // convert input to double
+
+.. raw:: html
+
+  </details>

Help/guide/tutorial/Adding Export Configuration.rst

@@ -21,7 +21,7 @@ in ``MathFunctions/CMakeLists.txt`` to look like:
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-install-TARGETS-EXPORT
   :language: cmake
-  :start-after: # install rules
+  :start-after: # install libs
 
 Now that we have ``MathFunctions`` being exported, we also need to explicitly
 install the generated ``MathFunctionsTargets.cmake`` file. This is done by

Help/guide/tutorial/Adding Generator Expressions.rst

@@ -1,4 +1,4 @@
-Step 10: Adding Generator Expressions
+Step 4: Adding Generator Expressions
 =====================================
 
 :manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated
@@ -27,58 +27,280 @@ 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.
 
+Exercise 1 - Setting the C++ Standard with Interface Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before we use :manual:`generator expressions <cmake-generator-expressions(7)>`
+let's refactor our existing code to use an ``INTERFACE`` library. We will
+use that library in the next step to demonstrate a common use for
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+Goal
+----
+
+Add an ``INTERFACE`` library target to specify the required C++ standard.
+
+Helpful Resources
+-----------------
+
+* :command:`add_library`
+* :command:`target_compile_features`
+* :command:`target_link_libraries`
+
+Files to Edit
+-------------
+
+* ``CMakeLists.txt``
+* ``MathFunctions/CMakeLists.txt``
+
+Getting Started
+---------------
+
+In this exercise, we will refactor our code to use an ``INTERFACE`` library to
+specify the C++ standard.
+
+The starting source code is provided in the ``Step4`` directory. In this
+exercise, complete ``TODO 1`` through ``TODO 3``.
+
+Start by editing the top level ``CMakeLists.txt`` file. Construct an
+``INTERFACE`` library target called ``tutorial_compiler_flags`` and
+specify ``cxx_std_11`` as a target compiler feature.
+
+Modify ``CMakeLists.txt`` and ``MathFunctions/CMakeLists.txt`` so that all
+targets have a :command:`target_link_libraries` call to
+``tutorial_compiler_flags``.
+
+Build and Run
+-------------
+
+Make a new directory called ``Step4_build``, 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 or by using ``cmake --build .``
+from the build directory.
+
+Here's a refresher of what that looks like from the command line:
+
+.. code-block:: console
+
+  mkdir Step4_build
+  cd Step4_build
+  cmake ../Step4
+  cmake --build .
+
+Next, use the newly built ``Tutorial`` and verify that it is working as
+expected.
+
+Solution
+--------
+
+Let's update our code from the previous step to use interface libraries
+to set our C++ requirements.
+
+To start, we need to remove the two :command:`set` calls on the variables
+:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`.
+The specific lines to remove are as follows:
+
+.. literalinclude:: Step4/CMakeLists.txt
+  :caption: CMakeLists.txt
+  :name: CMakeLists.txt-CXX_STANDARD-variable-remove
+  :language: cmake
+  :start-after: # specify the C++ standard
+  :end-before: # TODO 5: Create helper variables
+
+Next, we need to create an interface library, ``tutorial_compiler_flags``. And
+then use :command:`target_compile_features` to add the compiler feature
+``cxx_std_11``.
+
+
+.. raw:: html
+
+  <details><summary>TODO 1: Click to show/hide answer</summary>
+
+.. literalinclude:: Step5/CMakeLists.txt
+  :caption: TODO 1: CMakeLists.txt
+  :name: CMakeLists.txt-cxx_std-feature
+  :language: cmake
+  :start-after: # specify the C++ standard
+  :end-before: # add compiler warning flags just
+
+.. raw:: html
+
+  </details>
+
+Finally, with our interface library set up, we need to link our
+executable ``Target`` and our ``MathFunctions`` library to our new
+``tutorial_compiler_flags`` library. Respectively, the code will look like
+this:
+
+.. raw:: html
+
+  <details><summary>TODO 2: Click to show/hide answer</summary>
+
+.. literalinclude:: Step5/CMakeLists.txt
+  :caption: TODO 2: CMakeLists.txt
+  :name: CMakeLists.txt-target_link_libraries-step4
+  :language: cmake
+  :start-after: add_executable(Tutorial tutorial.cxx)
+  :end-before: # add the binary tree to the search path for include file
+
+.. raw:: html
+
+  </details>
+
+and this:
+
+.. raw:: html
+
+  <details><summary>TODO 3: Click to show/hide answer</summary>
+
+.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
+  :caption: TODO 3: MathFunctions/CMakeLists.txt
+  :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4
+  :language: cmake
+  :start-after: # link our compiler flags interface library
+  :end-before: # TODO 1
+
+.. raw:: html
+
+  </details>
+
+With this, all of our code still requires C++ 11 to build. Notice
+though that with this method, it gives us the ability to be specific about
+which targets get specific requirements. In addition, we create a single
+source of truth in our interface library.
+
+Exercise 2 - Adding Compiler Warning Flags with Generator Expressions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 A common usage of
 :manual:`generator expressions <cmake-generator-expressions(7)>` is to
 conditionally add compiler flags, such as those for language levels or
 warnings. A nice pattern is to associate this information to an ``INTERFACE``
-target allowing this information to propagate. Let's start by constructing an
+target allowing this information to propagate.
-``INTERFACE`` target and specifying the required C++ standard level of ``11``
-instead of using :variable:`CMAKE_CXX_STANDARD`.
 
-So the following code:
+Goal
+----
 
-.. literalinclude:: Step10/CMakeLists.txt
+Add compiler warning flags when building but not for installed versions.
-  :caption: CMakeLists.txt
+
-  :name: CMakeLists.txt-CXX_STANDARD-variable-remove
+Helpful Resources
+-----------------
+
+* :manual:`cmake-generator-expressions(7)`
+* :command:`cmake_minimum_required`
+* :command:`set`
+* :command:`target_compile_options`
+
+Files to Edit
+-------------
+
+* ``CMakeLists.txt``
+
+Getting Started
+---------------
+
+Start with the resulting files from Exercise 1. Complete ``TODO 4`` through
+``TODO 7``.
+
+First, in the top level ``CMakeLists.txt`` file, we need to set the
+:command:`cmake_minimum_required` to ``3.15``. In this exercise we are going
+to use a generator expression which was introduced in CMake 3.15.
+
+Next we add the desired compiler warning flags that we want for our project.
+As warning flags vary based on the compiler, we use the
+``COMPILE_LANG_AND_ID`` generator expression to control which flags to apply
+given a language and a set of compiler ids.
+
+Build and Run
+-------------
+
+Since we have our build directory already configured from Exercise 1, simply
+rebuild our code by calling the following:
+
+.. code-block:: console
+
+  cd Step4_build
+  cmake --build .
+
+Solution
+--------
+
+Update the :command:`cmake_minimum_required` to require at least CMake
+version ``3.15``:
+
+.. raw:: html
+
+  <details><summary>TODO 4: Click to show/hide answer</summary>
+
+.. literalinclude:: Step5/CMakeLists.txt
+  :caption: TODO 4: CMakeLists.txt
+  :name: MathFunctions-CMakeLists.txt-minimum-required-step4
   :language: cmake
-  :start-after: project(Tutorial VERSION 1.0)
+  :end-before: # set the project name and version
-  :end-before: # control where the static and shared libraries are built so that on windows
 
-Would be replaced with:
+.. raw:: html
 
-.. literalinclude:: Step11/CMakeLists.txt
+  </details>
-  :caption: CMakeLists.txt
-  :name: CMakeLists.txt-cxx_std-feature
-  :language: cmake
-  :start-after: project(Tutorial VERSION 1.0)
-  :end-before: # add compiler warning flags just when building this project via
 
-**Note**:  This upcoming section will require a change to the
+Next we determine which compiler our system is currently using to build
-:command:`cmake_minimum_required` usage in the code.  The Generator Expression
+since warning flags vary based on the compiler we use. This is done with
-that is about to be used was introduced in `3.15`.  Update the call to require
+the ``COMPILE_LANG_AND_ID`` generator expression. We set the result in the
-that more recent version:
+variables ``gcc_like_cxx`` and ``msvc_cxx`` as follows:
 
-.. code-block:: cmake
+.. raw:: html
-  :caption: CMakeLists.txt
-  :name: CMakeLists.txt-version-update
 
-  cmake_minimum_required(VERSION 3.15)
+  <details><summary>TODO 5: Click to show/hide answer</summary>
 
-Next we add the desired compiler warning flags that we want for our project. As
+.. literalinclude:: Step5/CMakeLists.txt
-warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID``
+  :caption: TODO 5: CMakeLists.txt
-generator expression to control which flags to apply given a language and a set
+  :name: CMakeLists.txt-compile_lang_and_id
-of compiler ids as seen below:
-
-.. literalinclude:: Step11/CMakeLists.txt
-  :caption: CMakeLists.txt
-  :name: CMakeLists.txt-target_compile_options-genex
   :language: cmake
   :start-after: # the BUILD_INTERFACE genex
-  :end-before: # control where the static and shared libraries are built so that on windows
+  :end-before: target_compile_options(tutorial_compiler_flags INTERFACE
 
-Looking at this we see that the warning flags are encapsulated inside a
+.. raw:: html
-``BUILD_INTERFACE`` condition. This is done so that consumers of our installed
-project will not inherit our warning flags.
 
-**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have
+  </details>
-a :command:`target_link_libraries` call to ``tutorial_compiler_flags``.
+
+Next we add the desired compiler warning flags that we want for our project.
+Using our variables ``gcc_like_cxx`` and ``msvc_cxx``, we can use another
+generator expression to apply the respective flags only when the variables are
+true. We use :command:`target_compile_options` to apply these flags to our
+interface library.
+
+.. raw:: html
+
+  <details><summary>TODO 6: Click to show/hide answer</summary>
+
+.. code-block:: cmake
+  :caption: TODO 6: CMakeLists.txt
+  :name: CMakeLists.txt-compile_flags
+
+  target_compile_options(tutorial_compiler_flags INTERFACE
+    "$<${gcc_like_cxx}:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>"
+    "$<${msvc_cxx}:-W3>"
+  )
+
+.. raw:: html
+
+  </details>
+
+Lastly, we only want these warning flags to be used during builds. Consumers
+of our installed project should not inherit our warning flags. To specify
+this, we wrap our flags in a generator expression using the ``BUILD_INTERFACE``
+condition. The resulting full code looks like the following:
+
+.. raw:: html
+
+  <details><summary>TODO 7: Click to show/hide answer</summary>
+
+.. literalinclude:: Step5/CMakeLists.txt
+  :caption: TODO 7: CMakeLists.txt
+  :name: CMakeLists.txt-target_compile_options-genex
+  :language: cmake
+  :start-after: set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
+  :end-before: # should we use our own math functions
+
+.. raw:: html
+
+  </details>

Help/guide/tutorial/Adding Support for a Testing Dashboard.rst

@@ -1,4 +1,4 @@
-Step 8: Adding Support for a Testing Dashboard
+Step 6: Adding Support for a Testing Dashboard
 ==============================================
 
 Adding support for submitting our test results to a dashboard is simple. We
@@ -9,21 +9,21 @@ we include the :module:`CTest` module in our top-level ``CMakeLists.txt``.
 
 Replace:
 
-.. code-block:: cmake
+.. literalinclude:: Step6/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-enable_testing-remove
-
+  :language: cmake
-  # enable testing
+  :start-after: # enable testing
-  enable_testing()
+  :end-before: # does the application run
 
 With:
 
-.. code-block:: cmake
+.. literalinclude:: Step7/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-include-CTest
-
+  :language: cmake
-  # enable dashboard scripting
+  :start-after: # enable testing
-  include(CTest)
+  :end-before: # does the application run
 
 The :module:`CTest` module will automatically call ``enable_testing()``, so we
 can remove it from our CMake files.
@@ -46,7 +46,7 @@ downloaded from the ``Settings`` page of the project on the CDash
 instance that will host and display the test results.  Once downloaded from
 CDash, the file should not be modified locally.
 
-.. literalinclude:: Step9/CTestConfig.cmake
+.. literalinclude:: Step7/CTestConfig.cmake
   :caption: CTestConfig.cmake
   :name: CTestConfig.cmake
   :language: cmake

Help/guide/tutorial/Adding System Introspection.rst

@@ -1,4 +1,4 @@
-Step 5: Adding System Introspection
+Step 7: Adding System Introspection
 ===================================
 
 Let us consider adding some code to our project that depends on features the
@@ -15,7 +15,7 @@ these functions using the :module:`CheckCXXSourceCompiles` module in
 Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``,
 after the call to :command:`target_include_directories`:
 
-.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles
   :language: cmake
@@ -25,19 +25,19 @@ after the call to :command:`target_include_directories`:
 If available, use :command:`target_compile_definitions` to specify
 ``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions.
 
-.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-target_compile_definitions
   :language: cmake
   :start-after: # add compile definitions
-  :end-before: # install rules
+  :end-before: # install libs
 
 If ``log`` and ``exp`` are available on the system, then we will use them to
 compute the square root in the ``mysqrt`` function. Add the following code to
 the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
 ``#endif`` before returning the result!):
 
-.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step8/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx-ifdef
   :language: c++
@@ -46,7 +46,7 @@ the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
 
 We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
 
-.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step8/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx-include-cmath
   :language: c++

Help/guide/tutorial/Adding Usage Requirements for a Library.rst

@@ -1,52 +1,147 @@
 Step 3: Adding Usage Requirements for a Library
 ===============================================
 
-Usage requirements allow for far better control over a library or executable's
+Exercise 1 - Adding Usage Requirements for a Library
-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:
 
-  - :command:`target_compile_definitions`
+:ref:`Usage requirements <Target Usage Requirements>` of a target parameters
-  - :command:`target_compile_options`
+allow for far better control over a library or executable's link and include
-  - :command:`target_include_directories`
+line while also giving more control over the transitive property of targets
-  - :command:`target_link_libraries`
+inside CMake. The primary commands that
+leverage usage requirements are:
 
-Let's refactor our code from :guide:`tutorial/Adding a Library` to use the
+* :command:`target_compile_definitions`
-modern CMake approach of usage requirements. We first state that anybody
+* :command:`target_compile_options`
-linking to ``MathFunctions`` needs to include the current source directory,
+* :command:`target_include_directories`
-while ``MathFunctions`` itself doesn't. So this can become an ``INTERFACE``
+* :command:`target_link_directories`
-usage requirement.
+* :command:`target_link_options`
+* :command:`target_precompile_headers`
+* :command:`target_sources`
 
-Remember ``INTERFACE`` means things that consumers require but the producer
+
-doesn't. Add the following lines to the end of
+Goal
-``MathFunctions/CMakeLists.txt``:
+----
+
+Add usage requirements for a library.
+
+Helpful Materials
+-----------------
+
+* :variable:`CMAKE_CURRENT_SOURCE_DIR`
+
+Files to Edit
+-------------
+
+* ``MathFunctions/CMakeLists.txt``
+* ``CMakeLists.txt``
+
+Getting Started
+---------------
+
+In this exercise, we will refactor our code from
+:guide:`tutorial/Adding a Library` to use the modern CMake approach. We will
+let our library define its own usage requirements so they are passed
+transitively to other targets as necessary. In this case, ``MathFunctions``
+will specify any needed include directories itself. Then, the consuming target
+``Tutorial`` simply needs to link to ``MathFunctions`` and not worry about
+any additional include directories.
+
+The starting source code is provided in the ``Step3`` directory. In this
+exercise, complete ``TODO 1`` through ``TODO 3``.
+
+First, add a call to :command:`target_include_directories` in
+``MathFunctions/CMakeLists``. Remember that
+:variable:`CMAKE_CURRENT_SOURCE_DIR` is the path to the source directory
+currently being processed.
+
+Then, update (and simplify!) the call to
+:command:`target_include_directories` in the top-level ``CMakeLists.txt``.
+
+Build and Run
+-------------
+
+Make a new directory called ``Step3_build``, 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 or by
+using :option:`cmake --build . <cmake --build>` from the build directory.
+Here's a refresher of what that looks like from the command line:
+
+.. code-block:: console
+
+  mkdir Step3_build
+  cd Step3_build
+  cmake ../Step3
+  cmake --build .
+
+Next, use the newly built ``Tutorial`` and verify that it is working as
+expected.
+
+Solution
+--------
+
+Let's update the code from the previous step to use the modern CMake
+approach of usage requirements.
+
+We want to state that anybody linking to ``MathFunctions`` needs to include
+the current source directory, while ``MathFunctions`` itself doesn't. This
+can be expressed with an ``INTERFACE`` usage requirement. Remember
+``INTERFACE`` means things that consumers require but the producer doesn't.
+
+At the end of ``MathFunctions/CMakeLists.txt``, use
+:command:`target_include_directories` with the ``INTERFACE`` keyword, as
+follows:
+
+.. raw:: html
+
+  <details><summary>TODO 1: Click to show/hide answer</summary>
 
 .. literalinclude:: Step4/MathFunctions/CMakeLists.txt
-  :caption: MathFunctions/CMakeLists.txt
+  :caption: TODO 1: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE
   :language: cmake
   :start-after: # to find MathFunctions.h
+  :end-before: # TODO 3: Link to
 
-Now that we've specified usage requirements for ``MathFunctions`` we can safely
+.. raw:: html
-remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
+
+  </details>
+
+Now that we've specified usage requirements for ``MathFunctions`` we can
+safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
 ``CMakeLists.txt``, here:
 
+.. raw:: html
+
+  <details><summary>TODO 2: Click to show/hide answer</summary>
+
 .. literalinclude:: Step4/CMakeLists.txt
-  :caption: CMakeLists.txt
+  :caption: TODO 2: CMakeLists.txt
   :name: CMakeLists.txt-remove-EXTRA_INCLUDES
   :language: cmake
   :start-after: # add the MathFunctions library
   :end-before: # add the executable
 
+.. raw:: html
+
+  </details>
+
 And here:
 
+.. raw:: html
+
+  <details><summary>TODO 3: Click to show/hide answer</summary>
+
 .. literalinclude:: Step4/CMakeLists.txt
-  :caption: CMakeLists.txt
+  :caption: TODO 3: CMakeLists.txt
   :name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES
   :language: cmake
   :start-after: # so that we will find TutorialConfig.h
 
-Once this is done, run the :manual:`cmake  <cmake(1)>` executable or the
+.. raw:: html
-:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
+
-with your chosen build tool or by using ``cmake --build .`` from the build
+  </details>
-directory.
+
+Notice that with this technique, the only thing our executable target does to
+use our library is call :command:`target_link_libraries` with the name
+of the library target. In larger projects, the classic method of specifying
+library dependencies manually becomes very complicated very quickly.

Help/guide/tutorial/Adding a Custom Command and Generated File.rst

@@ -1,4 +1,4 @@
-Step 6: Adding a Custom Command and Generated File
+Step 8: Adding a Custom Command and Generated File
 ==================================================
 
 Suppose, for the purpose of this tutorial, we decide that we never want to use
@@ -26,7 +26,7 @@ accomplish this.
 First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
 ``MakeTable`` is added as any other executable would be added.
 
-.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable
   :language: cmake
@@ -36,7 +36,7 @@ First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
 Then we add a custom command that specifies how to produce ``Table.h``
 by running MakeTable.
 
-.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h
   :language: cmake
@@ -47,7 +47,7 @@ Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated
 file ``Table.h``. This is done by adding the generated ``Table.h`` to the list
 of sources for the library MathFunctions.
 
-.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_library-Table.h
   :language: cmake
@@ -57,17 +57,17 @@ of sources for the library MathFunctions.
 We also have to add the current binary directory to the list of include
 directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
 
-.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h
   :language: cmake
   :start-after: # state that we depend on our bin
-  :end-before: # install rules
+  :end-before: # install libs
 
 Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
 ``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table:
 
-.. literalinclude:: Step7/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step9/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx
   :language: c++

Help/guide/tutorial/Adding a Library.rst

@@ -1,136 +1,459 @@
 Step 2: Adding a Library
 ========================
 
-Now we will add a library to our project. This library will contain our own
+At this point, we have seen how to create a basic project using CMake. In this
+step, we will learn how to create and use a library in our project. We will
+also see how to make the use of our library optional.
+
+Exercise 1 - Creating a Library
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To add a library in CMake, use the :command:`add_library` command and specify
+which source files should make up the library.
+
+Rather than placing all of the source files in one directory, we can organize
+our project with one or more subdirectories. In this case, we will create a
+subdirectory specifically for our library. Here, we can add a new
+``CMakeLists.txt`` file and one or more source files. In the top level
+``CMakeLists.txt`` file, we will use the :command:`add_subdirectory` command
+to add the subdirectory to the build.
+
+Once the library is created, it is connected to our executable target with
+:command:`target_include_directories` and :command:`target_link_libraries`.
+
+Goal
+----
+
+Add and use a library.
+
+Helpful Resources
+-----------------
+
+* :command:`add_library`
+* :command:`add_subdirectory`
+* :command:`target_include_directories`
+* :command:`target_link_libraries`
+* :variable:`PROJECT_SOURCE_DIR`
+
+Files to Edit
+-------------
+
+* ``CMakeLists.txt``
+* ``tutorial.cxx``
+* ``MathFunctions/CMakeLists.txt``
+
+Getting Started
+---------------
+
+In this exercise, we will add a library to our project that contains our own
 implementation for computing the square root of a number. The executable can
 then use this library instead of the standard square root function provided by
 the compiler.
 
-For this tutorial we will put the library into a subdirectory
+For this tutorial we will put the library into a subdirectory called
-called ``MathFunctions``. This directory already contains a header file,
+``MathFunctions``. This directory already contains a header file,
-``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one
+``MathFunctions.h``, and a source file ``mysqrt.cxx``. We will not need to
-function called ``mysqrt`` that provides similar functionality to the
+modify either of these files. The source file has one function called
-compiler's ``sqrt`` function.
+``mysqrt`` that provides similar functionality to the compiler's ``sqrt``
+function.
 
-Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions``
+From the ``Help/guide/tutorial/Step2`` directory, start with ``TODO 1`` and
-directory:
+complete through ``TODO 6``.
 
-.. literalinclude:: Step3/MathFunctions/CMakeLists.txt
+First, fill in the one line ``CMakeLists.txt`` in the ``MathFunctions``
-  :caption: MathFunctions/CMakeLists.txt
+subdirectory.
-  :name: MathFunctions/CMakeLists.txt
-  :language: cmake
 
-To make use of the new library we will add an :command:`add_subdirectory`
+Next, edit the top level ``CMakeLists.txt``.
-call in the top-level ``CMakeLists.txt`` file so that the library will get
-built. We add the new library to the executable, and add ``MathFunctions`` as
-an include directory so that the ``MathFunctions.h`` header file can be found.
-The last few lines of the top-level ``CMakeLists.txt`` file should now look
-like:
 
-.. code-block:: cmake
+Finally, use the newly created ``MathFunctions`` library in ``tutorial.cxx``
-        :caption: CMakeLists.txt
-        :name: CMakeLists.txt-add_subdirectory
 
-        # add the MathFunctions library
+Build and Run
-        add_subdirectory(MathFunctions)
+-------------
-
-        # add the executable
-        add_executable(Tutorial tutorial.cxx)
-
-        target_link_libraries(Tutorial PUBLIC MathFunctions)
-
-        # add the binary tree to the search path for include files
-        # so that we will find TutorialConfig.h
-        target_include_directories(Tutorial PUBLIC
-                                  "${PROJECT_BINARY_DIR}"
-                                  "${PROJECT_SOURCE_DIR}/MathFunctions"
-                                  )
-
-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
-occurrence. The first step is to add an option to the top-level
-``CMakeLists.txt`` file.
-
-.. literalinclude:: Step3/CMakeLists.txt
-  :caption: CMakeLists.txt
-  :name: CMakeLists.txt-option
-  :language: cmake
-  :start-after: # should we use our own math functions
-  :end-before: # add the MathFunctions library
-
-This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
-:manual:`ccmake <ccmake(1)>`
-with a default value of ``ON`` that can be changed by the user. This setting
-will 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 will create an ``if`` statement which checks the
-value of the option.  Inside the ``if`` block, put the
-:command:`add_subdirectory` command from above with some additional list
-commands to store information needed to link to the library and add the
-subdirectory as an include directory in the ``Tutorial`` target.
-The end of the top-level ``CMakeLists.txt`` file will now look like the
-following:
-
-.. literalinclude:: Step3/CMakeLists.txt
-  :caption: CMakeLists.txt
-  :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS
-  :language: cmake
-  :start-after: # add the MathFunctions library
-
-Note the use of the variable ``EXTRA_LIBS`` to collect up any optional
-libraries to later be linked into the executable. The variable
-``EXTRA_INCLUDES`` is used similarly for optional header files. This is a
-classic approach when dealing with many optional components, we will cover
-the modern approach in the next step.
-
-The corresponding changes to the source code are fairly straightforward.
-First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we
-need it:
-
-.. literalinclude:: Step3/tutorial.cxx
-  :caption: tutorial.cxx
-  :name: tutorial.cxx-ifdef-include
-  :language: c++
-  :start-after: // should we include the MathFunctions header
-  :end-before: int main
-
-Then, in the same file, make ``USE_MYMATH`` control which square root
-function is used:
-
-.. literalinclude:: Step3/tutorial.cxx
-  :caption: tutorial.cxx
-  :name: tutorial.cxx-ifdef-const
-  :language: c++
-  :start-after: // which square root function should we use?
-  :end-before: std::cout << "The square root of
-
-Since the source code now requires ``USE_MYMATH`` we can add it to
-``TutorialConfig.h.in`` with the following line:
-
-.. literalinclude:: Step3/TutorialConfig.h.in
-  :caption: TutorialConfig.h.in
-  :name: TutorialConfig.h.in-cmakedefine
-  :language: c++
-  :lines: 4
-
-**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 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.
+with your chosen build tool.
 
-Now let's update the value of ``USE_MYMATH``. The easiest way is to use the
+Below is a refresher of what that looks like from the command line:
-:manual:`cmake-gui <cmake-gui(1)>` or  :manual:`ccmake <ccmake(1)>` if you're
+
-in the terminal. Or, alternatively, if you want to change the option from the
+.. code-block:: console
-command-line, try:
+
+  mkdir Step2_build
+  cd Step2_build
+  cmake ../Step2
+  cmake --build .
+
+Try to use the newly built ``Tutorial`` and ensure that it is still
+producing accurate square root values.
+
+Solution
+--------
+
+In the ``CMakeLists.txt`` file in the ``MathFunctions`` directory, we create
+a library target called ``MathFunctions`` with :command:`add_library`. The
+source file for the library is passed as an argument to
+:command:`add_library`. This looks like the following line:
+
+.. raw:: html
+
+  <details><summary>TODO 1: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/MathFunctions/CMakeLists.txt
+  :caption: TODO 1: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-add_library
+  :language: cmake
+  :end-before: # TODO 1
+
+.. raw:: html
+
+  </details>
+
+To make use of the new library we will add an :command:`add_subdirectory`
+call in the top-level ``CMakeLists.txt`` file so that the library will get
+built.
+
+.. raw:: html
+
+  <details><summary>TODO 2: Click to show/hide answer</summary>
+
+.. code-block:: cmake
+  :caption: TODO 2: CMakeLists.txt
+  :name: CMakeLists.txt-add_subdirectory
+
+  add_subdirectory(MathFunctions)
+
+.. raw:: html
+
+  </details>
+
+Next, the new library target is linked to the executable target using
+:command:`target_link_libraries`.
+
+.. raw:: html
+
+  <details><summary>TODO 3: Click to show/hide answer</summary>
+
+.. code-block:: cmake
+  :caption: TODO 3: CMakeLists.txt
+  :name: CMakeLists.txt-target_link_libraries
+
+  target_link_libraries(Tutorial PUBLIC MathFunctions)
+
+.. raw:: html
+
+  </details>
+
+Finally we need to specify the library's header file location. Modify
+:command:`target_include_directories` to add the ``MathFunctions`` subdirectory
+as an include directory so that the ``MathFunctions.h`` header file can be
+found.
+
+.. raw:: html
+
+  <details><summary>TODO 4: Click to show/hide answer</summary>
+
+.. code-block:: cmake
+  :caption: TODO 4: CMakeLists.txt
+  :name: CMakeLists.txt-target_include_directories-step2
+
+  target_include_directories(Tutorial PUBLIC
+                            "${PROJECT_BINARY_DIR}"
+                            "${PROJECT_SOURCE_DIR}/MathFunctions"
+                            )
+
+.. raw:: html
+
+  </details>
+
+Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``:
+
+.. raw:: html
+
+  <details><summary>TODO 5: Click to show/hide answer</summary>
+
+.. code-block:: c++
+  :caption: TODO 5 : tutorial.cxx
+  :name: tutorial.cxx-include_MathFunctions.h
+
+  #include "MathFunctions.h"
+
+.. raw:: html
+
+  </details>
+
+Lastly, replace ``sqrt`` with our library function ``mysqrt``.
+
+.. raw:: html
+
+  <details><summary>TODO 6: Click to show/hide answer</summary>
+
+.. code-block:: c++
+  :caption: TODO 6 : tutorial.cxx
+  :name: tutorial.cxx-call_mysqrt
+
+  const double outputValue = mysqrt(inputValue);
+
+.. raw:: html
+
+  </details>
+
+Exercise 2 - Making Our Library Optional
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+occurrence.
+
+CMake can do this using the :command:`option` command. This gives users a
+variable which they can change when configuring their cmake build. This
+setting will 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.
+
+Goal
+----
+
+Add the option to build without ``MathFunctions``.
+
+
+Helpful Resources
+-----------------
+
+* :command:`if`
+* :command:`list`
+* :command:`option`
+* :command:`cmakedefine <configure_file>`
+
+Files to Edit
+-------------
+
+* ``CMakeLists.txt``
+* ``tutorial.cxx``
+* ``TutorialConfig.h.in``
+
+Getting Started
+---------------
+
+Start with the resulting files from Exercise 1. Complete ``TODO 7`` through
+``TODO 13``.
+
+First create a variable ``USE_MYMATH`` using the :command:`option` command
+in the top-level ``CMakeLists.txt`` file. In that same file, use that option
+to determine whether to build and use the ``MathFunctions`` library.
+
+Then, update ``tutorial.cxx`` and ``TutorialConfig.h.in`` to use
+``USE_MYMATH``.
+
+Build and Run
+-------------
+
+Since we have our build directory already configured from Exercise 1, we can
+rebuild by simply calling the following:
+
+.. code-block:: console
+
+  cd ../Step2_build
+  cmake --build .
+
+Next, run the ``Tutorial`` executable on a few numbers to verify that it's
+still correct.
+
+Now let's update the value of ``USE_MYMATH`` to ``OFF``. The easiest way is to
+use the :manual:`cmake-gui <cmake-gui(1)>` or  :manual:`ccmake <ccmake(1)>`
+if you're in the terminal. Or, alternatively, if you want to change the
+option from the command-line, try:
 
 .. code-block:: console
 
   cmake ../Step2 -DUSE_MYMATH=OFF
 
-Rebuild and run the tutorial again.
+Now, rebuild the code with the following:
 
-Which function gives better results, ``sqrt`` or ``mysqrt``?
+.. code-block:: console
+
+  cmake --build .
+
+Then, run the executable again to ensure that it still works with
+``USE_MYMATH`` set to ``OFF``. Which function gives better results, ``sqrt``
+or ``mysqrt``?
+
+Solution
+--------
+
+The first step is to add an option to the top-level ``CMakeLists.txt`` file.
+This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
+:manual:`ccmake <ccmake(1)>` with a default value of ``ON`` that can be
+changed by the user.
+
+.. raw:: html
+
+  <details><summary>TODO 7: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/CMakeLists.txt
+  :caption: TODO 7: CMakeLists.txt
+  :name: CMakeLists.txt-option
+  :language: cmake
+  :start-after: # should we use our own math functions
+  :end-before: # configure a header file to pass some of the CMake settings
+
+.. raw:: html
+
+  </details>
+
+Next, make building and linking the ``MathFunctions`` library
+conditional.
+
+Start by creating a :command:`list` of the optional library targets for our
+project. At the moment, it is just ``MathFunctions``. Let's name our list
+``EXTRA_LIBS``.
+
+Similarly, we need to make a :command:`list` for the optional includes which
+we will call ``EXTRA_INCLUDES``. In this list, we will ``APPEND`` the path of
+the header file needed for our library.
+
+Next, create an :command:`if` statement which checks the value of
+``USE_MYMATH``. Inside the :command:`if` block, put the
+:command:`add_subdirectory` command from Exercise 1 with the additional
+:command:`list` commands.
+
+When ``USE_MYMATH`` is ``ON``, the lists will be generated and will be added to
+our project. When ``USE_MYMATH`` is ``OFF``, the lists stay empty. With this
+strategy, we allow users to toggle ``USE_MYMATH`` to manipulate what library is
+used in the build.
+
+The top-level CMakeLists.txt file will now look like the following:
+
+.. raw:: html
+
+  <details><summary>TODO 8: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/CMakeLists.txt
+  :caption: TODO 8: CMakeLists.txt
+  :name: CMakeLists.txt-USE_MYMATH
+  :language: cmake
+  :start-after: # add the MathFunctions library
+  :end-before: # add the executable
+
+.. raw:: html
+
+  </details>
+
+Now that we have these two lists, we need to update
+:command:`target_link_libraries` and :command:`target_include_directories` to
+use them. Changing them is fairly straightforward.
+
+For :command:`target_link_libraries`, we replace the written out
+library names with ``EXTRA_LIBS``. This looks like the following:
+
+.. raw:: html
+
+  <details><summary>TODO 9: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/CMakeLists.txt
+  :caption: TODO 9: CMakeLists.txt
+  :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS
+  :language: cmake
+  :start-after: add_executable(Tutorial tutorial.cxx)
+  :end-before: # TODO 3
+
+.. raw:: html
+
+  </details>
+
+Then, we do the same thing with :command:`target_include_directories` and
+``EXTRA_INCLUDES``.
+
+.. raw:: html
+
+  <details><summary>TODO 10: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/CMakeLists.txt
+  :caption: TODO 10 : CMakeLists.txt
+  :name: CMakeLists.txt-target_link_libraries-EXTRA_INCLUDES
+  :language: cmake
+  :start-after: # so that we will find TutorialConfig.h
+
+.. raw:: html
+
+  </details>
+
+Note that this is a classic approach when dealing with many components. We
+will cover the modern approach in the Step 3 of the tutorial.
+
+The corresponding changes to the source code are fairly straightforward.
+First, in ``tutorial.cxx``, we include the ``MathFunctions.h`` header if
+``USE_MYMATH`` is defined.
+
+.. raw:: html
+
+  <details><summary>TODO 11: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/tutorial.cxx
+  :caption: TODO 11 : tutorial.cxx
+  :name: tutorial.cxx-ifdef-include
+  :language: c++
+  :start-after: // should we include the MathFunctions header
+  :end-before: int main
+
+.. raw:: html
+
+  </details>
+
+Then, in the same file, we make ``USE_MYMATH`` control which square root
+function is used:
+
+.. raw:: html
+
+  <details><summary>TODO 12: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/tutorial.cxx
+  :caption: TODO 12 : tutorial.cxx
+  :name: tutorial.cxx-ifdef-const
+  :language: c++
+  :start-after: // which square root function should we use?
+  :end-before: std::cout << "The square root of
+
+.. raw:: html
+
+  </details>
+
+Since the source code now requires ``USE_MYMATH`` we can add it to
+``TutorialConfig.h.in`` with the following line:
+
+.. raw:: html
+
+  <details><summary>TODO 13: Click to show/hide answer</summary>
+
+.. literalinclude:: Step3/TutorialConfig.h.in
+  :caption: TODO 13 : TutorialConfig.h.in
+  :name: TutorialConfig.h.in-cmakedefine
+  :language: c++
+  :lines: 4
+
+.. raw:: html
+
+  </details>
+
+With these changes, our library is now completely optional to whoever is
+building and using it.
+
+Bonus Question
+--------------
+
+Why is it important that we configure ``TutorialConfig.h.in``
+after the option for ``USE_MYMATH``? What would happen if we inverted the two?
+
+Answer
+------
+
+.. raw:: html
+
+  <details><summary>Click to show/hide answer</summary>
+
+We configure after because ``TutorialConfig.h.in`` uses the value of
+``USE_MYMATH``. If we configure the file before
+calling :command:`option`, we won't be using the expected value of
+``USE_MYMATH``.
+
+.. raw:: html
+
+  </details>

Help/guide/tutorial/Complete/CMakeLists.txt

@@ -41,7 +41,7 @@ add_subdirectory(MathFunctions)
 add_executable(Tutorial tutorial.cxx)
 set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
 
-target_link_libraries(Tutorial PUBLIC MathFunctions)
+target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags)
 
 # add the binary tree to the search path for include files
 # so that we will find TutorialConfig.h
@@ -84,6 +84,7 @@ do_test(Tutorial 25 "25 is 5")
 do_test(Tutorial -25 "-25 is (-nan|nan|0)")
 do_test(Tutorial 0.0001 "0.0001 is 0.01")
 
+# setup installer
 include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")

Help/guide/tutorial/Complete/License.txt

@@ -1,2 +1,2 @@
 This is the open source License.txt file introduced in
-CMake/Tutorial/Step7...
+CMake/Tutorial/Step9...

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

@@ -56,7 +56,7 @@ target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
 set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
 
-# install rules
+# install libs
 set(installable_libs MathFunctions tutorial_compiler_flags)
 if(TARGET SqrtLibrary)
   list(APPEND installable_libs SqrtLibrary)
@@ -64,4 +64,5 @@ endif()
 install(TARGETS ${installable_libs}
         EXPORT MathFunctionsTargets
         DESTINATION lib)
+# install include headers
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Installing and Testing.rst

@@ -1,95 +1,311 @@
-Step 4: Installing and Testing
+Step 5: Installing and Testing
 ==============================
 
-Now we can start adding install rules and testing support to our project.
+.. _`Tutorial Testing Support`:
 
-Install Rules
+Exercise 1 - Install Rules
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Often, it is not enough to only build an executable, it should also be
+installable. With CMake, we can specify install rules using the
+:command:`install` command. Supporting local installations for your builds in
+CMake is often as simple as specifying an install location and the targets and
+files to be installed.
+
+Goal
+----
+
+Install the ``Tutorial`` executable and the ``MathFunctions`` library.
+
+Helpful Materials
+-----------------
+
+* :command:`install`
+
+Files to Edit
 -------------
 
-The install rules are fairly simple: for ``MathFunctions`` we want to install
+* ``MathFunctions/CMakeLists.txt``
-the library and header file and for the application we want to install the
+* ``CMakeLists.txt``
-executable and configured header.
 
-So to the end of ``MathFunctions/CMakeLists.txt`` we add:
+Getting Started
+---------------
 
-.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
+The starting code is provided in the ``Step5`` directory. In this
-  :caption: MathFunctions/CMakeLists.txt
+exercise, complete ``TODO 1`` through ``TODO 4``.
-  :name: MathFunctions/CMakeLists.txt-install-TARGETS
-  :language: cmake
-  :start-after: # install rules
 
-And to the end of the top-level ``CMakeLists.txt`` we add:
+First, update ``MathFunctions/CMakeLists.txt`` to install the
+``MathFunctions`` and ``tutorial_compiler_flags`` libraries to the ``lib``
+directory. In that same file, specify the install rules needed to install
+``MathFunctions.h`` to the ``include`` directory.
 
-.. literalinclude:: Step5/CMakeLists.txt
+Then, update the top level ``CMakeLists.txt`` to install
-  :caption: CMakeLists.txt
+the ``Tutorial`` executable to the ``bin`` directory. Lastly, any header files
-  :name: CMakeLists.txt-install-TARGETS
+should be installed to the ``include`` directory. Remember that
-  :language: cmake
+``TutorialConfig.h`` is in the :variable:`PROJECT_BINARY_DIR`.
-  :start-after: # add the install targets
-  :end-before: # enable testing
 
-That is all that is needed to create a basic local install of the tutorial.
+Build and Run
+-------------
 
-Now run the :manual:`cmake  <cmake(1)>` executable or the
+Make a new directory called ``Step5_build``. 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 install step by using the ``install`` option of the
+Then, run the install step by using the :option:`--install <cmake --install>`
-:manual:`cmake  <cmake(1)>` command (introduced in 3.15, older versions of
+option of the :manual:`cmake  <cmake(1)>` command (introduced in 3.15, older
-CMake must use ``make install``) from the command line. For
+versions of CMake must use ``make install``) from the command line. This step
-multi-configuration tools, don't forget to use the ``--config`` argument to
+will install the appropriate header files, libraries, and executables.
-specify the configuration. If using an IDE, simply build the ``INSTALL``
+For example:
-target. This step will install the appropriate header files, libraries, and
-executables. For example:
 
 .. code-block:: console
 
   cmake --install .
 
+For multi-configuration tools, don't forget to use the
+:option:`--config <cmake--build --config>` argument to specify the configuration.
+
+.. code-block:: console
+
+  cmake --install . --config Release
+
+If using an IDE, simply build the ``INSTALL`` target. You can build the same
+install target from the command line like the following:
+
+.. code-block:: console
+
+  cmake --build . --target install --config Debug
+
 The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
-root of where the files will be installed. If using the ``cmake --install``
+root of where the files will be installed. If using the :option:`cmake --install`
-command, the installation prefix can be overridden via the ``--prefix``
+command, the installation prefix can be overridden via the
-argument. For example:
+:option:`--prefix <cmake--install --prefix>` argument. For example:
 
 .. code-block:: console
 
   cmake --install . --prefix "/home/myuser/installdir"
 
-Navigate to the install directory and verify that the installed Tutorial runs.
+Navigate to the install directory and verify that the installed ``Tutorial``
+runs.
 
-.. _`Tutorial Testing Support`:
+Solution
+--------
 
-Testing Support
+The install rules for our project are fairly simple:
+
+* For ``MathFunctions``, we want to install the libraries and header file to
+  the ``lib`` and ``include`` directories respectively.
+
+* For the ``Tutorial`` executable, we want to install the executable and
+  configured header file to the ``bin`` and ``include`` directories
+  respectively.
+
+So to the end of ``MathFunctions/CMakeLists.txt`` we add:
+
+.. raw:: html
+
+  <details><summary>TODO 1: Click to show/hide answer</summary>
+
+.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
+  :caption: TODO 1: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-install-TARGETS
+  :language: cmake
+  :start-after: # install libs
+  :end-before: # install include headers
+
+.. raw:: html
+
+  </details>
+
+and
+
+.. raw:: html
+
+  <details><summary>TODO 2: Click to show/hide answer</summary>
+
+.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
+  :caption: TODO 2: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-install-headers
+  :language: cmake
+  :start-after: # install include headers
+
+.. raw:: html
+
+  </details>
+
+The install rules for the ``Tutorial`` executable and configured header file
+are similar. To the end of the top-level ``CMakeLists.txt`` we add:
+
+.. raw:: html
+
+  <details><summary>TODO 3,4: Click to show/hide answer</summary>
+
+.. literalinclude:: Step6/CMakeLists.txt
+  :caption: CMakeLists.txt
+  :name: TODO 3,4: CMakeLists.txt-install-TARGETS
+  :language: cmake
+  :start-after: # add the install targets
+  :end-before: # enable testing
+
+.. raw:: html
+
+  </details>
+
+That is all that is needed to create a basic local
+install of the tutorial.
+
+Exercise 2 - Testing Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CTest offers a way to easily manage tests for your project. Tests can be
+added through the :command:`add_test` command. Although it is not
+explicitly covered in this tutorial, there is a lot of compatibility
+between CTest and other testing frameworks such as :module:`GoogleTest`.
+
+Goal
+----
+
+Create unit tests for our executable using CTest.
+
+Helpful Materials
+-----------------
+
+* :command:`enable_testing`
+* :command:`add_test`
+* :command:`function`
+* :command:`set_tests_properties`
+* :manual:`ctest <ctest(1)>`
+
+Files to Edit
+-------------
+
+* ``CMakeLists.txt``
+
+Getting Started
 ---------------
 
-Next let's test our application. At the end of the top-level ``CMakeLists.txt``
+The starting source code is provided in the ``Step5`` directory. In this
-file we can enable testing and then add a number of basic tests to verify that
+exercise, complete ``TODO 5`` through ``TODO 9``.
-the application is working correctly.
 
-.. literalinclude:: Step5/CMakeLists.txt
+First, we need to enable testing. Next, begin adding tests to our project
-  :caption: CMakeLists.txt
+using :command:`add_test`. We will work through adding 3 simple tests and
+then you can add additional testing as you see fit.
+
+Build and Run
+-------------
+
+Navigate to the build directory and rebuild the application. Then, run the
+``ctest`` executable: :option:`ctest -N` and :option:`ctest -VV`. For
+multi-config generators (e.g. Visual Studio), the configuration type must be
+specified with the :option:`-C \<mode\> <ctest -C>` flag.  For example, to run tests in Debug
+mode use ``ctest -C Debug -VV`` from the build directory
+(not the Debug subdirectory!). Release mode would be executed from the same
+location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS``
+target from the IDE.
+
+Solution
+--------
+
+Let's test our application. At the end of the top-level ``CMakeLists.txt``
+file we first need to enable testing with the
+:command:`enable_testing` command.
+
+.. raw:: html
+
+  <details><summary>TODO 5: Click to show/hide answer</summary>
+
+.. literalinclude:: Step6/CMakeLists.txt
+  :caption: TODO 5: CMakeLists.txt
   :name: CMakeLists.txt-enable_testing
   :language: cmake
   :start-after: # enable testing
+  :end-before: # does the application run
 
-The first test simply verifies that the application runs, does not segfault or
+.. raw:: html
-otherwise crash, and has a zero return value. This is the basic form of a
-CTest test.
 
-The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test
+  </details>
-property to verify that the output of the test contains certain strings. In
-this case, verifying that the usage message is printed when an incorrect number
-of arguments are provided.
 
-Lastly, we have a function called ``do_test`` that runs the application and
+With testing enabled, we will add a number of basic tests to verify
-verifies that the computed square root is correct for given input. For each
+that the application is working correctly. First, we create a test using
-invocation of ``do_test``, another test is added to the project with a name,
+:command:`add_test` which runs the ``Tutorial`` executable with the
-input, and expected results based on the passed arguments.
+parameter 25 passed in. For this test, we are not going to check the
+executable's computed answer. This test will verify that
+application runs, does not segfault or otherwise crash, and has a zero
+return value. This is the basic form of a CTest test.
 
-Rebuild the application and then cd to the binary directory and run the
+.. raw:: html
-:manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For
+
-multi-config generators (e.g. Visual Studio), the configuration type must be
+  <details><summary>TODO 6: Click to show/hide answer</summary>
-specified with the ``-C <mode>`` flag.  For example, to run tests in Debug
+
-mode use ``ctest -C Debug -VV`` from the binary directory
+.. literalinclude:: Step6/CMakeLists.txt
-(not the Debug subdirectory!). Release mode would be executed from the same
+  :caption: TODO 6: CMakeLists.txt
-location but with a ``-C Release``.  Alternatively, build the ``RUN_TESTS``
+  :name: CMakeLists.txt-test-runs
-target from the IDE.
+  :language: cmake
+  :start-after: # does the application run
+  :end-before: # does the usage message work
+
+.. raw:: html
+
+  </details>
+
+Next, let's use the :prop_test:`PASS_REGULAR_EXPRESSION` test property to
+verify that the output of the test contains certain strings. In this case,
+verifying that the usage message is printed when an incorrect number of
+arguments are provided.
+
+.. raw:: html
+
+  <details><summary>TODO 7: Click to show/hide answer</summary>
+
+.. literalinclude:: Step6/CMakeLists.txt
+  :caption: TODO 7: CMakeLists.txt
+  :name: CMakeLists.txt-test-usage
+  :language: cmake
+  :start-after: # does the usage message work?
+  :end-before: # define a function to simplify adding tests
+
+.. raw:: html
+
+  </details>
+
+The next test we will add verifies the computed value is truly the
+square root.
+
+.. raw:: html
+
+  <details><summary>TODO 8: Click to show/hide answer</summary>
+
+.. code-block:: cmake
+  :caption: TODO 8: CMakeLists.txt
+  :name: CMakeLists.txt-test-standard
+
+  add_test(NAME StandardUse COMMAND Tutorial 4)
+  set_tests_properties(StandardUse
+    PROPERTIES PASS_REGULAR_EXPRESSION "4 is 2"
+    )
+
+.. raw:: html
+
+  </details>
+
+This one test is not enough to give us confidence that it will
+work for all values passed in. We should add more tests to verify this.
+To easily add more tests, we make 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.
+
+.. raw:: html
+
+  <details><summary>TODO 9: Click to show/hide answer</summary>
+
+.. literalinclude:: Step6/CMakeLists.txt
+  :caption: TODO 9: CMakeLists.txt
+  :name: CMakeLists.txt-generalized-tests
+  :language: cmake
+  :start-after: # define a function to simplify adding tests
+
+.. raw:: html
+
+  </details>

Help/guide/tutorial/Packaging Debug and Release.rst

@@ -10,8 +10,8 @@ possible, however, to setup CPack to bundle multiple build directories and
 construct a package that contains multiple configurations of the same project.
 
 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
+for the libraries that will be installed. Let's use `d` as the
-postfix for the debug executable and libraries.
+postfix for the debug libraries.
 
 Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
 ``CMakeLists.txt`` file:
@@ -41,10 +41,10 @@ Let's also add version numbering to the ``MathFunctions`` library. In
   :name: MathFunctions/CMakeLists.txt-VERSION-properties
   :language: cmake
   :start-after: # setup the version numbering
-  :end-before: # install rules
+  :end-before: # install libs
 
 From the ``Step12`` directory, create ``debug`` and ``release``
-subbdirectories. The layout will look like:
+subdirectories. The layout will look like:
 
 .. code-block:: none
 

Help/guide/tutorial/Packaging an Installer.rst

@@ -1,4 +1,4 @@
-Step 7: Packaging an Installer
+Step 9: Packaging an Installer
 ==============================
 
 Next suppose that we want to distribute our project to other people so that
@@ -11,7 +11,7 @@ installations and package management features. To accomplish this we will use
 CPack to create platform specific installers. Specifically we need to add a
 few lines to the bottom of our top-level ``CMakeLists.txt`` file.
 
-.. literalinclude:: Step8/CMakeLists.txt
+.. literalinclude:: Step10/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-include-CPack
   :language: cmake
@@ -38,15 +38,15 @@ binary directory run:
 
   cpack
 
-To specify the generator, use the ``-G`` option. For multi-config builds, use
+To specify the generator, use the :option:`-G <cpack -G>` option. For multi-config builds,
-``-C`` to specify the configuration. For example:
+use :option:`-C <cpack -C>` to specify the configuration. For example:
 
 .. code-block:: console
 
   cpack -G ZIP -C Debug
 
 For a list of available generators, see :manual:`cpack-generators(7)` or call
-``cpack --help``. An :cpack_gen:`archive generator <CPack Archive Generator>`
+:option:`cpack --help`. An :cpack_gen:`archive generator <CPack Archive Generator>`
 like ZIP creates a compressed archive of all *installed* files.
 
 To create an archive of the *full* source tree you would type:

Help/guide/tutorial/Selecting Static or Shared Libraries.rst

@@ -1,5 +1,5 @@
-Step 9: Selecting Static or Shared Libraries
+Step 10: Selecting Static or Shared Libraries
-============================================
+=============================================
 
 In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can
 be used to control the default behavior of :command:`add_library`,
@@ -19,7 +19,7 @@ library.
 The first step is to update the starting section of the top-level
 ``CMakeLists.txt`` to look like:
 
-.. literalinclude:: Step10/CMakeLists.txt
+.. literalinclude:: Step11/CMakeLists.txt
   :caption: CMakeLists.txt
   :name: CMakeLists.txt-option-BUILD_SHARED_LIBS
   :language: cmake
@@ -33,7 +33,7 @@ explicitly require that SqrtLibrary is built statically.
 
 The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
 
-.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-add_library-STATIC
   :language: cmake
@@ -42,7 +42,7 @@ The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
 Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and
 ``detail`` namespaces:
 
-.. literalinclude:: Step10/MathFunctions/mysqrt.cxx
+.. literalinclude:: Step11/MathFunctions/mysqrt.cxx
   :caption: MathFunctions/mysqrt.cxx
   :name: MathFunctions/mysqrt.cxx-namespace
   :language: c++
@@ -56,7 +56,7 @@ uses ``USE_MYMATH``:
 
 Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 
-.. literalinclude:: Step10/MathFunctions/MathFunctions.h
+.. literalinclude:: Step11/MathFunctions/MathFunctions.h
   :caption: MathFunctions/MathFunctions.h
   :name: MathFunctions/MathFunctions.h
   :language: c++
@@ -67,7 +67,7 @@ library that has position independent code. The solution to this is to
 explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
 SqrtLibrary to be ``True`` no matter the build type.
 
-.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
   :caption: MathFunctions/CMakeLists.txt
   :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE
   :language: cmake

Help/guide/tutorial/Step1/CMakeLists.txt

@@ -0,0 +1,16 @@
+# TODO 1: Set the minimum required version of CMake to be 3.10
+
+# TODO 2: Create a project named Tutorial
+
+# TODO 7: Set the project version number as 1.0 in the above project command
+
+# TODO 6: Set the variable CMAKE_CXX_STANDARD to 11
+#         and the variable CMAKE_CXX_STANDARD_REQUIRED to True
+
+# TODO 8: Use configure_file to configure and copy TutorialConfig.h.in to
+#         TutorialConfig.h
+
+# TODO 3: Add an executable called Tutorial to the project
+# Hint: Be sure to specify the source file as tutorial.cxx
+
+# TODO 9: Use target_include_directories to include ${PROJECT_BINARY_DIR}

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

@@ -0,0 +1,2 @@
+// the configured options and settings for Tutorial
+// TODO 10: Define Tutorial_VERSION_MAJOR and Tutorial_VERSION_MINOR