New upstream version 3.16.3

.clang-format

@@ -18,4 +18,28 @@ ColumnLimit: 79
 IndentPPDirectives: AfterHash
 SortUsingDeclarations: false
 SpaceAfterTemplateKeyword: true
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex:           '^[<"]cmConfigure\.h'
+    Priority:        -1
+  - Regex:           '^(<|")cm/'
+    Priority:        2
+  - Regex:           '^(<|")windows\.h'
+    Priority:        3
+  - Regex:           '^<sys/'
+    Priority:        5
+  - Regex:           '^(<|")Qt?[A-Z]'
+    Priority:        6
+  - Regex:           '^(<|")cmsys/'
+    Priority:        7
+  - Regex:           '^(<|")cm_'
+    Priority:        8
+  - Regex:           '^(<|")cm[A-Z][^.]+\.h'
+    Priority:        9
+  - Regex:           '^<[^.]+\.h'
+    Priority:        4
+  - Regex:           '^<'
+    Priority:        1
+  - Regex:           '.*'
+    Priority:        10
 ...

.clang-tidy

@@ -3,29 +3,27 @@ Checks: "-*,\
 bugprone-*,\
 -bugprone-macro-parentheses,\
 -bugprone-misplaced-widening-cast,\
+-bugprone-narrowing-conversions,\
+-bugprone-too-small-loop-variable,\
 google-readability-casting,\
 misc-*,\
--misc-incorrect-roundings,\
+-misc-non-private-member-variables-in-classes,\
--misc-macro-parentheses,\
--misc-misplaced-widening-cast,\
 -misc-static-assert,\
 modernize-*,\
--modernize-deprecated-headers,\
+-modernize-avoid-c-arrays,\
--modernize-return-braced-init-list,\
+-modernize-use-nodiscard,\
--modernize-use-auto,\
 -modernize-use-noexcept,\
 -modernize-use-transparent-functors,\
--modernize-use-using,\
 performance-*,\
--performance-inefficient-string-concatenation,\
 readability-*,\
 -readability-function-size,\
 -readability-identifier-naming,\
--readability-implicit-bool-cast,\
 -readability-implicit-bool-conversion,\
 -readability-inconsistent-declaration-parameter-name,\
+-readability-magic-numbers,\
 -readability-named-parameter,\
 -readability-redundant-declaration,\
+-readability-uppercase-literal-suffix,\
 "
 HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'
 CheckOptions:
@@ -33,4 +31,6 @@ CheckOptions:
     value: '1'
   - key:   modernize-use-equals-default.IgnoreMacros
     value: '0'
+  - key:   modernize-use-auto.MinTypeNameLength
+    value: '80'
 ...

Auxiliary/bash-completion/cmake

@@ -76,8 +76,8 @@ _cmake()
                 compopt -o nospace
             else
             # complete variable names
-                COMPREPLY=( $( compgen -W '$( cmake -LA -N | tail -n +2 |
+                COMPREPLY=( $( compgen -W '$( cmake -LA -N 2>/dev/null |
-                    cut -f1 -d: )' -P "$prefix" -- "$cur" ) )
+                    tail -n +2 | cut -f1 -d: )' -P "$prefix" -- "$cur" ) )
                 compopt -o nospace
             fi
             return

Auxiliary/cmake-mode.el

@@ -1,5 +1,7 @@
 ;;; cmake-mode.el --- major-mode for editing CMake sources
 
+;; Package-Requires: ((emacs "24.1"))
+
 ; Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 ; file Copyright.txt or https://cmake.org/licensing for details.
 
@@ -224,17 +226,11 @@ the indentation.  Otherwise it retains the same position on the line"
 ;;
 (defvar cmake-mode-hook nil)
 
-;------------------------------------------------------------------------------
-
-;; For compatibility with Emacs < 24
-(defalias 'cmake--parent-mode
-  (if (fboundp 'prog-mode) 'prog-mode 'fundamental-mode))
-
 ;;------------------------------------------------------------------------------
 ;; Mode definition.
 ;;
 ;;;###autoload
-(define-derived-mode cmake-mode cmake--parent-mode "CMake"
+(define-derived-mode cmake-mode prog-mode "CMake"
   "Major mode for editing CMake source files."
 
   ; Setup font-lock mode.

Auxiliary/vim/syntax/cmake.vim

@@ -288,6 +288,7 @@ syn keyword cmakeProperty contained
             \ SKIP_AUTORCC
             \ SKIP_AUTOUIC
             \ SKIP_BUILD_RPATH
+            \ SKIP_REGULAR_EXPRESSION
             \ SKIP_RETURN_CODE
             \ SOURCES
             \ SOURCE_DIR
@@ -915,6 +916,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
             \ CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT
             \ CMAKE_ECLIPSE_MAKE_ARGUMENTS
+            \ CMAKE_ECLIPSE_RESOURCE_ENCODING
             \ CMAKE_ECLIPSE_VERSION
             \ CMAKE_EDIT_COMMAND
             \ CMAKE_ENABLE_EXPORTS
@@ -948,6 +950,12 @@ syn keyword cmakeVariable contained
             \ CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
             \ CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
             \ CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
+            \ CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
+            \ CMAKE_FIND_USE_CMAKE_PATH
+            \ CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
+            \ CMAKE_FIND_USE_PACKAGE_REGISTRY
+            \ CMAKE_FIND_USE_PACKAGE_ROOT_PATH
+            \ CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
             \ CMAKE_FOLDER
             \ CMAKE_FRAMEWORK
             \ CMAKE_FRAMEWORK_PATH
@@ -1765,6 +1773,7 @@ syn keyword cmakeKWadd_test contained
             \ NAME
             \ OFF
             \ PASS_REGULAR_EXPRESSION
+            \ SKIP_REGULAR_EXPRESSION
             \ TARGET_FILE
             \ WILL_FAIL
             \ WORKING_DIRECTORY

CMakeCPack.cmake

@@ -215,7 +215,7 @@ if(NOT DEFINED CPACK_PACKAGE_FILE_NAME)
   endif()
 endif()
 
-set(CPACK_PACKAGE_CONTACT "cmake@cmake.org")
+set(CPACK_PACKAGE_CONTACT "cmake+development@discourse.cmake.org")
 
 if(UNIX)
   set(CPACK_STRIP_FILES "${CMAKE_BIN_DIR}/ccmake;${CMAKE_BIN_DIR}/cmake;${CMAKE_BIN_DIR}/cpack;${CMAKE_BIN_DIR}/ctest")

CMakeLists.txt

@@ -1,13 +1,24 @@
 # 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.1...3.14 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.1...3.15 FATAL_ERROR)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
 project(CMake)
 unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX)
 unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
 
+# FIXME: This block should go away after a transition period.
+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(c DEBUG MINSIZEREL RELEASE RELWITHDEBINFO)
+      string(REGEX REPLACE "[-/]M[DT]d?( |$)" "" "CMAKE_${l}_FLAGS_${c}" "${CMAKE_${l}_FLAGS_${c}}")
+    endforeach()
+  endforeach()
+endif()
+
 # Make sure we can find internal find_package modules only used for
 # building CMake and not for shipping externally
 list(INSERT CMAKE_MODULE_PATH 0 ${CMake_SOURCE_DIR}/Source/Modules)
@@ -18,6 +29,10 @@ if(CMAKE_BOOTSTRAP)
   unset(CMAKE_BOOTSTRAP CACHE)
 endif()
 
+if(CMake_TEST_HOST_CMAKE)
+  get_filename_component(CMake_TEST_EXTERNAL_CMAKE "${CMAKE_COMMAND}" DIRECTORY)
+endif()
+
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
   if(CMAKE_SYSTEM_NAME STREQUAL "HP-UX")
     message(FATAL_ERROR
@@ -353,11 +368,24 @@ macro (CMAKE_BUILD_UTILITIES)
   # Setup third-party libraries.
   # Everything in the tree should be able to include files from the
   # Utilities directory.
+  if (CMAKE_SYSTEM_NAME STREQUAL "AIX" AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+    # 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
     ${CMake_SOURCE_DIR}/Utilities
     )
 
+  #---------------------------------------------------------------------
+  # 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()
@@ -429,10 +457,7 @@ macro (CMAKE_BUILD_UTILITIES)
     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)")
-      find_package(OpenSSL QUIET)
+      set(_CMAKE_USE_OPENSSL_DEFAULT ON)
-      if(OPENSSL_FOUND)
-        set(_CMAKE_USE_OPENSSL_DEFAULT ON)
-      endif()
     endif()
     option(CMAKE_USE_OPENSSL "Use OpenSSL." ${_CMAKE_USE_OPENSSL_DEFAULT})
     mark_as_advanced(CMAKE_USE_OPENSSL)
@@ -629,8 +654,7 @@ endif()
 # The main section of the CMakeLists file
 #
 #-----------------------------------------------------------------------
-# Compute CMake_VERSION, etc.
+include(Source/CMakeVersion.cmake)
-include(Source/CMakeVersionCompute.cmake)
 
 # Include the standard Dart testing module
 enable_testing()
@@ -677,7 +701,7 @@ endif()
 # to a cdash4simpletest database. In these cases, the CDash dashboards
 # should be run first.
 #
-if("x${CMAKE_TESTS_CDASH_SERVER}" STREQUAL "x")
+if("x${CMAKE_TESTS_CDASH_SERVER}" STREQUAL "x" AND NOT CMake_TEST_NO_NETWORK)
   set(CMAKE_TESTS_CDASH_SERVER "http://open.cdash.org")
 endif()
 
@@ -817,7 +841,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
     PATTERN "*.sh*" PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE
                                 GROUP_READ GROUP_EXECUTE
                                 WORLD_READ WORLD_EXECUTE
-    REGEX "Help/dev($|/)" EXCLUDE
+    REGEX "Help/(dev|guide)($|/)" EXCLUDE
     )
 
   # Install auxiliary files integrating with other tools.

CONTRIBUTING.rst

@@ -27,14 +27,15 @@ To contribute patches:
 #. Run `Utilities/SetupForDevelopment.sh`_ for local git configuration.
 #. See `Building CMake`_ for building CMake locally.
 #. See the `CMake Source Code Guide`_ for coding guidelines.
-#. Base all new work on the upstream ``master`` branch.
+#. Create a topic branch named suitably for your work.
+   Base all new work on the upstream ``master`` branch.
    Base work on the upstream ``release`` branch only if it fixes a
    regression or bug in a feature new to that release.
    If in doubt, prefer ``master``.  Reviewers may simply ask for
    a rebase if deemed appropriate in particular cases.
 #. Create commits making incremental, distinct, logically complete changes
    with appropriate `commit messages`_.
-#. Push a topic branch to a personal repository fork on GitLab.
+#. Push the topic branch to a personal repository fork on GitLab.
 #. Create a GitLab Merge Request targeting the upstream ``master`` branch
    (even if the change is intended for merge to the ``release`` branch).
    Check the box labelled "Allow commits from members who can merge to the

CTestCustom.cmake.in

@@ -49,6 +49,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "WarningMessagesDialog\\.cxx"
   "warning.*directory name.*CMake-Xcode.*/bin/.*does not exist.*"
   "stl_deque.h:1051"
+  "Tests/CMakeLib/testCTestResourceSpec.cxx:.*warning: missing initializer for member.*cmCTestResourceSpec::.*" # GCC 4.8 disagrees with later compilers on C++11 initializer list conversion
   "(Lexer|Parser).*warning.*conversion.*may (alter its value|change the sign)"
   "(Lexer|Parser).*warning.*(statement is unreachable|will never be executed)"
   "(Lexer|Parser).*warning.*variable.*was set but never used"

CompileFlags.cmake

@@ -54,12 +54,20 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "^parisc")
 endif()
 
 # Workaround for TOC Overflow on ppc64
+set(bigTocFlag "")
 if(CMAKE_SYSTEM_NAME STREQUAL "AIX" AND
    CMAKE_SYSTEM_PROCESSOR MATCHES "powerpc")
-  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-bbigtoc")
+  set(bigTocFlag "-Wl,-bbigtoc")
 elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND
    CMAKE_SYSTEM_PROCESSOR MATCHES "ppc64")
-  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,--no-multi-toc")
+  set(bigTocFlag "-Wl,--no-multi-toc")
+endif()
+if(bigTocFlag)
+  include(CheckCXXLinkerFlag)
+  check_cxx_linker_flag(${bigTocFlag} BIG_TOC_FLAG_SUPPORTED)
+  if(BIG_TOC_FLAG_SUPPORTED)
+    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${bigTocFlag}")
+  endif()
 endif()
 
 if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND

Help/command/FIND_XXX.txt

@@ -79,17 +79,19 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in
    :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 
-1. If called from within a find module loaded by
+1. If called from within a find module or any other script loaded by a call to
    :command:`find_package(<PackageName>)`, search prefixes unique to the
-   current package being found.  Specifically look in the
+   current package being found.  Specifically, look in the
    :variable:`<PackageName>_ROOT` CMake variable and the
    :envvar:`<PackageName>_ROOT` environment variable.
-   The package root variables are maintained as a stack so if called from
+   The package root variables are maintained as a stack, so if called from
-   nested find modules, root paths from the parent's find module will be
+   nested find modules or config packages, root paths from the parent's find
-   searched after paths from the current module,
+   module or config package will be searched after paths from the current
-   i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
+   module or package.  In other words, the search order would be
+   ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
    ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
-   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
+   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
+   the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
    See policy :policy:`CMP0074`.
 
    * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
@@ -97,7 +99,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 2. Search paths specified in cmake-specific cache variables.
    These are intended to be used on the command line with a ``-DVAR=value``.
    The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
-   This can be skipped if ``NO_CMAKE_PATH`` is passed.
+   This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``.
 
    * |CMAKE_PREFIX_PATH_XXX|
    * |CMAKE_XXX_PATH|
@@ -107,7 +110,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    These are intended to be set in the user's shell configuration,
    and therefore use the host's native path separator
    (``;`` on Windows and ``:`` on UNIX).
-   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed.
+   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or
+   by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``.
 
    * |CMAKE_PREFIX_PATH_XXX|
    * |CMAKE_XXX_PATH|
@@ -119,13 +123,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    Hard-coded guesses should be specified with the ``PATHS`` option.
 
 5. Search the standard system environment variables.
-   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
+   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by
+   setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.
 
    * |SYSTEM_ENVIRONMENT_PATH_XXX|
+   * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
 
 6. Search cmake variables defined in the Platform files
    for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
-   is passed.
+   is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
+   to ``FALSE``.
 
    * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
    * |CMAKE_SYSTEM_XXX_PATH|

Help/command/LINK_OPTIONS_LINKER.txt

@@ -1,8 +1,8 @@
-To pass options to the linker tool, each compiler driver has is own syntax.
+To pass options to the linker tool, each compiler driver has its own syntax.
-The ``LINKER:`` prefix can be used to specify, in a portable way, options
+The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable
-to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required
+way, options to pass to the linker tool. ``LINKER:`` is replaced by the
-driver option and the rest of the option string defines linker arguments using
+appropriate driver option and ``,`` by the appropriate driver separator.
-``,`` as separator. These arguments will be formatted according to the
+The driver prefix and driver separator are given by the values of the
 :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and
 :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables.
 
@@ -12,11 +12,11 @@ For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for
 The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix
 expression.
 
-The ``LINKER:`` prefix supports, as alternate syntax, specification of
+The ``LINKER:`` prefix supports, as an alternative syntax, specification of
-arguments using ``SHELL:`` prefix and space as separator. Previous example
+arguments using the ``SHELL:`` prefix and space as separator. The previous
-becomes ``"LINKER:SHELL:-z defs"``.
+example then becomes ``"LINKER:SHELL:-z defs"``.
 
 .. note::
 
-  Specifying ``SHELL:`` prefix elsewhere than at the beginning of the
+  Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the
   ``LINKER:`` prefix is not supported.

Help/command/OPTIONS_SHELL.txt

@@ -1,9 +1,9 @@
 The final set of compile or link options used for a target is constructed by
 accumulating options from the current target and the usage requirements of
-it dependencies.  The set of options is de-duplicated to avoid repetition.
+its dependencies.  The set of options is de-duplicated to avoid repetition.
 While beneficial for individual options, the de-duplication step can break
 up option groups.  For example, ``-D A -D B`` becomes ``-D A B``.  One may
 specify a group of options using shell-like quoting along with a ``SHELL:``
-prefix.  The ``SHELL:`` prefix is dropped and the rest of the option string
+prefix.  The ``SHELL:`` prefix is dropped, and the rest of the option string
 is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode.
 For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``.

Help/command/add_custom_command.rst

@@ -68,9 +68,6 @@ The options are:
   order-only dependencies to ensure the byproducts will be
   available before their dependents build.
 
-  The ``BYPRODUCTS`` option is ignored on non-Ninja generators
-  except to mark byproducts ``GENERATED``.
-
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,
@@ -82,25 +79,33 @@ The options are:
   will be ignored.
 
   If ``COMMAND`` specifies an executable target name (created by the
-  :command:`add_executable` command) it will automatically be replaced
+  :command:`add_executable` command), it will automatically be replaced
-  by the location of the executable created at build time. If set, the
+  by the location of the executable created at build time if either of
-  :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will
+  the following is true:
-  also be prepended to the command to allow the executable to run on
+
-  the host.
+  * The target is not being cross-compiled (i.e. the
-  (Use the ``TARGET_FILE``
+    :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
-  :manual:`generator expression <cmake-generator-expressions(7)>` to
+  * The target is being cross-compiled and an emulator is provided (i.e.
-  reference an executable later in the command line.)
+    its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
-  Additionally a target-level dependency will be added so that the
+    In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
-  executable target will be built before any target using this custom
+    prepended to the command before the location of the target executable.
-  command.  However this does NOT add a file-level dependency that
+
-  would cause the custom command to re-run whenever the executable is
+  If neither of the above conditions are met, it is assumed that the
-  recompiled.
+  command name is a program to be found on the ``PATH`` at build time.
 
   Arguments to ``COMMAND`` may use
   :manual:`generator expressions <cmake-generator-expressions(7)>`.
-  References to target names in generator expressions imply target-level
+  Use the ``TARGET_FILE`` generator expression to refer to the location of
-  dependencies, but NOT file-level dependencies.  List target names with
+  a target later in the command line (i.e. as a command argument rather
-  the ``DEPENDS`` option to add file-level dependencies.
+  than as the command to execute).
+
+  Whenever a target is used as a command to execute or is mentioned in a
+  generator expression as a command argument, a target-level dependency
+  will be added automatically so that the mentioned target will be built
+  before any target using this custom command.  However this does NOT add
+  a file-level dependency that would cause the custom command to re-run
+  whenever the executable is recompiled.  List target names with
+  the ``DEPENDS`` option to add such file-level dependencies.
 
 ``COMMENT``
   Display the given message before the commands are executed at
@@ -111,6 +116,9 @@ The options are:
   an ``OUTPUT`` of another custom command in the same directory
   (``CMakeLists.txt`` file) CMake automatically brings the other
   custom command into the target in which this command is built.
+  A target-level dependency is added if any dependency is listed as
+  ``BYPRODUCTS`` of a target or any of its build events in the same
+  directory to ensure the byproducts will be available.
   If ``DEPENDS`` is not specified the command will run whenever
   the ``OUTPUT`` is missing; if the command does not actually
   create the ``OUTPUT`` then the rule will always run.
@@ -219,7 +227,8 @@ target is already built, the command will not execute.
                      [BYPRODUCTS [files...]]
                      [WORKING_DIRECTORY dir]
                      [COMMENT comment]
-                     [VERBATIM] [USES_TERMINAL])
+                     [VERBATIM] [USES_TERMINAL]
+                     [COMMAND_EXPAND_LISTS])
 
 This defines a new command that will be associated with building the
 specified ``<target>``.  The ``<target>`` must be defined in the current

Help/command/add_custom_target.rst

@@ -49,9 +49,6 @@ The options are:
   order-only dependencies to ensure the byproducts will be
   available before their dependents build.
 
-  The ``BYPRODUCTS`` option is ignored on non-Ninja generators
-  except to mark byproducts ``GENERATED``.
-
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
   If more than one ``COMMAND`` is specified they will be executed in order,
@@ -61,18 +58,30 @@ The options are:
   a ``COMMAND`` to launch it.)
 
   If ``COMMAND`` specifies an executable target name (created by the
-  :command:`add_executable` command) it will automatically be replaced
+  :command:`add_executable` command), it will automatically be replaced
-  by the location of the executable created at build time. If set, the
+  by the location of the executable created at build time if either of
-  :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will
+  the following is true:
-  also be prepended to the command to allow the executable to run on
+
-  the host.
+  * The target is not being cross-compiled (i.e. the
-  Additionally a target-level dependency will be added so that the
+    :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
-  executable target will be built before this custom target.
+  * The target is being cross-compiled and an emulator is provided (i.e.
+    its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
+    In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
+    prepended to the command before the location of the target executable.
+
+  If neither of the above conditions are met, it is assumed that the
+  command name is a program to be found on the ``PATH`` at build time.
 
   Arguments to ``COMMAND`` may use
   :manual:`generator expressions <cmake-generator-expressions(7)>`.
-  References to target names in generator expressions imply target-level
+  Use the ``TARGET_FILE`` generator expression to refer to the location of
-  dependencies.
+  a target later in the command line (i.e. as a command argument rather
+  than as the command to execute).
+
+  Whenever a target is used as a command to execute or is mentioned in a
+  generator expression as a command argument, a target-level dependency
+  will be added automatically so that the mentioned target will be built
+  before this custom target.
 
   The command and arguments are optional and if not specified an empty
   target will be created.
@@ -86,6 +95,9 @@ The options are:
   :command:`add_custom_command` command calls in the same directory
   (``CMakeLists.txt`` file).  They will be brought up to date when
   the target is built.
+  A target-level dependency is added if any dependency is a byproduct
+  of a target or any of its build events in the same directory to ensure
+  the byproducts will be available before this target is built.
 
   Use the :command:`add_dependencies` command to add dependencies
   on other targets.

Help/command/add_test.rst

@@ -7,7 +7,8 @@ Add a test to the project to be run by :manual:`ctest(1)`.
 
   add_test(NAME <name> COMMAND <command> [<arg>...]
            [CONFIGURATIONS <config>...]
-           [WORKING_DIRECTORY <dir>])
+           [WORKING_DIRECTORY <dir>]
+           [COMMAND_EXPAND_LISTS])
 
 Adds a test called ``<name>``.  The test name may not contain spaces,
 quotes, or other characters special in CMake syntax.  The options are:
@@ -28,12 +29,18 @@ quotes, or other characters special in CMake syntax.  The options are:
   directory set to the build directory corresponding to the
   current source directory.
 
+``COMMAND_EXPAND_LISTS``
+  Lists in ``COMMAND`` arguments will be expanded, including those
+  created with
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
 The given test command is expected to exit with code ``0`` to pass and
 non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test
 property is set.  Any output written to stdout or stderr will be
 captured by :manual:`ctest(1)` but does not affect the pass/fail status
-unless the :prop_test:`PASS_REGULAR_EXPRESSION` or
+unless the :prop_test:`PASS_REGULAR_EXPRESSION`,
-:prop_test:`FAIL_REGULAR_EXPRESSION` test property is used.
+:prop_test:`FAIL_REGULAR_EXPRESSION` or
+:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used.
 
 The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
 expressions" with the syntax ``$<...>``.  See the

Help/command/ctest_coverage.rst

@@ -8,7 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
   ctest_coverage([BUILD <build-dir>] [APPEND]
                  [LABELS <label>...]
                  [RETURN_VALUE <result-var>]
-                 [CAPTURE_CMAKE_ERROR <result-var]
+                 [CAPTURE_CMAKE_ERROR <result-var>]
                  [QUIET]
                  )
 

Help/command/ctest_start.rst

@@ -5,9 +5,9 @@ Starts the testing for a given model
 
 ::
 
-  ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET])
+  ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
 
-  ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET])
+  ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
 
 Starts the testing for a given model.  The command should be called
 after the binary directory is initialized.
@@ -26,20 +26,21 @@ The parameters are as follows:
   Set the binary directory. If not specified, the value of
   :variable:`CTEST_BINARY_DIRECTORY` is used instead.
 
-``TRACK <track>``
+``GROUP <group>``
-  If ``TRACK`` is used, the submissions will go to the specified track on the
+  If ``GROUP`` is used, the submissions will go to the specified group on the
-  CDash server. If no ``TRACK`` is specified, the name of the model is used by
+  CDash server. If no ``GROUP`` is specified, the name of the model is used by
-  default.
+  default. This replaces the deprecated option ``TRACK``. Despite the name
+  change its behavior is unchanged.
 
 ``APPEND``
   If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new
   one based on the current time stamp. If you use ``APPEND``, you can omit the
-  ``<model>`` and ``TRACK <track>`` parameters, because they will be read from
+  ``<model>`` and ``GROUP <group>`` parameters, because they will be read from
   the generated ``TAG`` file. For example:
 
   .. code-block:: cmake
 
-    ctest_start(Experimental TRACK TrackExperimental)
+    ctest_start(Experimental GROUP GroupExperimental)
 
   Later, in another ``ctest -S`` script:
 
@@ -48,11 +49,11 @@ The parameters are as follows:
     ctest_start(APPEND)
 
   When the second script runs ``ctest_start(APPEND)``, it will read the
-  ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file
+  ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file
   generated by the first ``ctest_start()`` command. Please note that if you
-  call ``ctest_start(APPEND)`` and specify a different model or track than
+  call ``ctest_start(APPEND)`` and specify a different model or group than
   in the first ``ctest_start()`` command, a warning will be issued, and the
-  new model and track will be used.
+  new model and group will be used.
 
 ``QUIET``
   If ``QUIET`` is used, CTest will suppress any non-error messages that it
@@ -65,11 +66,11 @@ equivalent:
 
 .. code-block:: cmake
 
-  ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND)
+  ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
 
-  ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary)
+  ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
 
-  ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary)
+  ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
 
 However, for the sake of readability, it is recommended that you order your
 parameters in the order listed at the top of this page.

Help/command/ctest_test.rst

@@ -17,6 +17,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
              [EXCLUDE_FIXTURE_SETUP <regex>]
              [EXCLUDE_FIXTURE_CLEANUP <regex>]
              [PARALLEL_LEVEL <level>]
+             [RESOURCE_SPEC_FILE <file>]
              [TEST_LOAD <threshold>]
              [SCHEDULE_RANDOM <ON|OFF>]
              [STOP_TIME <time-of-day>]
@@ -82,6 +83,11 @@ The options are:
   Specify a positive number representing the number of tests to
   be run in parallel.
 
+``RESOURCE_SPEC_FILE <file>``
+  Specify a
+  :ref:`resource specification file <ctest-resource-specification-file>`. See
+  :ref:`ctest-resource-allocation` for more information.
+
 ``TEST_LOAD <threshold>``
   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

Help/command/enable_language.rst

@@ -1,7 +1,6 @@
 enable_language
 ---------------
-
+Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
-Enable a language (CXX/C/Fortran/etc)
 
 .. code-block:: cmake
 
@@ -10,7 +9,7 @@ Enable a language (CXX/C/Fortran/etc)
 Enables support for the named language in CMake.  This is
 the same as 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``, ``Fortran``, and ``ASM``.
+are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, and ``ASM``.
 
 If enabling ``ASM``, enable it last so that CMake can check whether
 compilers for other languages like ``C`` work for assembly too.

Help/command/file.rst

@@ -13,6 +13,7 @@ Synopsis
     file(`STRINGS`_ <filename> <out-var> [...])
     file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
     file(`TIMESTAMP`_ <filename> <out-var> [...])
+    file(`GET_RUNTIME_DEPENDENCIES`_ [...])
 
   `Writing`_
     file({`WRITE`_ | `APPEND`_} <filename> <content>...)
@@ -130,6 +131,273 @@ timestamp variable will be set to the empty string ("").
 See the :command:`string(TIMESTAMP)` command for documentation of
 the ``<format>`` and ``UTC`` options.
 
+.. _GET_RUNTIME_DEPENDENCIES:
+
+.. code-block:: cmake
+
+  file(GET_RUNTIME_DEPENDENCIES
+    [RESOLVED_DEPENDENCIES_VAR <deps_var>]
+    [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
+    [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
+    [EXECUTABLES [<executable_files>...]]
+    [LIBRARIES [<library_files>...]]
+    [MODULES [<module_files>...]]
+    [DIRECTORIES [<directories>...]]
+    [BUNDLE_EXECUTABLE <bundle_executable_file>]
+    [PRE_INCLUDE_REGEXES [<regexes>...]]
+    [PRE_EXCLUDE_REGEXES [<regexes>...]]
+    [POST_INCLUDE_REGEXES [<regexes>...]]
+    [POST_EXCLUDE_REGEXES [<regexes>...]]
+    )
+
+Recursively get the list of libraries depended on by the given files.
+
+Please note that this sub-command is not intended to be used in project mode.
+Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)`
+block. For example:
+
+.. code-block:: cmake
+
+  install(CODE [[
+    file(GET_RUNTIME_DEPENDENCIES
+      # ...
+      )
+    ]])
+
+The arguments are as follows:
+
+``RESOLVED_DEPENDENCIES_VAR <deps_var>``
+  Name of the variable in which to store the list of resolved dependencies.
+
+``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>``
+  Name of the variable in which to store the list of unresolved dependencies.
+  If this variable is not specified, and there are any unresolved dependencies,
+  an error is issued.
+
+``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>``
+  Variable prefix in which to store conflicting dependency information.
+  Dependencies are conflicting if two files with the same name are found in
+  two different directories. The list of filenames that conflict are stored in
+  ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths
+  that were found for that filename are stored in
+  ``<conflicting_deps_prefix>_<filename>``.
+
+``EXECUTABLES <executable_files>``
+  List of executable files to read for dependencies. These are executables that
+  are typically created with :command:`add_executable`, but they do not have to
+  be created by CMake. On Apple platforms, the paths to these files determine
+  the value of ``@executable_path`` when recursively resolving the libraries.
+  Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here
+  will result in undefined behavior.
+
+``LIBRARIES <library_files>``
+  List of library files to read for dependencies. These are libraries that are
+  typically created with :command:`add_library(SHARED)`, but they do not have
+  to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE``
+  libraries, or executables here will result in undefined behavior.
+
+``MODULES <module_files>``
+  List of loadable module files to read for dependencies. These are modules
+  that are typically created with :command:`add_library(MODULE)`, but they do
+  not have to be created by CMake. They are typically used by calling
+  ``dlopen()`` at runtime rather than linked at link time with ``ld -l``.
+  Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here
+  will result in undefined behavior.
+
+``DIRECTORIES <directories>``
+  List of additional directories to search for dependencies. On Linux
+  platforms, these directories are searched if the dependency is not found in
+  any of the other usual paths. If it is found in such a directory, a warning
+  is issued, because it means that the file is incomplete (it does not list all
+  of the directories that contain its dependencies). On Windows platforms,
+  these directories are searched if the dependency is not found in any of the
+  other search paths, but no warning is issued, because searching other paths
+  is a normal part of Windows dependency resolution. On Apple platforms, this
+  argument has no effect.
+
+``BUNDLE_EXECUTABLE <bundle_executable_file>``
+  Executable to treat as the "bundle executable" when resolving libraries. On
+  Apple platforms, this argument determines the value of ``@executable_path``
+  when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files.
+  It has no effect on ``EXECUTABLES`` files. On other platforms, it has no
+  effect. This is typically (but not always) one of the executables in the
+  ``EXECUTABLES`` argument which designates the "main" executable of the
+  package.
+
+The following arguments specify filters for including or excluding libraries to
+be resolved. See below for a full description of how they work.
+
+``PRE_INCLUDE_REGEXES <regexes>``
+  List of pre-include regexes through which to filter the names of
+  not-yet-resolved dependencies.
+
+``PRE_EXCLUDE_REGEXES <regexes>``
+  List of pre-exclude regexes through which to filter the names of
+  not-yet-resolved dependencies.
+
+``POST_INCLUDE_REGEXES <regexes>``
+  List of post-include regexes through which to filter the names of resolved
+  dependencies.
+
+``POST_EXCLUDE_REGEXES <regexes>``
+  List of post-exclude regexes through which to filter the names of resolved
+  dependencies.
+
+These arguments can be used to blacklist unwanted system libraries when
+resolving the dependencies, or to whitelist libraries from a specific
+directory. The filtering works as follows:
+
+1. If the not-yet-resolved dependency matches any of the
+   ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
+   resolution proceeds to step 4.
+2. If the not-yet-resolved dependency matches any of the
+   ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.
+3. Otherwise, dependency resolution proceeds.
+4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to
+   the linking rules of the platform (see below).
+5. If the dependency is found, and its full path matches one of the
+   ``POST_INCLUDE_REGEXES``, the full path is added to the resolved
+   dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves
+   that library's own dependencies. Otherwise, resolution proceeds to step 6.
+6. If the dependency is found, but its full path matches one of the
+   ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and
+   dependency resolution stops for that dependency.
+7. If the dependency is found, and its full path does not match either
+   ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added
+   to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
+   recursively resolves that library's own dependencies.
+
+Different platforms have different rules for how dependencies are resolved.
+These specifics are described here.
+
+On Linux platforms, library resolution works as follows:
+
+1. If the depending file does not have any ``RUNPATH`` entries, and the library
+   exists in one of the depending file's ``RPATH`` entries, or its parents', in
+   that order, the dependency is resolved to that file.
+2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
+   library exists in one of those entries, the dependency is resolved to that
+   file.
+3. Otherwise, if the library exists in one of the directories listed by
+   ``ldconfig``, the dependency is resolved to that file.
+4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the
+   dependency is resolved to that file. In this case, a warning is issued,
+   because finding a file in one of the ``DIRECTORIES`` means that the
+   depending file is not complete (it does not list all the directories from
+   which it pulls dependencies).
+5. Otherwise, the dependency is unresolved.
+
+On Windows platforms, library resolution works as follows:
+
+1. The dependent DLL name is converted to lowercase. Windows DLL names are
+   case-insensitive, and some linkers mangle the case of the DLL dependency
+   names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``,
+   ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and
+   ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would
+   have to check for both uppercase and lowercase letters. For example:
+
+   .. code-block:: cmake
+
+     file(GET_RUNTIME_DEPENDENCIES
+       # ...
+       PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
+       )
+
+   Converting the DLL name to lowercase allows the regexes to only match
+   lowercase names, thus simplifying the regex. For example:
+
+   .. code-block:: cmake
+
+     file(GET_RUNTIME_DEPENDENCIES
+       # ...
+       PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
+       )
+
+   This regex will match ``mylibrary.dll`` regardless of how it is cased,
+   either on disk or in the depending file. (For example, it will match
+   ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)
+
+   Please note that the directory portion of any resolved DLLs retains its
+   casing and is not converted to lowercase. Only the filename portion is
+   converted.
+
+2. (**Not yet implemented**) If the depending file is a Windows Store app, and
+   the dependency is listed as a dependency in the application's package
+   manifest, the dependency is resolved to that file.
+3. Otherwise, if the library exists in the same directory as the depending
+   file, the dependency is resolved to that file.
+4. Otherwise, if the library exists in either the operating system's
+   ``system32`` directory or the ``Windows`` directory, in that order, the
+   dependency is resolved to that file.
+5. Otherwise, if the library exists in one of the directories specified by
+   ``DIRECTORIES``, in the order they are listed, the dependency is resolved to
+   that file. In this case, a warning is not issued, because searching other
+   directories is a normal part of Windows library resolution.
+6. Otherwise, the dependency is unresolved.
+
+On Apple platforms, library resolution works as follows:
+
+1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES``
+   argument is in the process of being resolved, and replacing
+   ``@executable_path/`` with the directory of the executable yields an
+   existing file, the dependency is resolved to that file.
+2. Otherwise, if the dependency starts with ``@executable_path/``, and there is
+   a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with
+   the directory of the bundle executable yields an existing file, the
+   dependency is resolved to that file.
+3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
+   ``@loader_path/`` with the directory of the depending file yields an
+   existing file, the dependency is resolved to that file.
+4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
+   ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields
+   an existing file, the dependency is resolved to that file. Note that
+   ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/``
+   also have these items replaced with the appropriate path.
+5. Otherwise, if the dependency is an absolute file that exists, the dependency
+   is resolved to that file.
+6. Otherwise, the dependency is unresolved.
+
+This function accepts several variables that determine which tool is used for
+dependency resolution:
+
+.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
+
+  Determines which operating system and executable format the files are built
+  for. This could be one of several values:
+
+  * ``linux+elf``
+  * ``windows+pe``
+  * ``macos+macho``
+
+  If this variable is not specified, it is determined automatically by system
+  introspection.
+
+.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
+
+  Determines the tool to use for dependency resolution. It could be one of
+  several values, depending on the value of
+  :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:
+
+  ================================================= =============================================
+     ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM``       ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
+  ================================================= =============================================
+  ``linux+elf``                                     ``objdump``
+  ``windows+pe``                                    ``dumpbin``
+  ``windows+pe``                                    ``objdump``
+  ``macos+macho``                                   ``otool``
+  ================================================= =============================================
+
+  If this variable is not specified, it is determined automatically by system
+  introspection.
+
+.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
+
+  Determines the path to the tool to use for dependency resolution. This is the
+  actual path to ``objdump``, ``dumpbin``, or ``otool``.
+
+  If this variable is not specified, it is determined automatically by system
+  introspection.
+
 Writing
 ^^^^^^^
 
@@ -235,6 +503,11 @@ regular expressions, but much simpler.  If ``RELATIVE`` flag is
 specified, the results will be returned as relative paths to the given
 path.  The results will be ordered lexicographically.
 
+On Windows and macOS, globbing is case-insensitive even if the underlying
+filesystem is case-sensitive (both filenames and globbing expressions are
+converted to lowercase before matching).  On other platforms, globbing is
+case-sensitive.
+
 If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic
 to the main build system check target to rerun the flagged ``GLOB`` commands
 at build time. If any of the outputs change, CMake will regenerate the build

Help/command/find_file.rst

@@ -17,11 +17,10 @@ find_file
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
-   On Windows hosts:
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
-   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+      ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
+      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
-   directories in ``PATH`` itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`

Help/command/find_library.rst

@@ -17,11 +17,10 @@ find_library
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
-   On Windows hosts:
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
-   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
+      ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-   and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
+      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
-   and the directories in ``PATH`` itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,

Help/command/find_package.rst

@@ -81,6 +81,7 @@ The complete Config mode command signature is
 
   find_package(<PackageName> [version] [EXACT] [QUIET]
                [REQUIRED] [[COMPONENTS] [components...]]
+               [OPTIONAL_COMPONENTS components...]
                [CONFIG|NO_MODULE]
                [NO_POLICY_SCOPE]
                [NAMES name1 [name2 ...]]
@@ -293,13 +294,15 @@ enabled.
    The package root variables are maintained as a stack so if
    called from within a find module, root paths from the parent's find
    module will also be searched after paths for the current package.
-   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
+   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
+   the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
    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``.
    The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
-   This can be skipped if ``NO_CMAKE_PATH`` is passed::
+   This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``::
 
      CMAKE_PREFIX_PATH
      CMAKE_FRAMEWORK_PATH
@@ -309,7 +312,8 @@ enabled.
    These are intended to be set in the user's shell configuration,
    and therefore use the host's native path separator
    (``;`` on Windows and ``:`` on UNIX).
-   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed::
+   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting
+   the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``::
 
      <PackageName>_DIR
      CMAKE_PREFIX_PATH
@@ -322,7 +326,8 @@ enabled.
    be specified with the ``PATHS`` option.
 
 5. Search the standard system environment variables.  This can be
-   skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed.  Path entries
+   skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed  or by setting the
+   :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries
    ending in ``/bin`` or ``/sbin`` are automatically converted to their
    parent directories::
 
@@ -330,14 +335,17 @@ enabled.
 
 6. Search paths stored in the CMake :ref:`User Package Registry`.
    This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
-   setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
+   setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`
-   to ``TRUE``.
+   to ``FALSE`` or the deprecated variable
+   :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``.
+
    See the :manual:`cmake-packages(7)` manual for details on the user
    package registry.
 
 7. Search cmake variables defined in the Platform files for the
    current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
-   passed::
+   passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
+   to ``FALSE``::
 
      CMAKE_SYSTEM_PREFIX_PATH
      CMAKE_SYSTEM_FRAMEWORK_PATH
@@ -345,8 +353,10 @@ enabled.
 
 8. Search paths stored in the CMake :ref:`System Package Registry`.
    This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
-   or by setting the
+   or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`
+   variable to ``FALSE`` or the deprecated variable
    :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
+
    See the :manual:`cmake-packages(7)` manual for details on the system
    package registry.
 

Help/command/find_path.rst

@@ -17,11 +17,10 @@ find_path
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
-   On Windows hosts:
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
-   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+      ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
+      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
-   directories in ``PATH`` itself.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`

Help/command/find_program.rst

@@ -15,7 +15,8 @@ find_program
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH``
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|

Help/command/if.rst

@@ -29,6 +29,8 @@ If used, it must be a verbatim
 repeat of the argument of the opening
 ``if`` command.
 
+.. _`Condition Syntax`:
+
 Condition Syntax
 ^^^^^^^^^^^^^^^^
 

Help/command/install.rst

@@ -126,6 +126,8 @@ project.  There are several kinds of target files that may be installed:
   marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK``
   below.) For DLL platforms (all Windows-based systems including
   Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
+  On AIX, the linker import file created for executables with
+  :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target.
 
 ``LIBRARY``
   Module libraries are always treated as ``LIBRARY`` targets. For non-

Help/command/list.rst

@@ -180,7 +180,7 @@ Insert elements to the 0th position in the list.
 
   list(REMOVE_ITEM <list> <value> [<value> ...])
 
-Removes the given items from the list.
+Removes all instances of the given items from the list.
 
 .. _REMOVE_AT:
 

Help/command/load_cache.rst

@@ -5,7 +5,7 @@ Load in the values from another project's CMake cache.
 
 .. code-block:: cmake
 
-  load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...)
+  load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
 
 Reads the cache and store the requested entries in variables with their
 name prefixed with the given prefix.  This only reads the values, and
@@ -13,7 +13,7 @@ does not create entries in the local project's cache.
 
 .. code-block:: cmake
 
-  load_cache(pathToCacheFile [EXCLUDE entry1...]
+  load_cache(pathToBuildDirectory [EXCLUDE entry1...]
              [INCLUDE_INTERNALS entry1...])
 
 Loads in the values from another cache and store them in the local

Help/command/math.rst

@@ -8,7 +8,8 @@ Evaluate a mathematical expression.
   math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
 
 Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
-resulting value.
+resulting value.  The result of the expression must be representable as a
+64-bit signed integer.
 
 The mathematical expression must be given as a string (i.e. enclosed in
 double quotation marks). An example is ``"5 * (10 + 13)"``.

Help/command/message.rst

@@ -57,9 +57,14 @@ 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 ``--loglevel`` command-line option to each of
+interactive pop-up box.  The ``--log-level`` command-line option to each of
 these tools can be used to control which messages will be shown.
 
+Messages of log levels ``NOTICE`` and below will also have each line preceded
+by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
+a single string by concatenating its list items).  For ``STATUS`` to ``TRACE``
+messages, this indenting content will be inserted after the hyphens.
+
 CMake Warning and Error message text displays using a simple markup
 language.  Non-indented text is formatted in line-wrapped paragraphs
 delimited by newlines.  Indented text is considered pre-formatted.

Help/command/project.rst

@@ -87,7 +87,8 @@ The options are:
   Can also be specified without ``LANGUAGES`` keyword per the first, short signature.
 
   Selects which programming languages are needed to build the project.
-  Supported languages include ``C``, ``CXX`` (i.e.  C++), ``CUDA``, ``Fortran``, and ``ASM``.
+  Supported languages include ``C``, ``CXX`` (i.e.  C++), ``CUDA``,
+  ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, and ``ASM``.
   By default ``C`` and ``CXX`` are enabled if no language options are given.
   Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
   to skip enabling any languages.

Help/command/string.rst

@@ -22,8 +22,8 @@ Synopsis
     string(`PREPEND`_ <string-var> [<input>...])
     string(`CONCAT`_ <out-var> [<input>...])
     string(`JOIN`_ <glue> <out-var> [<input>...])
-    string(`TOLOWER`_ <string1> <out-var>)
+    string(`TOLOWER`_ <string> <out-var>)
-    string(`TOUPPER`_ <string1> <out-var>)
+    string(`TOUPPER`_ <string> <out-var>)
     string(`LENGTH`_ <string> <out-var>)
     string(`SUBSTRING`_ <string> <begin> <length> <out-var>)
     string(`STRIP`_ <string> <out-var>)
@@ -38,7 +38,7 @@ Synopsis
 
   `Generation`_
     string(`ASCII`_ <number>... <out-var>)
-    string(`CONFIGURE`_ <string1> <out-var> [...])
+    string(`CONFIGURE`_ <string> <out-var> [...])
     string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
     string(`RANDOM`_ [<option>...] <out-var>)
     string(`TIMESTAMP`_ <out-var> [<format string>] [UTC])
@@ -51,23 +51,28 @@ Search and Replace
 
 .. code-block:: cmake
 
-  string(FIND <string> <substring> <output variable> [REVERSE])
+  string(FIND <string> <substring> <output_variable> [REVERSE])
 
-Return the position where the given substring was found in
+Return the position where the given ``<substring>`` was found in
-the supplied string.  If the ``REVERSE`` flag was used, the command will
+the supplied ``<string>``.  If the ``REVERSE`` flag was used, the command will
 search for the position of the last occurrence of the specified
-substring.  If the substring is not found, a position of -1 is returned.
+``<substring>``.  If the ``<substring>`` is not found, a position of -1 is
+returned.
+
+The ``string(FIND)`` subcommand treats all strings as ASCII-only characters.
+The index stored in ``<output_variable>`` will also be counted in bytes,
+so strings containing multi-byte characters may lead to unexpected results.
 
 .. _REPLACE:
 
 .. code-block:: cmake
 
   string(REPLACE <match_string>
-         <replace_string> <output variable>
+         <replace_string> <output_variable>
          <input> [<input>...])
 
-Replace all occurrences of ``match_string`` in the input
+Replace all occurrences of ``<match_string>`` in the ``<input>``
-with ``replace_string`` and store the result in the output.
+with ``<replace_string>`` and store the result in the ``<output_variable>``.
 
 Regular Expressions
 ^^^^^^^^^^^^^^^^^^^
@@ -77,9 +82,10 @@ Regular Expressions
 .. code-block:: cmake
 
   string(REGEX MATCH <regular_expression>
-         <output variable> <input> [<input>...])
+         <output_variable> <input> [<input>...])
 
-Match the regular expression once and store the match in the output variable.
+Match the ``<regular_expression>`` once and store the match in the
+``<output_variable>``.
 All ``<input>`` arguments are concatenated before matching.
 
 .. _`REGEX MATCHALL`:
@@ -87,10 +93,10 @@ All ``<input>`` arguments are concatenated before matching.
 .. code-block:: cmake
 
   string(REGEX MATCHALL <regular_expression>
-         <output variable> <input> [<input>...])
+         <output_variable> <input> [<input>...])
 
-Match the regular expression as many times as possible and store the matches
+Match the ``<regular_expression>`` as many times as possible and store the
-in the output variable as a list.
+matches in the ``<output_variable>`` as a list.
 All ``<input>`` arguments are concatenated before matching.
 
 .. _`REGEX REPLACE`:
@@ -98,16 +104,17 @@ All ``<input>`` arguments are concatenated before matching.
 .. code-block:: cmake
 
   string(REGEX REPLACE <regular_expression>
-         <replace_expression> <output variable>
+         <replacement_expression> <output_variable>
          <input> [<input>...])
 
-Match the regular expression as many times as possible and substitute the
+Match the ``<regular_expression>`` as many times as possible and substitute
-replacement expression for the match in the output.
+the ``<replacement_expression>`` for the match in the output.
 All ``<input>`` arguments are concatenated before matching.
 
-The replace expression may refer to paren-delimited subexpressions of the
+The ``<replacement_expression>`` may refer to parenthesis-delimited
-match using ``\1``, ``\2``, ..., ``\9``.  Note that two backslashes (``\\1``)
+subexpressions of the match using ``\1``, ``\2``, ..., ``\9``.  Note that
-are required in CMake code to get a backslash through argument parsing.
+two backslashes (``\\1``) are required in CMake code to get a backslash
+through argument parsing.
 
 .. _`Regex Specification`:
 
@@ -180,103 +187,109 @@ Manipulation
 
 .. code-block:: cmake
 
-  string(APPEND <string variable> [<input>...])
+  string(APPEND <string_variable> [<input>...])
 
-Append all the input arguments to the string.
+Append all the ``<input>`` arguments to the string.
 
 .. _PREPEND:
 
 .. code-block:: cmake
 
-  string(PREPEND <string variable> [<input>...])
+  string(PREPEND <string_variable> [<input>...])
 
-Prepend all the input arguments to the string.
+Prepend all the ``<input>`` arguments to the string.
 
 .. _CONCAT:
 
 .. code-block:: cmake
 
-  string(CONCAT <output variable> [<input>...])
+  string(CONCAT <output_variable> [<input>...])
 
-Concatenate all the input arguments together and store
+Concatenate all the ``<input>`` arguments together and store
-the result in the named output variable.
+the result in the named ``<output_variable>``.
 
 .. _JOIN:
 
 .. code-block:: cmake
 
-  string(JOIN <glue> <output variable> [<input>...])
+  string(JOIN <glue> <output_variable> [<input>...])
 
-Join all the input arguments together using the glue
+Join all the ``<input>`` arguments together using the ``<glue>``
-string and store the result in the named output variable.
+string and store the result in the named ``<output_variable>``.
 
-To join list's elements, use preferably the ``JOIN`` operator
+To join a list's elements, prefer to use the ``JOIN`` operator
-from :command:`list` command. This allows for the elements to have
+from the :command:`list` command.  This allows for the elements to have
 special characters like ``;`` in them.
 
 .. _TOLOWER:
 
 .. code-block:: cmake
 
-  string(TOLOWER <string1> <output variable>)
+  string(TOLOWER <string> <output_variable>)
 
-Convert string to lower characters.
+Convert ``<string>`` to lower characters.
 
 .. _TOUPPER:
 
 .. code-block:: cmake
 
-  string(TOUPPER <string1> <output variable>)
+  string(TOUPPER <string> <output_variable>)
 
-Convert string to upper characters.
+Convert ``<string>`` to upper characters.
 
 .. _LENGTH:
 
 .. code-block:: cmake
 
-  string(LENGTH <string> <output variable>)
+  string(LENGTH <string> <output_variable>)
 
-Store in an output variable a given string's length.
+Store in an ``<output_variable>`` a given string's length in bytes.
+Note that this means if ``<string>`` contains multi-byte characters, the
+result stored in ``<output_variable>`` will *not* be the number of characters.
 
 .. _SUBSTRING:
 
 .. code-block:: cmake
 
-  string(SUBSTRING <string> <begin> <length> <output variable>)
+  string(SUBSTRING <string> <begin> <length> <output_variable>)
 
-Store in an output variable a substring of a given string.  If length is
+Store in an ``<output_variable>`` a substring of a given ``<string>``.  If
-``-1`` the remainder of the string starting at begin will be returned.
+``<length>`` is ``-1`` the remainder of the string starting at ``<begin>``
-If string is shorter than length then end of string is used instead.
+will be returned.  If ``<string>`` is shorter than ``<length>`` then the
+end of the string is used instead.
+
+Both ``<begin>`` and ``<length>`` are counted in bytes, so care must
+be exercised if ``<string>`` could contain multi-byte characters.
 
 .. note::
-  CMake 3.1 and below reported an error if length pointed past
+  CMake 3.1 and below reported an error if ``<length>`` pointed past
-  the end of string.
+  the end of ``<string>``.
 
 .. _STRIP:
 
 .. code-block:: cmake
 
-  string(STRIP <string> <output variable>)
+  string(STRIP <string> <output_variable>)
 
-Store in an output variable a substring of a given string with leading and
+Store in an ``<output_variable>`` a substring of a given ``<string>`` with
-trailing spaces removed.
+leading and trailing spaces removed.
 
 .. _GENEX_STRIP:
 
 .. code-block:: cmake
 
-  string(GENEX_STRIP <input string> <output variable>)
+  string(GENEX_STRIP <string> <output_variable>)
 
 Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
-from the ``input string`` and store the result in the ``output variable``.
+from the input ``<string>`` and store the result in the ``<output_variable>``.
 
 .. _REPEAT:
 
 .. code-block:: cmake
 
-  string(REPEAT <input string> <count> <output variable>)
+  string(REPEAT <string> <count> <output_variable>)
 
-Produce the output string as repetion of ``input string`` ``count`` times.
+Produce the output string as the input ``<string>`` repeated ``<count>`` times.
 
 Comparison
 ^^^^^^^^^^
@@ -285,14 +298,14 @@ Comparison
 
 .. code-block:: cmake
 
-  string(COMPARE LESS <string1> <string2> <output variable>)
+  string(COMPARE LESS <string1> <string2> <output_variable>)
-  string(COMPARE GREATER <string1> <string2> <output variable>)
+  string(COMPARE GREATER <string1> <string2> <output_variable>)
-  string(COMPARE EQUAL <string1> <string2> <output variable>)
+  string(COMPARE EQUAL <string1> <string2> <output_variable>)
-  string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
+  string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
-  string(COMPARE LESS_EQUAL <string1> <string2> <output variable>)
+  string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
-  string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>)
+  string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
 
-Compare the strings and store true or false in the output variable.
+Compare the strings and store true or false in the ``<output_variable>``.
 
 .. _`Supported Hash Algorithms`:
 
@@ -303,9 +316,9 @@ Hashing
 
 .. code-block:: cmake
 
-  string(<HASH> <output variable> <input>)
+  string(<HASH> <output_variable> <input>)
 
-Compute a cryptographic hash of the input string.
+Compute a cryptographic hash of the ``<input>`` string.
 The supported ``<HASH>`` algorithm names are:
 
 ``MD5``
@@ -336,7 +349,7 @@ Generation
 
 .. code-block:: cmake
 
-  string(ASCII <number> [<number> ...] <output variable>)
+  string(ASCII <number> [<number> ...] <output_variable>)
 
 Convert all numbers into corresponding ASCII characters.
 
@@ -344,31 +357,31 @@ Convert all numbers into corresponding ASCII characters.
 
 .. code-block:: cmake
 
-  string(CONFIGURE <string1> <output variable>
+  string(CONFIGURE <string> <output_variable>
          [@ONLY] [ESCAPE_QUOTES])
 
-Transform a string like :command:`configure_file` transforms a file.
+Transform a ``<string>`` like :command:`configure_file` transforms a file.
 
 .. _MAKE_C_IDENTIFIER:
 
 .. code-block:: cmake
 
-  string(MAKE_C_IDENTIFIER <input string> <output variable>)
+  string(MAKE_C_IDENTIFIER <string> <output_variable>)
 
-Convert each non-alphanumeric character in the ``<input string>`` to an
+Convert each non-alphanumeric character in the input ``<string>`` to an
-underscore and store the result in the ``<output variable>``.  If the first
+underscore and store the result in the ``<output_variable>``.  If the first
-character of the string is a digit, an underscore will also be prepended to
+character of the ``<string>`` is a digit, an underscore will also be prepended
-the result.
+to the result.
 
 .. _RANDOM:
 
 .. code-block:: cmake
 
   string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
-         [RANDOM_SEED <seed>] <output variable>)
+         [RANDOM_SEED <seed>] <output_variable>)
 
-Return a random string of given length consisting of
+Return a random string of given ``<length>`` consisting of
-characters from the given alphabet.  Default length is 5 characters
+characters from the given ``<alphabet>``.  Default length is 5 characters
 and default alphabet is all numbers and upper and lower case letters.
 If an integer ``RANDOM_SEED`` is given, its value will be used to seed the
 random number generator.
@@ -377,18 +390,18 @@ random number generator.
 
 .. code-block:: cmake
 
-  string(TIMESTAMP <output variable> [<format string>] [UTC])
+  string(TIMESTAMP <output_variable> [<format_string>] [UTC])
 
 Write a string representation of the current date
-and/or time to the output variable.
+and/or time to the ``<output_variable>``.
 
-Should the command be unable to obtain a timestamp the output variable
+If the command is unable to obtain a timestamp, the ``<output_variable>``
-will be set to the empty string "".
+will be set to the empty string ``""``.
 
 The optional ``UTC`` flag requests the current date/time representation to
 be in Coordinated Universal Time (UTC) rather than local time.
 
-The optional ``<format string>`` may contain the following format
+The optional ``<format_string>`` may contain the following format
 specifiers:
 
 ::
@@ -415,7 +428,7 @@ specifiers:
 Unknown format specifiers will be ignored and copied to the output
 as-is.
 
-If no explicit ``<format string>`` is given it will default to:
+If no explicit ``<format_string>`` is given, it will default to:
 
 ::
 
@@ -432,7 +445,7 @@ If no explicit ``<format string>`` is given it will default to:
 
 .. code-block:: cmake
 
-  string(UUID <output variable> NAMESPACE <namespace> NAME <name>
+  string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
          TYPE <MD5|SHA1> [UPPER])
 
 Create a universally unique identifier (aka GUID) as per RFC4122
@@ -441,6 +454,6 @@ based on the hash of the combined values of ``<namespace>``
 The hash algorithm can be either ``MD5`` (Version 3 UUID) or
 ``SHA1`` (Version 5 UUID).
 A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
-where each `x` represents a lower case hexadecimal character.
+where each ``x`` represents a lower case hexadecimal character.
-Where required an uppercase representation can be requested
+Where required, an uppercase representation can be requested
 with the optional ``UPPER`` flag.

Help/command/target_precompile_headers.rst

@@ -0,0 +1,124 @@
+target_precompile_headers
+-------------------------
+
+Add a list of header files to precompile.
+
+Precompiling header files can speed up compilation by creating a partially
+processed version of some header files, and then using that version during
+compilations rather than repeatedly parsing the original headers.
+
+Main Form
+^^^^^^^^^
+
+.. code-block:: cmake
+
+  target_precompile_headers(<target>
+    <INTERFACE|PUBLIC|PRIVATE> [header1...]
+    [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
+
+The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or
+:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``.
+The named ``<target>`` must have been created by a command such as
+:command:`add_executable` or :command:`add_library` and must not be an
+:ref:`ALIAS target <Alias Targets>`.
+
+The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
+specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
+items will populate the :prop_tgt:`PRECOMPILE_HEADERS` 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.
+
+Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets
+that will be :ref:`exported <install(EXPORT)>`, or they should at least use
+the ``$<BUILD_INTERFACE:...>`` generator expression to prevent precompile
+headers from appearing in an installed exported target.  Consumers of a target
+should typically be in control of what precompile headers they use, not have
+precompile headers forced on them by the targets being consumed (since
+precompile headers are not typically usage requirements).  A notable exception
+to this is where an :ref:`interface library <Interface Libraries>` is created
+to define a commonly used set of precompile headers in one place and then other
+targets link to that interface library privately.  In this case, the interface
+library exists specifically to propagate the precompile headers to its
+consumers and the consumer is effectively still in control, since it decides
+whether to link to the interface library or not.
+
+The list of header files is used to generate a header file named
+``cmake_pch.h|xx`` which is used to generate the precompiled header file
+(``.pch``, ``.gch``, ``.pchi``) artifact.  The ``cmake_pch.h|xx`` header
+file will be force included (``-include`` for GCC, ``/FI`` for MSVC) to
+all source files, so sources do not need to have ``#include "pch.h"``.
+
+Header file names specified with angle brackets (e.g. ``<unordered_map>``) or
+explicit double quotes (escaped for the :manual:`cmake-language(7)`,
+e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
+must be available for the compiler to find them.  Other header file names
+(e.g. ``project_header.h``) are interpreted as being relative to the current
+source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
+included by absolute path.
+
+Arguments to ``target_precompile_headers()`` may use "generator expressions"
+with the syntax ``$<...>``.
+See the :manual:`cmake-generator-expressions(7)` manual for available
+expressions.  See the :manual:`cmake-compile-features(7)` manual for
+information on compile features and a list of supported compilers.
+The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
+useful for specifying a language-specific header to precompile for
+only one language (e.g. ``CXX`` and not ``C``).  For example:
+
+.. code-block:: cmake
+
+  target_precompile_headers(myTarget
+    PUBLIC
+      project_header.h
+      "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>"
+    PRIVATE
+      [["other_header.h"]]
+      <unordered_map>
+  )
+
+When specifying angle brackets inside a :manual:`generator expression
+<cmake-generator-expressions(7)>`, be sure to encode the closing ``>``
+as ``$<ANGLE-R>``.  For example:
+
+.. code-block:: cmake
+
+  target_precompile_headers(mylib PRIVATE
+    "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
+    "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
+  )
+
+
+Reusing Precompile Headers
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The command also supports a second signature which can be used to specify that
+one target re-uses a precompiled header file artefact from another target
+instead of generating its own:
+
+.. code-block:: cmake
+
+  target_precompile_headers(<target> REUSE_FROM <other_target>)
+
+This form sets the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` property to
+``<other_target>`` and adds a dependency such that ``<target>`` will depend
+on ``<other_target>``.  CMake will halt with an error if the
+:prop_tgt:`PRECOMPILE_HEADERS` property of ``<target>`` is already set when
+the ``REUSE_FROM`` form is used.
+
+.. note::
+
+  The ``REUSE_FROM`` form requires the same set of compiler options,
+  compiler flags and compiler definitions for both ``<target>`` and
+  ``<other_target>``.  Some compilers (e.g. GCC) may issue a warning if the
+  precompiled header file cannot be used (``-Winvalid-pch``).
+
+See Also
+^^^^^^^^
+
+To disable precompile headers for specific targets, see the
+:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property.
+
+To prevent precompile headers from being used when compiling a specific
+source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property.

Help/command/try_compile.rst

@@ -103,15 +103,18 @@ The options are:
 
 ``<LANG>_STANDARD <std>``
   Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`,
+  :prop_tgt:`OBJC_STANDARD`, :prop_tgt:`OBJCXX_STANDARD`,
   or :prop_tgt:`CUDA_STANDARD` target property of the generated project.
 
 ``<LANG>_STANDARD_REQUIRED <bool>``
   Specify the :prop_tgt:`C_STANDARD_REQUIRED`,
-  :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED`
+  :prop_tgt:`CXX_STANDARD_REQUIRED`, :prop_tgt:`OBJC_STANDARD_REQUIRED`,
+  :prop_tgt:`OBJCXX_STANDARD_REQUIRED`,or :prop_tgt:`CUDA_STANDARD_REQUIRED`
   target property of the generated project.
 
 ``<LANG>_EXTENSIONS <bool>``
   Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`,
+  :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
@@ -171,6 +174,12 @@ then the language standard variables are honored:
 * :variable:`CMAKE_CXX_STANDARD`
 * :variable:`CMAKE_CXX_STANDARD_REQUIRED`
 * :variable:`CMAKE_CXX_EXTENSIONS`
+* :variable:`CMAKE_OBJC_STANDARD`
+* :variable:`CMAKE_OBJC_STANDARD_REQUIRED`
+* :variable:`CMAKE_OBJC_EXTENSIONS`
+* :variable:`CMAKE_OBJCXX_STANDARD`
+* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED`
+* :variable:`CMAKE_OBJCXX_EXTENSIONS`
 * :variable:`CMAKE_CUDA_STANDARD`
 * :variable:`CMAKE_CUDA_STANDARD_REQUIRED`
 * :variable:`CMAKE_CUDA_EXTENSIONS`

Help/cpack_gen/archive.rst

@@ -9,6 +9,7 @@ different formats:
   - TGZ (.tar.gz)
   - TXZ (.tar.xz)
   - TZ (.tar.Z)
+  - TZST (.tar.zst)
   - ZIP (.zip)
 
 Variables specific to CPack Archive generator

Help/cpack_gen/deb.rst

@@ -179,16 +179,24 @@ List of CPack DEB generator specific variables:
  * Default   : ``CPACK_PACKAGE_CONTACT``
 
 .. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
-              CPACK_COMPONENT_<COMPONENT>_DESCRIPTION
+              CPACK_DEBIAN_<COMPONENT>_DESCRIPTION
 
  The Debian package description
 
  * Mandatory : YES
  * Default   :
 
-   - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set or
+   - :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component
-   - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`
+     based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or
+   - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component
+     based installers only) if set, or :variable:`CPACK_PACKAGE_DESCRIPTION` if set, or
+   - content of the file specified in :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` if set
 
+ If after that description is not set, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` going to be
+ used if set. Otherwise, :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` will be added as the first
+ line of description as defined in `Debian Policy Manual`_.
+
+.. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description
 
 .. variable:: CPACK_DEBIAN_PACKAGE_SECTION
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION

Help/cpack_gen/wix.rst

@@ -95,6 +95,10 @@ Windows using WiX.
 
  If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME
 
+ If this variable is set to ``.``, then application shortcuts will be
+ created directly in the start menu and the uninstaller shortcut will be
+ omitted.
+
 .. variable:: CPACK_WIX_CULTURES
 
  Language(s) of the installer

Help/dev/maint.rst

@@ -92,6 +92,45 @@ Publish both ``master`` and ``release`` simultaneously:
 .. _`CMake Review Process`: review.rst
 .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
 
+Create Release Version
+======================
+
+When the ``release`` branch is ready to create a new release, follow the
+steps in the above `Maintain Current Release`_ section to checkout a local
+``release-$ver`` branch, where ``$ver`` is the version number of the
+current release in the form ``$major.$minor``.
+
+Edit ``Source/CMakeVersion.cmake`` to set the full version:
+
+.. code-block:: cmake
+
+  # CMake version number components.
+  set(CMake_VERSION_MAJOR $major)
+  set(CMake_VERSION_MINOR $minor)
+  set(CMake_VERSION_PATCH $patch)
+  #set(CMake_VERSION_RC $rc) # uncomment for release candidates
+
+In the following we use the placeholder ``$fullver`` for the full version
+number of the new release with the form ``$major.$minor.$patch[-rc$rc]``.
+If the version is not a release candidate, comment out the RC version
+component above and leave off the ``-rc$rc`` suffix from ``$fullver``.
+
+Commit the release version with the **exact** message ``CMake $fullver``:
+
+.. code-block:: shell
+
+  git commit -m "CMake $fullver"
+
+Tag the release using an annotated tag with the same message as the
+commit and named with the **exact** form ``v$fullver``:
+
+.. code-block:: shell
+
+  git tag -s -m "CMake $fullver" "v$fullver"
+
+Follow the steps in the above `Maintain Current Release`_ section to
+merge the ``release-$ver`` branch into ``master`` and publish both.
+
 Branch a New Release
 ====================
 
@@ -178,7 +217,7 @@ Commit with a message such as::
   the CMake Release Notes index page.
 
 Update ``Source/CMakeVersion.cmake`` to set the version to
-``$major.$minor.0-rc1``:
+``$major.$minor.0-rc0``:
 
 .. code-block:: cmake
 
@@ -186,7 +225,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to
   set(CMake_VERSION_MAJOR $major)
   set(CMake_VERSION_MINOR $minor)
   set(CMake_VERSION_PATCH 0)
-  set(CMake_VERSION_RC 1)
+  set(CMake_VERSION_RC 0)
 
 Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the
 actual version number:
@@ -197,7 +236,7 @@ actual version number:
 
 Commit with a message such as::
 
-  CMake $major.$minor.0-rc1 version update
+  Begin $ver release versioning
 
 Merge the ``release-$ver`` branch to ``master``:
 
@@ -225,7 +264,7 @@ Update ``Source/CMakeVersion.cmake`` to set the version to
   set(CMake_VERSION_MAJOR $major)
   set(CMake_VERSION_MINOR $minor)
   set(CMake_VERSION_PATCH $date)
-  #set(CMake_VERSION_RC 1)
+  #set(CMake_VERSION_RC 0)
 
 Commit with a message such as::
 
@@ -240,10 +279,11 @@ Push the update to the ``master`` and ``release`` branches:
 Announce 'release' Branch
 -------------------------
 
-Send email to the ``cmake-developers@cmake.org`` mailing list (perhaps
+Post a topic to the `CMake Discourse Forum Development Category`_
-in reply to a release preparation thread) announcing that post-release
+announcing that post-release development is open::
-development is open::
 
-  I've branched 'release' for $ver.  The repository is now open for
+  I've branched `release` for $ver.  The repository is now open for
-  post-$ver development.  Please rebase open merge requests on 'master'
+  post-$ver development.  Please rebase open merge requests on `master`
   before staging or merging.
+
+.. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development

Help/dev/source.rst

@@ -74,6 +74,8 @@ The CMake source tree is organized as follows.
 
   * ``Utilities/Release/``:
     Scripts used to package CMake itself for distribution on ``cmake.org``.
+    See `Utilities/Release/README.rst`_.
 
 .. _`CMake Documentation Guide`: documentation.rst
 .. _`Tests/README.rst`: ../../Tests/README.rst
+.. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst

Help/generator/Ninja.rst

@@ -3,9 +3,9 @@ Ninja
 
 Generates build.ninja files.
 
-A build.ninja file is generated into the build tree.  Recent versions
+A ``build.ninja`` file is generated into the build tree.  Use the ninja
-of the ninja program can build the project through the ``all`` target.
+program to build the project through the ``all`` target and install the
-An ``install`` target is also provided.
+project through the ``install`` (or ``install/strip``) target.
 
 For each subdirectory ``sub/dir`` of the project, additional targets
 are generated:
@@ -16,6 +16,13 @@ are generated:
 ``sub/dir/install``
   Runs the install step in the subdirectory, if any.
 
+``sub/dir/install/strip``
+  Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command,
+  if any.
+
+  The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which
+  removes symbols information from generated binaries.
+
 ``sub/dir/test``
   Runs the test step in the subdirectory, if any.
 

Help/generator/Unix Makefiles.rst

@@ -3,6 +3,29 @@ Unix Makefiles
 
 Generates standard UNIX makefiles.
 
-A hierarchy of UNIX makefiles is generated into the build tree.  Any
+A hierarchy of UNIX makefiles is generated into the build tree.  Use
-standard UNIX-style make program can build the project through the
+any standard UNIX-style make program to build the project through
-default ``all`` target.  An ``install`` target is also provided.
+the ``all`` target and install the project through the ``install``
+(or ``install/strip``) target.
+
+For each subdirectory ``sub/dir`` of the project a UNIX makefile will
+be created, containing the following targets:
+
+``all``
+  Depends on all targets required by the subdirectory.
+
+``install``
+  Runs the install step in the subdirectory, if any.
+
+``install/strip``
+  Runs the install step in the subdirectory followed by a ``CMAKE_STRIP`` command,
+  if any.
+
+  The ``CMAKE_STRIP`` variable will contain the platform's ``strip`` utility, which
+  removes symbols information from generated binaries.
+
+``test``
+  Runs the test step in the subdirectory, if any.
+
+``package``
+  Runs the package step in the subdirectory, if any.

Help/guide/tutorial/Complete/CMakeLists.txt

@@ -1,32 +1,43 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.15)
-project(Tutorial)
 
-# control how we mark up Debug libraries compared to Release libraries
+# set the project name and version
-set(CMAKE_DEBUG_POSTFIX "-d")
+project(Tutorial VERSION 1.0)
+
+add_library(tutorial_compiler_flags INTERFACE)
+target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
+
+# add compiler warning flags just when building this project via
+# the BUILD_INTERFACE genex
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
+set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
+target_compile_options(tutorial_compiler_flags INTERFACE
+  "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
+  "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
+)
 
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
+if(APPLE)
-set(Tutorial_VERSION_MAJOR 1)
+  set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
-set(Tutorial_VERSION_MINOR 0)
+elseif(UNIX)
+  set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib")
+endif()
 
 # configure a header file to pass the version number only
-configure_file(
+configure_file(TutorialConfig.h.in TutorialConfig.h)
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
-target_link_libraries(Tutorial MathFunctions)
+target_link_libraries(Tutorial PUBLIC MathFunctions)
 
 # add the binary tree to the search path for include files
 # so that we will find TutorialConfig.h

Help/guide/tutorial/Complete/CTestConfig.cmake

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

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

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -14,14 +13,11 @@ target_include_directories(MathFunctions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 if(USE_MYMATH)
 
-  # does this system provide the log and exp functions?
+  target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
-  include(CheckSymbolExists)
-  set(CMAKE_REQUIRED_LIBRARIES "m")
-  check_symbol_exists(log "math.h" HAVE_LOG)
-  check_symbol_exists(exp "math.h" HAVE_EXP)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
+  target_link_libraries(MakeTable tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(
@@ -41,18 +37,16 @@ if(USE_MYMATH)
                              ${CMAKE_CURRENT_BINARY_DIR}
                              )
 
+  # state that SqrtLibrary need PIC when the default is shared libraries
   set_target_properties(SqrtLibrary PROPERTIES
                         POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                         )
 
-  target_compile_definitions(SqrtLibrary PRIVATE
+  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
-                             "$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>"
-                             "$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>"
-                             )
   target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()
 
-target_compile_definitions(MathFunctions PRIVATE "$<$<BOOL:${USE_MYMATH}>:USE_MYMATH>")
+target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
 
 # define the symbol stating we are using the declspec(dllexport) when
 # building on windows
@@ -62,7 +56,8 @@ target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
 set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
 
-install(TARGETS MathFunctions
+# install rules
+install(TARGETS MathFunctions tutorial_compiler_flags
         DESTINATION lib
         EXPORT MathFunctionsTargets)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx

@@ -1,5 +1,6 @@
 
 #include "MathFunctions.h"
+
 #include <cmath>
 
 #ifdef USE_MYMATH

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

@@ -1,11 +1,10 @@
-#include "MathFunctions.h"
 #include <iostream>
 
+#include "MathFunctions.h"
+
 // include the generated table
 #include "Table.h"
 
-#include <cmath>
-
 namespace mathfunctions {
 namespace detail {
 // a hack square root calculation using simple operations
@@ -15,20 +14,13 @@ double mysqrt(double x)
     return 0;
   }
 
-  // if we have both log and exp then use them
-#if defined(HAVE_LOG) && defined(HAVE_EXP)
-  double result = exp(log(x) * 0.5);
-  std::cout << "Computing sqrt of " << x << " to be " << result << " using log"
-            << std::endl;
-#else
   // use the table to help find an initial value
   double result = x;
   if (x >= 1 && x < 10) {
+    std::cout << "Use the table to help find an initial value " << std::endl;
     result = sqrtTable[static_cast<int>(x)];
   }
 
-  // if we have both log and exp then use them
-
   // do ten iterations
   for (int i = 0; i < 10; ++i) {
     if (result <= 0) {
@@ -38,7 +30,7 @@ double mysqrt(double x)
     result = result + 0.5 * delta / result;
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
   }
-#endif
+
   return result;
 }
 }

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

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

Help/guide/tutorial/Complete/tutorial.cxx

@@ -10,15 +10,16 @@ int main(int argc, char* argv[])
 {
   if (argc < 2) {
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
-              << Tutorial_VERSION_MAJOR << std::endl;
+              << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
     return 1;
   }
 
-  double inputValue = std::stod(argv[1]);
+  // convert input to double
+  const double inputValue = std::stod(argv[1]);
 
+  // calculate square root
   const double outputValue = mathfunctions::sqrt(inputValue);
-
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;
   return 0;

Help/guide/tutorial/Consumer/CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.10)
 
 if(NOT DEFINED CMAKE_CXX_STANDARD)
   set(CMAKE_CXX_STANDARD 11)

Help/guide/tutorial/MultiPackage/CMakeLists.txt

@@ -1,5 +1,11 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.10)
-project(Tutorial)
+
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
+
 
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
@@ -7,15 +13,8 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 11)
-set(CMAKE_CXX_STANDARD_REQUIRED True)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 if(APPLE)
   set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
 elseif(UNIX)
@@ -23,17 +22,14 @@ elseif(UNIX)
 endif()
 
 # configure a header file to pass the version number only
-configure_file(
+configure_file(TutorialConfig.h.in TutorialConfig.h)
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
-target_link_libraries(Tutorial MathFunctions)
+target_link_libraries(Tutorial PUBLIC MathFunctions)
 
 # add the binary tree to the search path for include files
 # so that we will find TutorialConfig.h

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

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -14,11 +13,7 @@ target_include_directories(MathFunctions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 if(USE_MYMATH)
 
-  # does this system provide the log and exp functions?
+  target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
-  include(CheckSymbolExists)
-  set(CMAKE_REQUIRED_LIBRARIES "m")
-  check_symbol_exists(log "math.h" HAVE_LOG)
-  check_symbol_exists(exp "math.h" HAVE_EXP)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
@@ -41,19 +36,14 @@ if(USE_MYMATH)
                              ${CMAKE_CURRENT_BINARY_DIR}
                              )
 
+  # state that SqrtLibrary need PIC when the default is shared libraries
   set_target_properties(SqrtLibrary PROPERTIES
                         POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                         )
 
-  target_compile_definitions(SqrtLibrary PRIVATE
-                             "$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>"
-                             "$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>"
-                             )
   target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()
 
-target_compile_definitions(MathFunctions PRIVATE "$<$<BOOL:${USE_MYMATH}>:USE_MYMATH>")
-
 # define the symbol stating we are using the declspec(dllexport) when
 # building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
@@ -62,6 +52,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(TARGETS MathFunctions
         DESTINATION lib
         EXPORT MathFunctionsTargets)

Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx

@@ -1,5 +1,6 @@
 
 #include "MathFunctions.h"
+
 #include <cmath>
 
 #ifdef USE_MYMATH

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

@@ -1,11 +1,10 @@
-#include "MathFunctions.h"
 #include <iostream>
 
+#include "MathFunctions.h"
+
 // include the generated table
 #include "Table.h"
 
-#include <cmath>
-
 namespace mathfunctions {
 namespace detail {
 // a hack square root calculation using simple operations
@@ -15,12 +14,6 @@ double mysqrt(double x)
     return 0;
   }
 
-  // if we have both log and exp then use them
-#if defined(HAVE_LOG) && defined(HAVE_EXP)
-  double result = exp(log(x) * 0.5);
-  std::cout << "Computing sqrt of " << x << " to be " << result << " using log"
-            << std::endl;
-#else
   // use the table to help find an initial value
   double result = x;
   if (x >= 1 && x < 10) {
@@ -38,7 +31,7 @@ double mysqrt(double x)
     result = result + 0.5 * delta / result;
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
   }
-#endif
+
   return result;
 }
 }

Help/guide/tutorial/MultiPackage/tutorial.cxx

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

Help/guide/tutorial/Step1/tutorial.cxx

@@ -11,9 +11,11 @@ int main(int argc, char* argv[])
     return 1;
   }
 
-  double inputValue = atof(argv[1]);
+  // convert input to double
+  const double inputValue = atof(argv[1]);
 
-  double outputValue = sqrt(inputValue);
+  // calculate square root
+  const double outputValue = sqrt(inputValue);
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;
   return 0;

Help/guide/tutorial/Step10/CMakeLists.txt

@@ -1,5 +1,11 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.10)
-project(Tutorial)
+
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
@@ -7,27 +13,17 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 11)
-set(CMAKE_CXX_STANDARD_REQUIRED True)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass the version number only
-configure_file(
+configure_file(TutorialConfig.h.in TutorialConfig.h)
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
-target_link_libraries(Tutorial MathFunctions)
+target_link_libraries(Tutorial PUBLIC MathFunctions)
 
 # add the binary tree to the search path for include files
 # so that we will find TutorialConfig.h
@@ -42,7 +38,7 @@ install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h"
   )
 
 # enable testing
-enable_testing()
+include(CTest)
 
 # does the application run
 add_test(NAME Runs COMMAND Tutorial 25)

Help/guide/tutorial/Step10/CTestConfig.cmake

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

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

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -12,11 +11,7 @@ target_include_directories(MathFunctions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 if(USE_MYMATH)
 
-  # does this system provide the log and exp functions?
+  target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
-  include(CheckSymbolExists)
-  set(CMAKE_REQUIRED_LIBRARIES "m")
-  check_symbol_exists(log "math.h" HAVE_LOG)
-  check_symbol_exists(exp "math.h" HAVE_EXP)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
@@ -44,12 +39,6 @@ if(USE_MYMATH)
                         POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                         )
 
-  target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
-  if(HAVE_LOG AND HAVE_EXP)
-    target_compile_definitions(SqrtLibrary
-                               PRIVATE "HAVE_LOG" "HAVE_EXP")
-  endif()
-
   target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()
 
@@ -57,5 +46,6 @@ endif()
 # building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx

@@ -1,5 +1,6 @@
 
 #include "MathFunctions.h"
+
 #include <cmath>
 
 #ifdef USE_MYMATH

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

@@ -1,11 +1,10 @@
-#include "MathFunctions.h"
 #include <iostream>
 
+#include "MathFunctions.h"
+
 // include the generated table
 #include "Table.h"
 
-#include <cmath>
-
 namespace mathfunctions {
 namespace detail {
 // a hack square root calculation using simple operations
@@ -15,20 +14,13 @@ double mysqrt(double x)
     return 0;
   }
 
-  // if we have both log and exp then use them
-#if defined(HAVE_LOG) && defined(HAVE_EXP)
-  double result = exp(log(x) * 0.5);
-  std::cout << "Computing sqrt of " << x << " to be " << result << " using log"
-            << std::endl;
-#else
   // use the table to help find an initial value
   double result = x;
   if (x >= 1 && x < 10) {
+    std::cout << "Use the table to help find an initial value " << std::endl;
     result = sqrtTable[static_cast<int>(x)];
   }
 
-  // if we have both log and exp then use them
-
   // do ten iterations
   for (int i = 0; i < 10; ++i) {
     if (result <= 0) {
@@ -38,7 +30,7 @@ double mysqrt(double x)
     result = result + 0.5 * delta / result;
     std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
   }
-#endif
+
   return result;
 }
 }

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

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

Help/guide/tutorial/Step10/tutorial.cxx

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

Help/guide/tutorial/Step11/CMakeLists.txt

@@ -1,5 +1,19 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.15)
-project(Tutorial)
+
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+add_library(tutorial_compiler_flags INTERFACE)
+target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
+
+# add compiler warning flags just when building this project via
+# the BUILD_INTERFACE genex
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
+set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
+target_compile_options(tutorial_compiler_flags INTERFACE
+  "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
+  "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
+)
 
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
@@ -7,27 +21,17 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
 
-set(CMAKE_CXX_STANDARD 11)
-set(CMAKE_CXX_STANDARD_REQUIRED True)
-
 option(BUILD_SHARED_LIBS "Build using shared libraries" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass the version number only
-configure_file(
+configure_file(TutorialConfig.h.in TutorialConfig.h)
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
 
 # add the MathFunctions library
 add_subdirectory(MathFunctions)
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
-target_link_libraries(Tutorial MathFunctions)
+target_link_libraries(Tutorial PUBLIC MathFunctions)
 
 # add the binary tree to the search path for include files
 # so that we will find TutorialConfig.h

Help/guide/tutorial/Step11/CTestConfig.cmake

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

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

@@ -1,4 +1,3 @@
-
 # add the library that runs
 add_library(MathFunctions MathFunctions.cxx)
 
@@ -12,14 +11,11 @@ target_include_directories(MathFunctions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 if(USE_MYMATH)
 
-  # does this system provide the log and exp functions?
+  target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH")
-  include(CheckSymbolExists)
-  set(CMAKE_REQUIRED_LIBRARIES "m")
-  check_symbol_exists(log "math.h" HAVE_LOG)
-  check_symbol_exists(exp "math.h" HAVE_EXP)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
+  target_link_libraries(MakeTable tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(
@@ -39,22 +35,21 @@ if(USE_MYMATH)
                              ${CMAKE_CURRENT_BINARY_DIR}
                              )
 
+  # state that SqrtLibrary need PIC when the default is shared libraries
   set_target_properties(SqrtLibrary PROPERTIES
                         POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                         )
 
-  target_compile_definitions(SqrtLibrary PRIVATE
+  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
-                             "$<$<BOOL:${HAVE_LOG}>:HAVE_LOG>"
-                             "$<$<BOOL:${HAVE_EXP}>:HAVE_EXP>"
-                             )
   target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()
 
-target_compile_definitions(MathFunctions PRIVATE "$<$<BOOL:${USE_MYMATH}>:USE_MYMATH>")
+target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
 
 # define the symbol stating we are using the declspec(dllexport) when
 #building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
+# install rules
 install(TARGETS MathFunctions DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx

@@ -1,5 +1,6 @@
 
 #include "MathFunctions.h"
+
 #include <cmath>
 
 #ifdef USE_MYMATH

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

@@ -0,0 +1,37 @@
+#include <iostream>
+
+#include "MathFunctions.h"
+
+// include the generated table
+#include "Table.h"
+
+namespace mathfunctions {
+namespace detail {
+// a hack square root calculation using simple operations
+double mysqrt(double x)
+{
+  if (x <= 0) {
+    return 0;
+  }
+
+  // use the table to help find an initial value
+  double result = x;
+  if (x >= 1 && x < 10) {
+    std::cout << "Use the table to help find an initial value " << std::endl;
+    result = sqrtTable[static_cast<int>(x)];
+  }
+
+  // do ten iterations
+  for (int i = 0; i < 10; ++i) {
+    if (result <= 0) {
+      result = 0.1;
+    }
+    double delta = x - (result * result);
+    result = result + 0.5 * delta / result;
+    std::cout << "Computing sqrt of " << x << " to be " << result << std::endl;
+  }
+
+  return result;
+}
+}
+}

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

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

Help/guide/tutorial/Step11/tutorial.cxx

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

Help/guide/tutorial/Step2/CMakeLists.txt

@@ -1,19 +1,15 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.10)
-project(Tutorial)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass some of the CMake settings
 # to the source code
-configure_file(
+configure_file(TutorialConfig.h.in TutorialConfig.h)
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)

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

@@ -1,4 +1,3 @@
-#include "MathFunctions.h"
 #include <iostream>
 
 // a hack square root calculation using simple operations

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

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

Help/guide/tutorial/Step2/tutorial.cxx

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

Help/guide/tutorial/Step3/CMakeLists.txt

@@ -1,34 +1,30 @@
-cmake_minimum_required(VERSION 3.3)
+cmake_minimum_required(VERSION 3.10)
-project(Tutorial)
 
+# set the project name and version
+project(Tutorial VERSION 1.0)
+
+# specify the C++ standard
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 # should we use our own math functions
 option(USE_MYMATH "Use tutorial provided math implementation" ON)
 
-# the version number.
-set(Tutorial_VERSION_MAJOR 1)
-set(Tutorial_VERSION_MINOR 0)
-
 # configure a header file to pass some of the CMake settings
 # to the source code
-configure_file(
+configure_file(TutorialConfig.h.in TutorialConfig.h)
-  "${PROJECT_SOURCE_DIR}/TutorialConfig.h.in"
-  "${PROJECT_BINARY_DIR}/TutorialConfig.h"
-  )
 
-# add the MathFunctions library?
+# add the MathFunctions library
 if(USE_MYMATH)
   add_subdirectory(MathFunctions)
   list(APPEND EXTRA_LIBS MathFunctions)
   list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions")
-endif(USE_MYMATH)
+endif()
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
 
-target_link_libraries(Tutorial ${EXTRA_LIBS})
+target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS})
 
 # add the binary tree to the search path for include files
 # so that we will find TutorialConfig.h