New upstream version 3.15.4

.clang-tidy

@@ -1,5 +1,8 @@
 ---
 Checks: "-*,\
+bugprone-*,\
+-bugprone-macro-parentheses,\
+-bugprone-misplaced-widening-cast,\
 google-readability-casting,\
 misc-*,\
 -misc-incorrect-roundings,\
@@ -8,14 +11,8 @@ misc-*,\
 -misc-static-assert,\
 modernize-*,\
 -modernize-deprecated-headers,\
--modernize-pass-by-value,\
--modernize-raw-string-literal,\
 -modernize-return-braced-init-list,\
 -modernize-use-auto,\
--modernize-use-default-member-init,\
--modernize-use-emplace,\
--modernize-use-equals-default,\
--modernize-use-equals-delete,\
 -modernize-use-noexcept,\
 -modernize-use-transparent-functors,\
 -modernize-use-using,\
@@ -25,11 +22,15 @@ readability-*,\
 -readability-function-size,\
 -readability-identifier-naming,\
 -readability-implicit-bool-cast,\
+-readability-implicit-bool-conversion,\
 -readability-inconsistent-declaration-parameter-name,\
 -readability-named-parameter,\
 -readability-redundant-declaration,\
--readability-redundant-member-init,\
--readability-simplify-boolean-expr,\
 "
 HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'
+CheckOptions:
+  - key:   modernize-use-default-member-init.UseAssignment
+    value: '1'
+  - key:   modernize-use-equals-default.IgnoreMacros
+    value: '0'
 ...

Auxiliary/bash-completion/cmake

@@ -96,7 +96,7 @@ _cmake()
             _filedir
             return
             ;;
-        --build|--open)
+        --build|--install|--open)
             _filedir -d
             return
             ;;
@@ -116,6 +116,9 @@ _cmake()
                 2>/dev/null )' -- "$quoted" ) )
             return
             ;;
+        --loglevel)
+            COMPREPLY=( $(compgen -W 'error warning notice status verbose debug trace' -- $cur ) )
+            ;;
         --help-command)
             COMPREPLY=( $( compgen -W '$( cmake --help-command-list 2>/dev/null|
                 grep -v "^cmake version " )' -- "$cur" ) )

Auxiliary/cmake.m4

@@ -13,7 +13,7 @@ fi
 # $2: language (e.g. C/CXX/Fortran)
 # $3: The compiler ID, defaults to GNU.
 #     Possible values are: GNU, Intel, Clang, SunPro, HP, XL, VisualAge, PGI,
-#     PathScale, Cray, SCO, MIPSpro, MSVC
+#     PathScale, Cray, SCO, MSVC
 # $4: optional extra arguments to cmake, e.g. "-DCMAKE_SIZEOF_VOID_P=8"
 # $5: optional path to cmake binary
 AC_DEFUN([CMAKE_FIND_PACKAGE], [

Auxiliary/vim/cmake.vim.in

@@ -31,11 +31,11 @@ syn region cmakeGeneratorExpression start="$<" end=">" contained oneline contain
 
 syn region cmakeString start='"' end='"' contained contains=cmakeTodo,cmakeVariableValue,cmakeEscaped
 
-syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmakeVariable,cmakeTodo
+syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmakeVariable,cmakeTodo,cmakeVariableValue
 
 syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo
 
-syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo
+syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo
 
 syn case match
 

Auxiliary/vim/extract-upper-case.pl

@@ -13,6 +13,9 @@ my @properties;
 my @modules;
 my %keywords; # command => keyword-list
 
+# find cmake/Modules/ | sed -rn 's/.*CMakeDetermine(.+)Compiler.cmake/\1/p' | sort
+my @languages = qw(ASM ASM_MASM ASM_NASM C CSharp CUDA CXX Fortran Java RC Swift);
+
 # unwanted upper-cases
 my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR NEW);
 	# cannot remove ALL - exists for add_custom_command
@@ -30,8 +33,21 @@ push @modules, "ExternalProject";
 # variables
 open(CMAKE, "$cmake --help-variable-list|") or die "could not run cmake";
 while (<CMAKE>) {
-	next if /\</; # skip if containing < or >
 	chomp;
+
+	if (/<(.*?)>/) {
+		if ($1 eq 'LANG') {
+			foreach my $lang (@languages) {
+			(my $V = $_) =~ s/<.*>/$lang/;
+				push @variables, $V;
+			}
+
+			next
+		} else {
+			next; # skip if containing < or >
+		}
+	}
+
 	push @variables, $_;
 }
 close(CMAKE);

CMakeCPack.cmake

@@ -102,9 +102,6 @@ if(CMake_INSTALL_COMPONENTS)
   if(WIN32 AND NOT CYGWIN)
       list(APPEND _CPACK_IFW_COMPONENTS_ALL cmcldeps)
   endif()
-  if(APPLE)
-    list(APPEND _CPACK_IFW_COMPONENTS_ALL cmakexbuild)
-  endif()
   if(CMAKE_INSTALL_DEFAULT_COMPONENT_NAME)
     set(_CPACK_IFW_COMPONENT_UNSPECIFIED_NAME
       ${CMAKE_INSTALL_DEFAULT_COMPONENT_NAME})

CMakeCPackOptions.cmake.in

@@ -109,16 +109,6 @@ if(CPACK_GENERATOR MATCHES "IFW")
   set(CPACK_IFW_COMPONENT_CMCLDEPS_VERSION
     "@CMake_IFW_ROOT_COMPONENT_VERSION@")
 
-  set(CPACK_COMPONENT_CMAKEXBUILD_DISPLAY_NAME "cmakexbuild")
-  set(CPACK_COMPONENT_CMAKEXBUILD_DESCRIPTION
-    "The \"cmakexbuild\" executable is a wrapper program for \"xcodebuild\"")
-  set(CPACK_COMPONENT_CMAKEXBUILD_REQUIRED TRUE)
-  set(CPACK_COMPONENT_CMAKEXBUILD_GROUP Tools)
-  set(CPACK_IFW_COMPONENT_CMAKEXBUILD_NAME "CMakeXBuild")
-  set(CPACK_IFW_COMPONENT_CMAKEXBUILD_PRIORITY 85)
-  set(CPACK_IFW_COMPONENT_CMAKEXBUILD_VERSION
-    "@CMake_IFW_ROOT_COMPONENT_VERSION@")
-
   # Dialogs
   set(CPACK_COMPONENT_GROUP_DIALOGS_DISPLAY_NAME "Interactive Dialogs")
   set(CPACK_COMPONENT_GROUP_DIALOGS_DESCRIPTION

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-cmake_minimum_required(VERSION 3.1 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.1...3.14 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)
@@ -117,6 +117,18 @@ option(CMake_BUILD_DEVELOPER_REFERENCE
   "Build CMake Developer Reference" OFF)
 mark_as_advanced(CMake_BUILD_DEVELOPER_REFERENCE)
 
+# option to build using interprocedural optimizations (IPO/LTO)
+if (NOT CMAKE_VERSION VERSION_LESS 3.12.2)
+  option(CMake_BUILD_LTO "Compile CMake with link-time optimization if supported" OFF)
+  if(CMake_BUILD_LTO)
+    include(CheckIPOSupported)
+    check_ipo_supported(RESULT HAVE_IPO)
+    if(HAVE_IPO)
+      set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
+    endif()
+  endif()
+endif()
+
 #-----------------------------------------------------------------------
 # a macro to deal with system libraries, implemented as a macro
 # simply to improve readability of the main script
@@ -125,13 +137,9 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
   # Options have dependencies.
   include(CMakeDependentOption)
 
-  # Optionally use system xmlrpc.  We no longer build or use it by default.
-  option(CTEST_USE_XMLRPC "Enable xmlrpc submission method in CTest." OFF)
-  mark_as_advanced(CTEST_USE_XMLRPC)
-
   # Allow the user to enable/disable all system utility library options by
   # defining CMAKE_USE_SYSTEM_LIBRARIES or CMAKE_USE_SYSTEM_LIBRARY_${util}.
-  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV ZLIB)
+  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV ZLIB ZSTD)
   foreach(util ${UTILITIES})
     if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
         AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
@@ -159,14 +167,14 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
 
   # Optionally use system utility libraries.
   option(CMAKE_USE_SYSTEM_LIBARCHIVE "Use system-installed libarchive" "${CMAKE_USE_SYSTEM_LIBRARY_LIBARCHIVE}")
-  CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_CURL "Use system-installed curl"
+  option(CMAKE_USE_SYSTEM_CURL "Use system-installed curl" "${CMAKE_USE_SYSTEM_LIBRARY_CURL}")
-    "${CMAKE_USE_SYSTEM_LIBRARY_CURL}" "NOT CTEST_USE_XMLRPC" ON)
+  option(CMAKE_USE_SYSTEM_EXPAT "Use system-installed expat" "${CMAKE_USE_SYSTEM_LIBRARY_EXPAT}")
-  CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_EXPAT "Use system-installed expat"
-    "${CMAKE_USE_SYSTEM_LIBRARY_EXPAT}" "NOT CTEST_USE_XMLRPC" ON)
   CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_ZLIB "Use system-installed zlib"
     "${CMAKE_USE_SYSTEM_LIBRARY_ZLIB}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE;NOT CMAKE_USE_SYSTEM_CURL" ON)
   CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_BZIP2 "Use system-installed bzip2"
     "${CMAKE_USE_SYSTEM_LIBRARY_BZIP2}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
+  CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_ZSTD "Use system-installed zstd"
+    "${CMAKE_USE_SYSTEM_LIBRARY_ZSTD}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
   CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_LIBLZMA "Use system-installed liblzma"
     "${CMAKE_USE_SYSTEM_LIBRARY_LIBLZMA}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
   option(CMAKE_USE_SYSTEM_FORM "Use system-installed libform" "${CMAKE_USE_SYSTEM_LIBRARY_FORM}")
@@ -200,7 +208,7 @@ endmacro()
 macro(CMAKE_SETUP_TESTING)
   if(BUILD_TESTING)
     set(CMAKE_TEST_SYSTEM_LIBRARIES 0)
-    foreach(util CURL EXPAT XMLRPC ZLIB)
+    foreach(util CURL EXPAT ZLIB)
       if(CMAKE_USE_SYSTEM_${util})
         set(CMAKE_TEST_SYSTEM_LIBRARIES 1)
       endif()
@@ -326,6 +334,9 @@ macro (CMAKE_BUILD_UTILITIES)
   set(KWSYS_USE_ConsoleBuf 1)
   set(KWSYS_HEADER_ROOT ${CMake_BINARY_DIR}/Source)
   set(KWSYS_INSTALL_DOC_DIR "${CMAKE_DOC_DIR}")
+  if(CMake_NO_CXX_STANDARD)
+    set(KWSYS_CXX_STANDARD "")
+  endif()
   add_subdirectory(Source/kwsys)
   set(kwsys_folder "Utilities/KWSys")
   CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE} "${kwsys_folder}")
@@ -435,14 +446,6 @@ macro (CMAKE_BUILD_UTILITIES)
     CMAKE_SET_TARGET_FOLDER(LIBCURL "Utilities/3rdParty")
   endif()
 
-  #---------------------------------------------------------------------
-  # Build Compress library for CTest.
-  set(CMAKE_COMPRESS_INCLUDES
-    "${CMAKE_CURRENT_BINARY_DIR}/Utilities/cmcompress")
-  set(CMAKE_COMPRESS_LIBRARIES "cmcompress")
-  add_subdirectory(Utilities/cmcompress)
-  CMAKE_SET_TARGET_FOLDER(cmcompress "Utilities/3rdParty")
-
   #---------------------------------------------------------------------
   # Build expat library for CMake, CTest, and libarchive.
   if(CMAKE_USE_SYSTEM_EXPAT)
@@ -474,6 +477,17 @@ macro (CMAKE_BUILD_UTILITIES)
     endif()
   endif()
 
+  #---------------------------------------------------------------------
+  # Build or use system zstd for libarchive.
+  if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
+    if(NOT CMAKE_USE_SYSTEM_ZSTD)
+      set(ZSTD_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmzstd")
+      set(ZSTD_LIBRARY cmzstd)
+      add_subdirectory(Utilities/cmzstd)
+      CMAKE_SET_TARGET_FOLDER(cmzstd "Utilities/3rdParty")
+    endif()
+  endif()
+
   #---------------------------------------------------------------------
   # Build or use system liblzma for libarchive.
   if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
@@ -497,7 +511,7 @@ macro (CMAKE_BUILD_UTILITIES)
   #---------------------------------------------------------------------
   # Build or use system libarchive for CMake and CTest.
   if(CMAKE_USE_SYSTEM_LIBARCHIVE)
-    find_package(LibArchive 3.1.0)
+    find_package(LibArchive 3.3.3)
     if(NOT LibArchive_FOUND)
       message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBARCHIVE is ON but LibArchive is not found!")
     endif()
@@ -532,11 +546,15 @@ macro (CMAKE_BUILD_UTILITIES)
   #---------------------------------------------------------------------
   # Build jsoncpp library.
   if(CMAKE_USE_SYSTEM_JSONCPP)
-    find_package(JsonCpp)
+    find_package(JsonCpp 1.4.1)
     if(NOT JsonCpp_FOUND)
       message(FATAL_ERROR
         "CMAKE_USE_SYSTEM_JSONCPP is ON but a JsonCpp is not found!")
     endif()
+    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+      set_property(TARGET JsonCpp::JsonCpp APPEND PROPERTY
+        INTERFACE_COMPILE_OPTIONS -Wno-deprecated-declarations)
+    endif()
     set(CMAKE_JSONCPP_LIBRARIES JsonCpp::JsonCpp)
   else()
     set(CMAKE_JSONCPP_LIBRARIES cmjsoncpp)
@@ -559,18 +577,6 @@ macro (CMAKE_BUILD_UTILITIES)
     CMAKE_SET_TARGET_FOLDER(cmlibuv "Utilities/3rdParty")
   endif()
 
-  #---------------------------------------------------------------------
-  # Build XMLRPC library for CMake and CTest.
-  if(CTEST_USE_XMLRPC)
-    find_package(XMLRPC QUIET REQUIRED libwww-client)
-    if(NOT XMLRPC_FOUND)
-      message(FATAL_ERROR
-        "CTEST_USE_XMLRPC is ON but xmlrpc is not found!")
-    endif()
-    set(CMAKE_XMLRPC_INCLUDES ${XMLRPC_INCLUDE_DIRS})
-    set(CMAKE_XMLRPC_LIBRARIES ${XMLRPC_LIBRARIES})
-  endif()
-
   #---------------------------------------------------------------------
   # Use curses?
   if (UNIX)
@@ -724,7 +730,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
   # the build tree, which is both the build and the install RPATH.
   if (UNIX)
     if(   CMAKE_USE_SYSTEM_CURL   OR  CMAKE_USE_SYSTEM_ZLIB
-          OR  CMAKE_USE_SYSTEM_EXPAT  OR  CTEST_USE_XMLRPC  OR  CURSES_NEED_RPATH  OR  QT_NEED_RPATH)
+          OR  CMAKE_USE_SYSTEM_EXPAT  OR  CURSES_NEED_RPATH  OR  QT_NEED_RPATH)
       set(CMAKE_SKIP_RPATH OFF CACHE INTERNAL "CMake built with RPATH.")
       set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
       set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
@@ -816,4 +822,10 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
 
   # Install auxiliary files integrating with other tools.
   add_subdirectory(Auxiliary)
+
+  # Optionally sign installed binaries.
+  if(CMake_INSTALL_SIGNTOOL)
+    configure_file(Source/CMakeInstallSignTool.cmake.in Source/CMakeInstallSignTool.cmake @ONLY)
+    install(SCRIPT ${CMAKE_CURRENT_BINARY_DIR}/Source/CMakeInstallSignTool.cmake)
+  endif()
 endif()

CONTRIBUTING.rst

@@ -24,7 +24,8 @@ CMake uses `Kitware's GitLab Instance`_ to manage development and code review.
 To contribute patches:
 
 #. Fork the upstream `CMake Repository`_ into a personal account.
-#. Run `Utilities/SetupForDevelopment.sh`_ for local configuration.
+#. 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.
    Base work on the upstream ``release`` branch only if it fixes a
@@ -45,6 +46,7 @@ The merge request will enter the `CMake Review Process`_ for consideration.
 .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
 .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
 .. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
+.. _`Building CMake`: README.rst#building-cmake
 .. _`CMake Source Code Guide`: Help/dev/source.rst
 .. _`commit messages`: Help/dev/review.rst#commit-messages
 .. _`CMake Review Process`: Help/dev/review.rst

CTestCustom.cmake.in

@@ -52,6 +52,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "(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"
+  "LexerParser.*warning.*empty expression statement has no effect; remove unnecessary"
   "PGC-W-0095-Type cast required for this conversion.*ProcessUNIX.c"
   "[Qq]t([Cc]ore|[Gg]ui|[Ww]idgets).*warning.*conversion.*may alter its value"
   "warning:.*is.*very unsafe.*consider using.*"

CompileFlags.cmake

@@ -8,11 +8,16 @@ if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Intel")
   set(_INTEL_WINDOWS 1)
 endif()
 
+if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Clang"
+   AND "x${CMAKE_CXX_SIMULATE_ID}" STREQUAL "xMSVC")
+  set(_CLANG_MSVC_WINDOWS 1)
+endif()
+
 # Disable deprecation warnings for standard C functions.
 # really only needed for newer versions of VS, but should
 # not hurt other versions, and this will work into the
 # future
-if(MSVC OR _INTEL_WINDOWS)
+if(MSVC OR _INTEL_WINDOWS OR _CLANG_MSVC_WINDOWS)
   add_definitions(-D_CRT_SECURE_NO_DEPRECATE -D_CRT_NONSTDC_NO_DEPRECATE)
 else()
 endif()
@@ -21,6 +26,10 @@ if(MSVC)
   set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -stack:10000000")
 endif()
 
+if(_CLANG_MSVC_WINDOWS AND "x${CMAKE_CXX_COMPILER_FRONTEND_VARIANT}" STREQUAL "xGNU")
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Xlinker -stack:20000000")
+endif()
+
 #silence duplicate symbol warnings on AIX
 if(CMAKE_SYSTEM_NAME MATCHES "AIX")
   if(NOT CMAKE_COMPILER_IS_GNUCXX)
@@ -28,13 +37,6 @@ if(CMAKE_SYSTEM_NAME MATCHES "AIX")
   endif()
 endif()
 
-if(CMAKE_SYSTEM_NAME MATCHES "IRIX")
-  if(NOT CMAKE_COMPILER_IS_GNUCXX)
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wl,-woff84 -no_auto_include")
-    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-woff15")
-  endif()
-endif()
-
 if(CMAKE_SYSTEM MATCHES "OSF1-V")
   if(NOT CMAKE_COMPILER_IS_GNUCXX)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -timplicit_local -no_implicit_include ")
@@ -51,6 +53,15 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "^parisc")
   endif()
 endif()
 
+# Workaround for TOC Overflow on ppc64
+if(CMAKE_SYSTEM_NAME STREQUAL "AIX" AND
+   CMAKE_SYSTEM_PROCESSOR MATCHES "powerpc")
+  set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -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")
+endif()
+
 if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND
     NOT DEFINED CMAKE_CXX${CMAKE_CXX_STANDARD}_STANDARD_COMPILE_OPTION)
   if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.13)

Copyright.txt

@@ -1,5 +1,5 @@
 CMake - Cross Platform Makefile Generator
-Copyright 2000-2018 Kitware, Inc. and Contributors
+Copyright 2000-2019 Kitware, Inc. and Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -39,6 +39,7 @@ The following individuals and institutions are among the Contributors:
 * Alexander Neundorf <neundorf@kde.org>
 * Alexander Smorkalov <alexander.smorkalov@itseez.com>
 * Alexey Sokolov <sokolov@google.com>
+* Alex Merry <alex.merry@kde.org>
 * Alex Turbov <i.zaufi@gmail.com>
 * Andreas Pakulat <apaku@gmx.de>
 * Andreas Schneider <asn@cryptomilk.org>
@@ -62,13 +63,17 @@ The following individuals and institutions are among the Contributors:
 * Ilya Lavrenov <ilya.lavrenov@itseez.com>
 * Insight Software Consortium <insightsoftwareconsortium.org>
 * Jan Woetzel
+* Julien Schueller
 * Kelly Thompson <kgt@lanl.gov>
+* Laurent Montel <montel@kde.org>
 * Konstantin Podsvirov <konstantin@podsvirov.pro>
 * Mario Bensi <mbensi@ipsquad.net>
+* Martin Gräßlin <mgraesslin@kde.org>
 * Mathieu Malaterre <mathieu.malaterre@gmail.com>
 * Matthaeus G. Chajdas
 * Matthias Kretz <kretz@kde.org>
 * Matthias Maennich <matthias@maennich.net>
+* Michael Hirsch, Ph.D. <www.scivision.co>
 * Michael Stürmer
 * Miguel A. Figueroa-Villanueva
 * Mike Jackson

Help/command/FIND_XXX.txt

@@ -96,7 +96,7 @@ 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:`;-lists <CMake Language Lists>`.
+   The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
    This can be skipped if ``NO_CMAKE_PATH`` is passed.
 
    * |CMAKE_PREFIX_PATH_XXX|

Help/command/add_compile_definitions.rst

@@ -1,9 +1,9 @@
 add_compile_definitions
 -----------------------
 
-Adds preprocessor definitions to the compilation of source files.
+Add preprocessor definitions to the compilation of source files.
 
-::
+.. code-block:: cmake
 
   add_compile_definitions(<definition> ...)
 

Help/command/add_compile_options.rst

@@ -1,21 +1,18 @@
 add_compile_options
 -------------------
 
-Adds options to the compilation of source files.
+Add options to the compilation of source files.
 
-::
+.. code-block:: cmake
 
   add_compile_options(<option> ...)
 
-Adds options to the compiler command line for targets in the current
+Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property.
-directory and below that are added after this command is invoked.
+These options are used when compiling targets from the current
-See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and
+directory and below.
-:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
 
-This command can be used to add any options, but alternative commands
+Arguments
-exist to add preprocessor definitions (:command:`target_compile_definitions`
+^^^^^^^^^
-and :command:`add_compile_definitions`) or include directories
-(:command:`target_include_directories` and :command:`include_directories`).
 
 Arguments to ``add_compile_options`` may use "generator expressions" with
 the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
@@ -23,3 +20,29 @@ manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
 .. include:: OPTIONS_SHELL.txt
+
+Example
+^^^^^^^
+
+Since different compilers support different options, a typical use of
+this command is in a compiler-specific conditional clause:
+
+.. code-block:: cmake
+
+  if (MSVC)
+      # warning level 4 and all warnings as errors
+      add_compile_options(/W4 /WX)
+  else()
+      # lots of warnings and all warnings as errors
+      add_compile_options(-Wall -Wextra -pedantic -Werror)
+  endif()
+
+See Also
+^^^^^^^^
+
+This command can be used to add any options. However, for
+adding preprocessor definitions and include directories it is recommended
+to use the more specific commands :command:`add_compile_definitions`
+and :command:`include_directories`.
+
+The command :command:`target_compile_options` adds target-specific options.

Help/command/add_custom_command.rst

@@ -8,7 +8,9 @@ There are two main signatures for ``add_custom_command``.
 Generating Files
 ^^^^^^^^^^^^^^^^
 
-The first signature is for adding a custom command to produce an output::
+The first signature is for adding a custom command to produce an output:
+
+.. code-block:: cmake
 
   add_custom_command(OUTPUT output1 [output2 ...]
                      COMMAND command1 [ARGS] [args1...]
@@ -21,6 +23,7 @@ The first signature is for adding a custom command to produce an output::
                      [WORKING_DIRECTORY dir]
                      [COMMENT comment]
                      [DEPFILE depfile]
+                     [JOB_POOL job_pool]
                      [VERBATIM] [APPEND] [USES_TERMINAL]
                      [COMMAND_EXPAND_LISTS])
 
@@ -142,6 +145,13 @@ The options are:
   Note that the ``IMPLICIT_DEPENDS`` option is currently supported
   only for Makefile generators and will be ignored by other generators.
 
+``JOB_POOL``
+  Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
+  generator. Incompatible with ``USES_TERMINAL``, which implies
+  the ``console`` pool.
+  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
+  an error by ninja at build time.
+
 ``MAIN_DEPENDENCY``
   Specify the primary input source file to the command.  This is
   treated just like any value given to the ``DEPENDS`` option
@@ -200,7 +210,7 @@ before or after building the target.  The command becomes part of the
 target and will only execute when the target itself is built.  If the
 target is already built, the command will not execute.
 
-::
+.. code-block:: cmake
 
   add_custom_command(TARGET <target>
                      PRE_BUILD | PRE_LINK | POST_BUILD

Help/command/add_custom_target.rst

@@ -3,7 +3,7 @@ add_custom_target
 
 Add a target with no output so it will always be built.
 
-::
+.. code-block:: cmake
 
   add_custom_target(Name [ALL] [command1 [args1...]]
                     [COMMAND command2 [args2...] ...]
@@ -11,6 +11,7 @@ Add a target with no output so it will always be built.
                     [BYPRODUCTS [files...]]
                     [WORKING_DIRECTORY dir]
                     [COMMENT comment]
+                    [JOB_POOL job_pool]
                     [VERBATIM] [USES_TERMINAL]
                     [COMMAND_EXPAND_LISTS]
                     [SOURCES src1 [src2...]])
@@ -97,6 +98,13 @@ The options are:
   ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
   to be properly expanded.
 
+``JOB_POOL``
+  Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
+  generator. Incompatible with ``USES_TERMINAL``, which implies
+  the ``console`` pool.
+  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
+  an error by ninja at build time.
+
 ``SOURCES``
   Specify additional source files to be included in the custom target.
   Specified source files will be added to IDE project files for

Help/command/add_definitions.rst

@@ -1,9 +1,9 @@
 add_definitions
 ---------------
 
-Adds -D define flags to the compilation of source files.
+Add -D define flags to the compilation of source files.
 
-::
+.. code-block:: cmake
 
   add_definitions(-DFOO -DBAR ...)
 
@@ -20,7 +20,7 @@ preprocessor definitions.
   * Use :command:`include_directories` to add include directories.
   * Use :command:`add_compile_options` to add other options.
 
-Flags beginning in -D or /D that look like preprocessor definitions are
+Flags beginning in ``-D`` or ``/D`` that look like preprocessor definitions are
 automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory
 property for the current directory.  Definitions with non-trivial values
 may be left in the set of flags instead of being converted for reasons of

Help/command/add_dependencies.rst

@@ -3,11 +3,11 @@ add_dependencies
 
 Add a dependency between top-level targets.
 
-::
+.. code-block:: cmake
 
   add_dependencies(<target> [<target-dependency>]...)
 
-Make a top-level ``<target>`` depend on other top-level targets to
+Makes a top-level ``<target>`` depend on other top-level targets to
 ensure that they build before ``<target>`` does.  A top-level target
 is one created by one of the :command:`add_executable`,
 :command:`add_library`, or :command:`add_custom_target` commands

Help/command/add_executable.rst

@@ -3,7 +3,7 @@ add_executable
 
 Add an executable to the project using the specified source files.
 
-::
+.. code-block:: cmake
 
   add_executable(<name> [WIN32] [MACOSX_BUNDLE]
                  [EXCLUDE_FROM_ALL]
@@ -47,7 +47,7 @@ within IDE.
 
 --------------------------------------------------------------------------
 
-::
+.. code-block:: cmake
 
   add_executable(<name> IMPORTED [GLOBAL])
 
@@ -67,7 +67,7 @@ properties for more information.
 
 --------------------------------------------------------------------------
 
-::
+.. code-block:: cmake
 
   add_executable(<name> ALIAS <target>)
 

Help/command/add_library.rst

@@ -10,7 +10,7 @@ Add a library to the project using the specified source files.
 Normal Libraries
 ^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   add_library(<name> [STATIC | SHARED | MODULE]
               [EXCLUDE_FROM_ALL]
@@ -67,7 +67,7 @@ within IDE.
 Imported Libraries
 ^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
               [GLOBAL])
@@ -80,19 +80,30 @@ option extends visibility.  It may be referenced like any target built
 within the project.  ``IMPORTED`` libraries are useful for convenient
 reference from commands like :command:`target_link_libraries`.  Details
 about the imported library are specified by setting properties whose names
-begin in ``IMPORTED_`` and ``INTERFACE_``.  The most important such
+begin in ``IMPORTED_`` and ``INTERFACE_``.
-property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
+
-variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
+The most important properties are:
-location of the main library file on disk.  Or, for object libraries,
+
-:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
+* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
-specifies the locations of object files on disk.
+  variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
+  location of the main library file on disk.
+* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
+  for object libraries, specifies the locations of object files on disk.
+* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation
+
 See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
 for more information.
 
+An ``UNKNOWN`` library type is typically only used in the implementation of
+:ref:`Find Modules`.  It allows the path to an imported library (often found
+using the :command:`find_library` command) to be used without having to know
+what type of library it is.  This is especially useful on Windows where a
+static library and a DLL's import library both have the same file extension.
+
 Object Libraries
 ^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   add_library(<name> OBJECT <src>...)
 
@@ -121,7 +132,7 @@ consider adding at least one real source file to any target that references
 Alias Libraries
 ^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   add_library(<name> ALIAS <target>)
 
@@ -141,7 +152,7 @@ installed or exported.
 Interface Libraries
 ^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
 

Help/command/add_link_options.rst

@@ -1,20 +1,25 @@
 add_link_options
 ----------------
 
-Adds options to the link of shared library, module and executable targets.
+Add options to the link step for executable, shared library or module
+library targets in the current directory and below that are added after
+this command is invoked.
 
-::
+.. code-block:: cmake
 
   add_link_options(<option> ...)
 
-Adds options to the link step for targets in the current directory and below
+This command can be used to add any link options, but alternative commands
-that are added after this command is invoked. See documentation of the
+exist to add libraries (:command:`target_link_libraries` or
+:command:`link_libraries`).  See documentation of the
 :prop_dir:`directory <LINK_OPTIONS>` and
 :prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
 
-This command can be used to add any options, but alternative commands
+.. note::
-exist to add libraries (:command:`target_link_libraries` or
+
-:command:`link_libraries`).
+  This command cannot be used to add options for static library targets,
+  since they do not use a linker.  To add archiver or MSVC librarian flags,
+  see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
 
 Arguments to ``add_link_options`` may use "generator expressions" with
 the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`

Help/command/add_subdirectory.rst

@@ -3,12 +3,11 @@ add_subdirectory
 
 Add a subdirectory to the build.
 
-::
+.. code-block:: cmake
 
-  add_subdirectory(source_dir [binary_dir]
+  add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
-                   [EXCLUDE_FROM_ALL])
 
-Add a subdirectory to the build.  The source_dir specifies the
+Adds a subdirectory to the build.  The source_dir specifies the
 directory in which the source CMakeLists.txt and code files are
 located.  If it is a relative path it will be evaluated with respect
 to the current directory (the typical usage), but it may also be an

Help/command/add_test.rst

@@ -3,13 +3,13 @@ add_test
 
 Add a test to the project to be run by :manual:`ctest(1)`.
 
-::
+.. code-block:: cmake
 
   add_test(NAME <name> COMMAND <command> [<arg>...]
            [CONFIGURATIONS <config>...]
            [WORKING_DIRECTORY <dir>])
 
-Add a test called ``<name>``.  The test name may not contain spaces,
+Adds a test called ``<name>``.  The test name may not contain spaces,
 quotes, or other characters special in CMake syntax.  The options are:
 
 ``COMMAND``
@@ -39,7 +39,9 @@ The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
 expressions" with the syntax ``$<...>``.  See the
 :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
-Example usage::
+Example usage:
+
+.. code-block:: cmake
 
   add_test(NAME mytest
            COMMAND testDriver --config $<CONFIGURATION>
@@ -53,11 +55,12 @@ file produced by target ``myexe``.
 
   CMake will generate tests only if the :command:`enable_testing`
   command has been invoked.  The :module:`CTest` module invokes the
-  command automatically when the ``BUILD_TESTING`` option is ``ON``.
+  command automatically unless the ``BUILD_TESTING`` option is turned
+  ``OFF``.
 
 ---------------------------------------------------------------------
 
-::
+.. code-block:: cmake
 
   add_test(<name> <command> [<arg>...])
 

Help/command/aux_source_directory.rst

@@ -3,7 +3,7 @@ aux_source_directory
 
 Find all source files in a directory.
 
-::
+.. code-block:: cmake
 
   aux_source_directory(<dir> <variable>)
 
@@ -11,14 +11,14 @@ Collects the names of all the source files in the specified directory
 and stores the list in the ``<variable>`` provided.  This command is
 intended to be used by projects that use explicit template
 instantiation.  Template instantiation files can be stored in a
-"Templates" subdirectory and collected automatically using this
+``Templates`` subdirectory and collected automatically using this
 command to avoid manually listing all instantiations.
 
 It is tempting to use this command to avoid writing the list of source
 files for a library or executable target.  While this seems to work,
 there is no way for CMake to generate a build system that knows when a
 new source file has been added.  Normally the generated build system
-knows when it needs to rerun CMake because the CMakeLists.txt file is
+knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is
 modified to add a new source.  When the source is just added to the
 directory without modifying this file, one would have to manually
 rerun CMake to generate a build system incorporating the new file.

Help/command/break.rst

@@ -3,10 +3,10 @@ break
 
 Break from an enclosing foreach or while loop.
 
-::
+.. code-block:: cmake
 
   break()
 
-Breaks from an enclosing foreach loop or while loop
+Breaks from an enclosing :command:`foreach` or :command:`while` loop.
 
 See also the :command:`continue` command.

Help/command/build_command.rst

@@ -14,7 +14,7 @@ This is mainly intended for internal use by the :module:`CTest` module.
 
 Sets the given ``<variable>`` to a command-line string of the form::
 
- <cmake> --build . [--config <config>] [--target <target>] [-- -i]
+ <cmake> --build . [--config <config>] [--target <target>...] [-- -i]
 
 where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
 tool, and ``<config>`` and ``<target>`` are the values provided to the

Help/command/build_name.rst

@@ -1,7 +1,7 @@
 build_name
 ----------
 
-Disallowed.  See CMake Policy :policy:`CMP0036`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0036`.
 
 Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
 

Help/command/cmake_host_system_information.rst

@@ -3,7 +3,7 @@ cmake_host_system_information
 
 Query host system specific information.
 
-::
+.. code-block:: cmake
 
   cmake_host_system_information(RESULT <variable> QUERY <key> ...)
 

Help/command/cmake_minimum_required.rst

@@ -1,11 +1,15 @@
 cmake_minimum_required
 ----------------------
 
-Set the minimum required version of cmake for a project and
+Require a minimum version of cmake.
-update `Policy Settings`_ to match the version given::
+
+.. code-block:: cmake
 
   cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
 
+Sets the minimum required version of cmake for a project.
+Also updates the policy settings as explained below.
+
 ``<min>`` and the optional ``<max>`` are each CMake versions of the form
 ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
 
@@ -47,13 +51,17 @@ as of a given CMake version and tells newer CMake versions to warn
 about their new policies.
 
 When a ``<min>`` version higher than 2.4 is specified the command
-implicitly invokes::
+implicitly invokes
+
+.. code-block:: cmake
 
   cmake_policy(VERSION <min>[...<max>])
 
 which sets CMake policies based on the range of versions specified.
 When a ``<min>`` version 2.4 or lower is given the command implicitly
-invokes::
+invokes
+
+.. code-block:: cmake
 
   cmake_policy(VERSION 2.4[...<max>])
 

Help/command/cmake_parse_arguments.rst

@@ -1,26 +1,28 @@
 cmake_parse_arguments
 ---------------------
 
-``cmake_parse_arguments`` is intended to be used in macros or functions for
+Parse function or macro arguments.
-parsing the arguments given to that macro or function.  It processes the
-arguments and defines a set of variables which hold the values of the
-respective options.
 
-::
+.. code-block:: cmake
 
   cmake_parse_arguments(<prefix> <options> <one_value_keywords>
-                        <multi_value_keywords> args...)
+                        <multi_value_keywords> <args>...)
 
-  cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
+  cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
-                        <multi_value_keywords>)
+                        <one_value_keywords> <multi_value_keywords>)
 
-The first signature reads processes arguments passed in the ``args...``.
+This command is for use in macros or functions.
+It processes the arguments given to that macro or function,
+and defines a set of variables which hold the values of the
+respective options.
+
+The first signature reads processes arguments passed in the ``<args>...``.
 This may be used in either a :command:`macro` or a :command:`function`.
 
 The ``PARSE_ARGV`` signature is only for use in a :command:`function`
 body.  In this case the arguments that are parsed come from the
 ``ARGV#`` variables of the calling function.  The parsing starts with
-the Nth argument, where ``N`` is an unsigned integer.  This allows for
+the ``<N>``-th argument, where ``<N>`` is an unsigned integer.  This allows for
 the values to have special characters like ``;`` in them.
 
 The ``<options>`` argument contains all options for the respective macro,
@@ -53,12 +55,17 @@ For the ``<options>`` keywords, these will always be defined,
 to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
 
 All remaining arguments are collected in a variable
-``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all argument
+``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
-where recognized. This can be checked afterwards to see
+were recognized. This can be checked afterwards to see
 whether your macro was called with unrecognized parameters.
 
-As an example here a ``my_install()`` macro, which takes similar arguments
+``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
-as the real :command:`install` command:
+values at all are collected in a variable ``<prefix>_KEYWORDS_MISSING_VALUES``
+that will be undefined if all keywords received values. This can be checked
+to see if there were keywords without any values given.
+
+Consider the following example macro, ``my_install()``, which takes similar
+arguments to the real :command:`install` command:
 
 .. code-block:: cmake
 
@@ -75,7 +82,7 @@ Assume ``my_install()`` has been called like this:
 
 .. code-block:: cmake
 
-   my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
+   my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
 
 After the ``cmake_parse_arguments`` call the macro will have set or undefined
 the following variables::
@@ -87,13 +94,16 @@ the following variables::
    MY_INSTALL_TARGETS = "foo;bar"
    MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
    MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
+   MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
+            # No value for "CONFIGURATIONS" given
 
 You can then continue and process these variables.
 
-Keywords terminate lists of values, e.g.  if directly after a
+Keywords terminate lists of values, e.g. if directly after a
-one_value_keyword another recognized keyword follows, this is
+``one_value_keyword`` another recognized keyword follows, this is
 interpreted as the beginning of the new option.  E.g.
 ``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
 ``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
-is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and
+is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
-``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``.
+to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
+therefore be set to ``TRUE``.

Help/command/cmake_policy.rst

@@ -22,7 +22,9 @@ Setting Policies by CMake Version
 
 The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
 behavior.  While setting policies individually is supported, we
-encourage projects to set policies based on CMake versions::
+encourage projects to set policies based on CMake versions:
+
+.. code-block:: cmake
 
   cmake_policy(VERSION <min>[...<max>])
 
@@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too.
 Setting Policies Explicitly
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   cmake_policy(SET CMP<NNNN> NEW)
   cmake_policy(SET CMP<NNNN> OLD)
@@ -66,7 +68,7 @@ policy state to ``NEW``.
 Checking Policy Settings
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   cmake_policy(GET CMP<NNNN> <variable>)
 
@@ -78,14 +80,16 @@ CMake Policy Stack
 ^^^^^^^^^^^^^^^^^^
 
 CMake keeps policy settings on a stack, so changes made by the
-cmake_policy command affect only the top of the stack.  A new entry on
+``cmake_policy`` command affect only the top of the stack.  A new entry on
 the policy stack is managed automatically for each subdirectory to
 protect its parents and siblings.  CMake also manages a new entry for
 scripts loaded by :command:`include` and :command:`find_package` commands
 except when invoked with the ``NO_POLICY_SCOPE`` option
 (see also policy :policy:`CMP0011`).
 The ``cmake_policy`` command provides an interface to manage custom
-entries on the policy stack::
+entries on the policy stack:
+
+.. code-block:: cmake
 
   cmake_policy(PUSH)
   cmake_policy(POP)

Help/command/configure_file.rst

@@ -3,7 +3,7 @@ configure_file
 
 Copy a file to another location and modify its contents.
 
-::
+.. code-block:: cmake
 
   configure_file(<input> <output>
                  [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
@@ -13,15 +13,21 @@ Copies an ``<input>`` file to an ``<output>`` file and substitutes
 variable values referenced as ``@VAR@`` or ``${VAR}`` in the input
 file content.  Each variable reference will be replaced with the
 current value of the variable, or the empty string if the variable
-is not defined.  Furthermore, input lines of the form::
+is not defined.  Furthermore, input lines of the form
+
+.. code-block:: c
 
   #cmakedefine VAR ...
 
-will be replaced with either::
+will be replaced with either
+
+.. code-block:: c
 
   #define VAR ...
 
-or::
+or
+
+.. code-block:: c
 
   /* #undef VAR */
 
@@ -33,12 +39,16 @@ either ``#define VAR 1`` or ``#define VAR 0`` similarly.
 The result lines (with the exception of the ``#undef`` comments) can be
 indented using spaces and/or tabs between the ``#`` character
 and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
-indentation will be preserved in the output lines::
+indentation will be preserved in the output lines:
+
+.. code-block:: c
 
   #  cmakedefine VAR
   #  cmakedefine01 VAR
 
-will be replaced, if ``VAR`` is defined, with::
+will be replaced, if ``VAR`` is defined, with
+
+.. code-block:: c
 
   #  define VAR
   #  define VAR 1

Help/command/continue.rst

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

Help/command/create_test_sourcelist.rst

@@ -3,7 +3,7 @@ create_test_sourcelist
 
 Create a test driver and source list for building test programs.
 
-::
+.. code-block:: cmake
 
   create_test_sourcelist(sourceListName driverName
                          test1 test2 test3

Help/command/ctest_build.rst

@@ -50,9 +50,7 @@ The options are:
   for an example.
 
 ``PROJECT_NAME <project-name>``
-  Set the name of the project to build.  This should correspond
+  Ignored.  This was once used but is no longer needed.
-  to the top-level call to the :command:`project` command.
-  If not specified the ``CTEST_PROJECT_NAME`` variable will be checked.
 
 ``TARGET <target-name>``
   Specify the name of a target to build.  If not specified the

Help/command/ctest_submit.rst

@@ -6,6 +6,8 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
 ::
 
   ctest_submit([PARTS <part>...] [FILES <file>...]
+               [SUBMIT_URL <url>]
+               [BUILD_ID <result-var>]
                [HTTPHEADER <header>]
                [RETRY_COUNT <count>]
                [RETRY_DELAY <delay>]
@@ -33,14 +35,31 @@ The options are:
     ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
     Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
     Submit     = nothing
+    Done       = Build is complete, in Done.xml
 
 ``FILES <file>...``
   Specify an explicit list of specific files to be submitted.
   Each individual file must exist at the time of the call.
 
+``SUBMIT_URL <url>``
+  The ``http`` or ``https`` URL of the dashboard server to send the submission
+  to.  If not given, the :variable:`CTEST_SUBMIT_URL` variable is used.
+
+``BUILD_ID <result-var>``
+  Store in the ``<result-var>`` variable the ID assigned to this build by
+  CDash.
+
 ``HTTPHEADER <HTTP-header>``
   Specify HTTP header to be included in the request to CDash during submission.
-  This suboption can be repeated several times.
+  For example, CDash can be configured to only accept submissions from
+  authenticated clients. In this case, you should provide a bearer token in your
+  header:
+
+  .. code-block:: cmake
+
+    ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
+
+  This suboption can be repeated several times for multiple headers.
 
 ``RETRY_COUNT <count>``
   Specify how many times to retry a timed-out submission.
@@ -67,6 +86,7 @@ Submit to CDash Upload API
 ::
 
   ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
+               [SUBMIT_URL <url>]
                [HTTPHEADER <header>]
                [RETRY_COUNT <count>]
                [RETRY_DELAY <delay>]
@@ -79,5 +99,6 @@ with a content hash of the file. If CDash does not already have the file,
 then it is uploaded. Along with the file, a CDash type string is specified
 to tell CDash which handler to use to process the data.
 
-This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``,
+This signature accepts the ``SUBMIT_URL``, ``BUILD_ID``, ``HTTPHEADER``,
-``RETURN_VALUE`` and ``QUIET`` options as described above.
+``RETRY_COUNT``, ``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options
+as described above.

Help/command/ctest_update.rst

@@ -35,4 +35,5 @@ The options are:
 
 The update always follows the version control branch currently checked
 out in the source directory.  See the :ref:`CTest Update Step`
-documentation for more information.
+documentation for information about variables that change the behavior
+of ``ctest_update()``.

Help/command/define_property.rst

@@ -3,7 +3,7 @@ define_property
 
 Define and document custom properties.
 
-::
+.. code-block:: cmake
 
   define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                    TEST | VARIABLE | CACHED_VARIABLE>
@@ -11,7 +11,7 @@ Define and document custom properties.
                    BRIEF_DOCS <brief-doc> [docs...]
                    FULL_DOCS <full-doc> [docs...])
 
-Define one property in a scope for use with the :command:`set_property` and
+Defines one property in a scope for use with the :command:`set_property` and
 :command:`get_property` commands.  This is primarily useful to associate
 documentation with property names that may be retrieved with the
 :command:`get_property` command. The first argument determines the kind of

Help/command/else.rst

@@ -3,8 +3,8 @@ else
 
 Starts the else portion of an if block.
 
-::
+.. code-block:: cmake
 
-  else(expression)
+  else([<condition>])
 
 See the :command:`if` command.

Help/command/elseif.rst

@@ -1,10 +1,11 @@
 elseif
 ------
 
-Starts the elseif portion of an if block.
+Starts an elseif portion of an if block.
 
-::
+.. code-block:: cmake
 
-  elseif(expression)
+  elseif(<condition>)
 
-See the :command:`if` command.
+See the :command:`if` command, especially for the syntax and logic
+of the ``<condition>``.

Help/command/enable_language.rst

@@ -3,12 +3,12 @@ enable_language
 
 Enable a language (CXX/C/Fortran/etc)
 
-::
+.. code-block:: cmake
 
   enable_language(<lang> [OPTIONAL] )
 
-This command enables support for the named language in CMake.  This is
+Enables support for the named language in CMake.  This is
-the same as the project command but does not create any of the extra
+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``.
 

Help/command/enable_testing.rst

@@ -3,11 +3,18 @@ enable_testing
 
 Enable testing for current directory and below.
 
-::
+.. code-block:: cmake
 
   enable_testing()
 
-Enables testing for this directory and below.  See also the
+Enables testing for this directory and below.
-:command:`add_test` command.  Note that ctest expects to find a test file
+
-in the build directory root.  Therefore, this command should be in the
+This command should be in the source directory root
-source directory root.
+because ctest expects to find a test file in the build
+directory root.
+
+This command is automatically invoked when the :module:`CTest`
+module is included, except if the ``BUILD_TESTING`` option is
+turned off.
+
+See also the :command:`add_test` command.

Help/command/endforeach.rst

@@ -3,8 +3,12 @@ endforeach
 
 Ends a list of commands in a foreach block.
 
-::
+.. code-block:: cmake
 
-  endforeach(expression)
+  endforeach([<loop_var>])
 
 See the :command:`foreach` command.
+
+The optional ``<loop_var>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of
+the opening ``foreach`` clause.

Help/command/endfunction.rst

@@ -3,8 +3,12 @@ endfunction
 
 Ends a list of commands in a function block.
 
-::
+.. code-block:: cmake
 
-  endfunction(expression)
+  endfunction([<name>])
 
 See the :command:`function` command.
+
+The optional ``<name>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the ``<name>`` argument
+of the opening ``function`` command.

Help/command/endif.rst

@@ -3,8 +3,12 @@ endif
 
 Ends a list of commands in an if block.
 
-::
+.. code-block:: cmake
 
-  endif(expression)
+  endif([<condition>])
 
 See the :command:`if` command.
+
+The optional ``<condition>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the argument of the opening
+``if`` clause.

Help/command/endmacro.rst

@@ -3,8 +3,12 @@ endmacro
 
 Ends a list of commands in a macro block.
 
-::
+.. code-block:: cmake
 
-  endmacro(expression)
+  endmacro([<name>])
 
 See the :command:`macro` command.
+
+The optional ``<name>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the ``<name>`` argument
+of the opening ``macro`` command.

Help/command/endwhile.rst

@@ -3,8 +3,12 @@ endwhile
 
 Ends a list of commands in a while block.
 
-::
+.. code-block:: cmake
 
-  endwhile(expression)
+  endwhile([<condition>])
 
 See the :command:`while` command.
+
+The optional ``<condition>`` argument is supported for backward compatibility
+only. If used it must be a verbatim repeat of the argument of the opening
+``while`` clause.

Help/command/exec_program.rst

@@ -1,7 +1,9 @@
 exec_program
 ------------
 
-Deprecated.  Use the :command:`execute_process` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`execute_process` command instead.
 
 Run an executable program during the processing of the CMakeList.txt
 file.

Help/command/execute_process.rst

@@ -5,8 +5,8 @@ Execute one or more child processes.
 
 .. code-block:: cmake
 
-  execute_process(COMMAND <cmd1> [args1...]]
+  execute_process(COMMAND <cmd1> [<arguments>]
-                  [COMMAND <cmd2> [args2...] [...]]
+                  [COMMAND <cmd2> [<arguments>]]...
                   [WORKING_DIRECTORY <directory>]
                   [TIMEOUT <seconds>]
                   [RESULT_VARIABLE <variable>]
@@ -18,11 +18,14 @@ Execute one or more child processes.
                   [ERROR_FILE <file>]
                   [OUTPUT_QUIET]
                   [ERROR_QUIET]
+                  [COMMAND_ECHO <where>]
                   [OUTPUT_STRIP_TRAILING_WHITESPACE]
                   [ERROR_STRIP_TRAILING_WHITESPACE]
                   [ENCODING <name>])
 
-Runs the given sequence of one or more commands in parallel with the standard
+Runs the given sequence of one or more commands.
+
+Commands are executed concurrently as a pipeline, with the standard
 output of each process piped to the standard input of the next.
 A single standard error pipe is used for all processes.
 
@@ -46,8 +49,9 @@ Options:
  the child processes.
 
 ``TIMEOUT``
- The child processes will be terminated if they do not finish in the
+ After the specified number of seconds (fractions allowed), all unfinished
- specified number of seconds (fractions are allowed).
+ child processes will be terminated, and the ``RESULT_VARIABLE`` will be
+ set to a string mentioning the "timeout".
 
 ``RESULT_VARIABLE``
  The variable will be set to contain the result of last child process.
@@ -56,9 +60,9 @@ Options:
 
 ``RESULTS_VARIABLE <variable>``
  The variable will be set to contain the result of all processes as a
- :ref:`;-list <CMake Language Lists>`, in order of the given ``COMMAND``
+ :ref:`semicolon-separated list <CMake Language Lists>`, in order of the
- arguments.  Each entry will be an integer return code from the
+ given ``COMMAND`` arguments.  Each entry will be an integer return code
- corresponding child or a string describing an error condition.
+ from the corresponding child or a string describing an error condition.
 
 ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
  The variable named will be set with the contents of the standard output
@@ -74,6 +78,12 @@ Options:
 ``OUTPUT_QUIET``, ``ERROR_QUIET``
  The standard output or standard error results will be quietly ignored.
 
+``COMMAND_ECHO <where>``
+ The command being run will be echo'ed to ``<where>`` with ``<where>``
+ being set to one of ``STDERR``, ``STDOUT`` or ``NONE``.
+ See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way
+ to control the default behavior when this option is not present.
+
 ``ENCODING <name>``
  On Windows, the encoding that is used to decode output from the process.
  Ignored on other platforms.

Help/command/export.rst

@@ -3,11 +3,11 @@ export
 
 Export targets from the build tree for use by outside projects.
 
-::
+.. code-block:: cmake
 
   export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
 
-Create a file ``<filename>`` that may be included by outside projects to
+Creates a file ``<filename>`` that may be included by outside projects to
 import targets from the current project's build tree.  This is useful
 during cross-compiling to build utility executables that can run on
 the host platform in one project and then import them into another
@@ -25,7 +25,7 @@ export targets from an installation tree.
 The properties set on the generated IMPORTED targets will have the
 same values as the final values of the input TARGETS.
 
-::
+.. code-block:: cmake
 
   export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
          [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
@@ -49,12 +49,12 @@ unspecified.
   transitive usage requirements of other targets that link to the
   object libraries in their implementation.
 
-::
+.. code-block:: cmake
 
   export(PACKAGE <PackageName>)
 
 Store the current build directory in the CMake user package registry
-for package ``<PackageName>``.  The find_package command may consider the
+for package ``<PackageName>``.  The :command:`find_package` command may consider the
 directory while searching for package ``<PackageName>``.  This helps dependent
 projects find and use a package from the current project's build tree
 without help from the user.  Note that the entry in the package
@@ -62,10 +62,15 @@ registry that this command creates works only in conjunction with a
 package configuration file (``<PackageName>Config.cmake``) that works with the
 build tree. In some cases, for example for packaging and for system
 wide installations, it is not desirable to write the user package
-registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
+registry.
-is enabled, the ``export(PACKAGE)`` command will do nothing.
 
-::
+By default the ``export(PACKAGE)`` command does nothing (see policy
+:policy:`CMP0090`) because populating the user package registry has effects
+outside the source and build trees.  Set the
+:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to
+the CMake user package registry.
+
+.. code-block:: cmake
 
   export(TARGETS [target1 [target2 [...]]]  [ANDROID_MK <filename>])
 

Help/command/export_library_dependencies.rst

@@ -1,7 +1,7 @@
 export_library_dependencies
 ---------------------------
 
-Disallowed.  See CMake Policy :policy:`CMP0033`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0033`.
 
 Use :command:`install(EXPORT)` or :command:`export` command.
 

Help/command/file.rst

@@ -25,6 +25,9 @@ Synopsis
     file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
     file(`MAKE_DIRECTORY`_ [<dir>...])
     file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
+    file(`SIZE`_ <filename> <out-var>)
+    file(`READ_SYMLINK`_ <linkname> <out-var>)
+    file(`CREATE_LINK`_ <original> <linkname> [...])
 
   `Path Conversion`_
     file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
@@ -42,7 +45,7 @@ Reading
 
 .. _READ:
 
-::
+.. code-block:: cmake
 
   file(READ <filename> <variable>
        [OFFSET <offset>] [LIMIT <max-in>] [HEX])
@@ -54,7 +57,7 @@ be converted to a hexadecimal representation (useful for binary data).
 
 .. _STRINGS:
 
-::
+.. code-block:: cmake
 
   file(STRINGS <filename> <variable> [<options>...])
 
@@ -105,7 +108,7 @@ from the input file.
 
 .. _HASH:
 
-::
+.. code-block:: cmake
 
   file(<HASH> <filename> <variable>)
 
@@ -116,7 +119,7 @@ command.
 
 .. _TIMESTAMP:
 
-::
+.. code-block:: cmake
 
   file(TIMESTAMP <filename> <variable> [<format>] [UTC])
 
@@ -133,7 +136,7 @@ Writing
 .. _WRITE:
 .. _APPEND:
 
-::
+.. code-block:: cmake
 
   file(WRITE <filename> <content>...)
   file(APPEND <filename> <content>...)
@@ -150,7 +153,7 @@ to update the file only when its content changes.
 .. _TOUCH:
 .. _TOUCH_NOCREATE:
 
-::
+.. code-block:: cmake
 
   file(TOUCH [<files>...])
   file(TOUCH_NOCREATE [<files>...])
@@ -167,7 +170,7 @@ modified.
 
 .. _GENERATE:
 
-::
+.. code-block:: cmake
 
   file(GENERATE OUTPUT output-file
        <INPUT input-file|CONTENT content>
@@ -217,7 +220,7 @@ Filesystem
 .. _GLOB:
 .. _GLOB_RECURSE:
 
-::
+.. code-block:: cmake
 
   file(GLOB <variable>
        [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
@@ -272,7 +275,7 @@ Examples of recursive globbing include::
 
 .. _RENAME:
 
-::
+.. code-block:: cmake
 
   file(RENAME <oldname> <newname>)
 
@@ -282,18 +285,19 @@ Move a file or directory within a filesystem from ``<oldname>`` to
 .. _REMOVE:
 .. _REMOVE_RECURSE:
 
-::
+.. code-block:: cmake
 
   file(REMOVE [<files>...])
   file(REMOVE_RECURSE [<files>...])
 
 Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
 files and directories, also non-empty directories. No error is emitted if a
-given file does not exist.
+given file does not exist.  Relative input paths are evaluated with respect
+to the current source directory.  Empty input paths are ignored with a warning.
 
 .. _MAKE_DIRECTORY:
 
-::
+.. code-block:: cmake
 
   file(MAKE_DIRECTORY [<directories>...])
 
@@ -302,12 +306,13 @@ Create the given directories and their parents as needed.
 .. _COPY:
 .. _INSTALL:
 
-::
+.. code-block:: cmake
 
   file(<COPY|INSTALL> <files>... DESTINATION <dir>
        [FILE_PERMISSIONS <permissions>...]
        [DIRECTORY_PERMISSIONS <permissions>...]
        [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
+       [FOLLOW_SYMLINK_CHAIN]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
         [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
@@ -321,6 +326,32 @@ at the destination with the same timestamp.  Copying preserves input
 permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
 are given (default is ``USE_SOURCE_PERMISSIONS``).
 
+If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve
+the symlinks at the paths given until a real file is found, and install
+a corresponding symlink in the destination for each symlink encountered. For
+each symlink that is installed, the resolution is stripped of the directory,
+leaving only the filename, meaning that the new symlink points to a file in
+the same directory as the symlink. This feature is useful on some Unix systems,
+where libraries are installed as a chain of symlinks with version numbers, with
+less specific versions pointing to more specific versions.
+``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library
+itself into the destination directory. For example, if you have the following
+directory structure:
+
+* ``/opt/foo/lib/libfoo.so.1.2.3``
+* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3``
+* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2``
+* ``/opt/foo/lib/libfoo.so -> libfoo.so.1``
+
+and you do:
+
+.. code-block:: cmake
+
+  file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
+
+This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
+``lib``.
+
 See the :command:`install(DIRECTORY)` command for documentation of
 permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
 ``EXCLUDE`` options.  Copying directories preserves the structure
@@ -333,12 +364,67 @@ and ``NO_SOURCE_PERMISSIONS`` is default.
 Installation scripts generated by the :command:`install` command
 use this signature (with some undocumented options for internal use).
 
+.. _SIZE:
+
+.. code-block:: cmake
+
+  file(SIZE <filename> <variable>)
+
+Determine the file size of the ``<filename>`` and put the result in
+``<variable>`` variable. Requires that ``<filename>`` is a valid path
+pointing to a file and is readable.
+
+.. _READ_SYMLINK:
+
+.. code-block:: cmake
+
+  file(READ_SYMLINK <linkname> <variable>)
+
+This subcommand queries the symlink ``<linkname>`` and stores the path it
+points to in the result ``<variable>``.  If ``<linkname>`` does not exist or
+is not a symlink, CMake issues a fatal error.
+
+Note that this command returns the raw symlink path and does not resolve
+a relative path.  The following is an example of how to ensure that an
+absolute path is obtained:
+
+.. code-block:: cmake
+
+  set(linkname "/path/to/foo.sym")
+  file(READ_SYMLINK "${linkname}" result)
+  if(NOT IS_ABSOLUTE "${result}")
+    get_filename_component(dir "${linkname}" DIRECTORY)
+    set(result "${dir}/${result}")
+  endif()
+
+.. _CREATE_LINK:
+
+.. code-block:: cmake
+
+  file(CREATE_LINK <original> <linkname>
+       [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
+
+Create a link ``<linkname>`` that points to ``<original>``.
+It will be a hard link by default, but providing the ``SYMBOLIC`` option
+results in a symbolic link instead.  Hard links require that ``original``
+exists and is a file, not a directory.  If ``<linkname>`` already exists,
+it will be overwritten.
+
+The ``<result>`` variable, if specified, receives the status of the operation.
+It is set to ``0`` upon success or an error message otherwise.  If ``RESULT``
+is not specified and the operation fails, a fatal error is emitted.
+
+Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
+creating the link fails.  It can be useful for handling situations such as
+``<original>`` and ``<linkname>`` being on different drives or mount points,
+which would make them unable to support a hard link.
+
 Path Conversion
 ^^^^^^^^^^^^^^^
 
 .. _RELATIVE_PATH:
 
-::
+.. code-block:: cmake
 
   file(RELATIVE_PATH <variable> <directory> <file>)
 
@@ -348,7 +434,7 @@ store it in the ``<variable>``.
 .. _TO_CMAKE_PATH:
 .. _TO_NATIVE_PATH:
 
-::
+.. code-block:: cmake
 
   file(TO_CMAKE_PATH "<path>" <variable>)
   file(TO_NATIVE_PATH "<path>" <variable>)
@@ -370,7 +456,7 @@ Transfer
 .. _DOWNLOAD:
 .. _UPLOAD:
 
-::
+.. code-block:: cmake
 
   file(DOWNLOAD <url> <file> [<options>...])
   file(UPLOAD   <file> <url> [<options>...])
@@ -460,7 +546,7 @@ Locking
 
 .. _LOCK:
 
-::
+.. code-block:: cmake
 
   file(LOCK <path> [DIRECTORY] [RELEASE]
        [GUARD <FUNCTION|FILE|PROCESS>]

Help/command/find_package.rst

@@ -12,7 +12,7 @@ Find an external project, and load its settings.
 Basic Signature and Module Mode
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
                [REQUIRED] [[COMPONENTS] [components...]]
@@ -23,9 +23,9 @@ Finds and loads settings from an external project.  ``<PackageName>_FOUND``
 will be set to indicate whether the package was found.  When the
 package is found package-specific information is provided through
 variables and :ref:`Imported Targets` documented by the package itself.  The
-``QUIET`` option disables messages if the package cannot be found.  The
+``QUIET`` option disables informational messages, including those indicating
-``REQUIRED`` option stops processing with an error message if the package
+that the package cannot be found if it is not ``REQUIRED``.  The ``REQUIRED``
-cannot be found.
+option stops processing with an error message if the package cannot be found.
 
 A package-specific list of required components may be listed after the
 ``COMPONENTS`` option (or after the ``REQUIRED`` option if present).
@@ -51,13 +51,21 @@ mode and "Config" mode.  The above signature selects Module mode.
 If no module is found the command falls back to Config mode, described
 below. This fall back is disabled if the ``MODULE`` option is given.
 
-In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``
+In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``.
-in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation.
+The file is first searched in the :variable:`CMAKE_MODULE_PATH`,
+then among the :ref:`Find Modules` provided by the CMake installation.
 If the file is found, it is read and processed by CMake.  It is responsible
 for finding the package, checking the version, and producing any needed
 messages.  Some find-modules provide limited or no support for versioning;
 check the module documentation.
 
+If the ``MODULE`` option is not specfied in the above signature,
+CMake first searches for the package using Module mode. Then, if the
+package is not found, it searches again using Config mode. A user
+may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to
+``TRUE`` to direct CMake first search using Config mode before falling
+back to Module mode.
+
 Full Signature and Config Mode
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -67,7 +75,9 @@ full command signature and details of the search process.  Project
 maintainers wishing to provide a package to be found by this command
 are encouraged to read on.
 
-The complete Config mode command signature is::
+The complete Config mode command signature is
+
+.. code-block:: cmake
 
   find_package(<PackageName> [version] [EXACT] [QUIET]
                [REQUIRED] [[COMPONENTS] [components...]]
@@ -177,7 +187,7 @@ sets these variables:
 
 These variables are checked by the ``find_package`` command to determine
 whether the configuration file provides an acceptable version.  They
-are not available after the find_package call returns.  If the version
+are not available after the ``find_package`` call returns.  If the version
 is acceptable the following variables are set:
 
 ``<PackageName>_VERSION``
@@ -202,7 +212,9 @@ is set no attempt is made to choose a highest or closest version number.
 To control the order in which ``find_package`` checks for compatibility use
 the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
 :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
-For instance in order to select the highest version one can set::
+For instance in order to select the highest version one can set
+
+.. code-block:: cmake
 
   SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
   SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
@@ -215,8 +227,8 @@ Search Procedure
 CMake constructs a set of possible installation prefixes for the
 package.  Under each prefix several directories are searched for a
 configuration file.  The tables below show the directories searched.
-Each entry is meant for installation trees following Windows (W), UNIX
+Each entry is meant for installation trees following Windows (``W``), UNIX
-(U), or Apple (A) conventions::
+(``U``), or Apple (``A``) conventions::
 
   <prefix>/                                                       (W)
   <prefix>/(cmake|CMake)/                                         (W)
@@ -229,8 +241,8 @@ Each entry is meant for installation trees following Windows (W), UNIX
   <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/               (W/U)
   <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
 
-On systems supporting macOS Frameworks and Application Bundles the
+On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the
-following directories are searched for frameworks or bundles
+following directories are searched for Frameworks or Application Bundles
 containing a configuration file::
 
   <prefix>/<name>.framework/Resources/                    (A)
@@ -257,16 +269,16 @@ that order).
 * The ``lib`` path is always searched.
 
 If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
-(W) or (U) directory entry one-by-one.
+(``W``) or (``U``) directory entry one-by-one.
 
 This set of directories is intended to work in cooperation with
 projects that provide configuration files in their installation trees.
-Directories above marked with (W) are intended for installations on
+Directories above marked with (``W``) are intended for installations on
 Windows where the prefix may point at the top of an application's
-installation directory.  Those marked with (U) are intended for
+installation directory.  Those marked with (``U``) are intended for
 installations on UNIX platforms where the prefix is shared by multiple
-packages.  This is merely a convention, so all (W) and (U) directories
+packages.  This is merely a convention, so all (``W``) and (``U``) directories
-are still searched on all platforms.  Directories marked with (A) are
+are still searched on all platforms.  Directories marked with (``A``) are
 intended for installations on Apple platforms.  The
 :variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE`
 variables determine the order of preference.
@@ -286,7 +298,7 @@ enabled.
 
 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:`;-lists <CMake Language Lists>`.
+   The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
    This can be skipped if ``NO_CMAKE_PATH`` is passed::
 
      CMAKE_PREFIX_PATH
@@ -349,6 +361,11 @@ enabled.
 .. include:: FIND_XXX_ROOT.txt
 .. include:: FIND_XXX_ORDER.txt
 
+By default the value stored in the result variable will be the path at
+which the file is found.  The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS`
+variable may be set to ``TRUE`` before calling ``find_package`` in order
+to resolve symbolic links and store the real path to the file.
+
 Every non-REQUIRED ``find_package`` call can be disabled by setting the
 :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.
 

Help/command/fltk_wrap_ui.rst

@@ -3,7 +3,7 @@ fltk_wrap_ui
 
 Create FLTK user interfaces Wrappers.
 
-::
+.. code-block:: cmake
 
   fltk_wrap_ui(resultingLibraryName source1
                source2 ... sourceN )

Help/command/foreach.rst

@@ -3,45 +3,82 @@ foreach
 
 Evaluate a group of commands for each value in a list.
 
+.. code-block:: cmake
+
+  foreach(<loop_var> <items>)
+    <commands>
+  endforeach()
+
+where ``<items>`` is a list of items that are separated by
+semicolon or whitespace.
+All commands between ``foreach`` and the matching ``endforeach`` are recorded
+without being invoked.  Once the ``endforeach`` is evaluated, the recorded
+list of commands is invoked once for each item in ``<items>``.
+At the beginning of each iteration the variable ``loop_var`` will be set
+to the value of the current item.
+
+The commands :command:`break` and :command:`continue` provide means to
+escape from the normal control flow.
+
+Per legacy, the :command:`endforeach` command admits
+an optional ``<loop_var>`` argument.
+If used, it must be a verbatim
+repeat of the argument of the opening
+``foreach`` command.
+
+.. code-block:: cmake
+
+  foreach(<loop_var> RANGE <stop>)
+
+In this variant, ``foreach`` iterates over the numbers
+0, 1, ... up to (and including) the nonnegative integer ``<stop>``.
+
+.. code-block:: cmake
+
+  foreach(<loop_var> RANGE <start> <stop> [<step>])
+
+In this variant, ``foreach`` iterates over the numbers from
+``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
+If ``<step>`` is not specified, then the step size is 1.
+The three arguments ``<start>`` ``<stop>`` ``<step>`` must
+all be nonnegative integers, and ``<stop>`` must not be
+smaller than ``<start>``; otherwise you enter the danger zone
+of undocumented behavior that may change in future releases.
+
+.. code-block:: cmake
+
+  foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
+
+In this variant, ``<lists>`` is a whitespace or semicolon
+separated list of list-valued variables. The ``foreach``
+command iterates over each item in each given list.
+The ``<items>`` following the ``ITEMS`` keyword are processed
+as in the first variant of the ``foreach`` command.
+The forms ``LISTS A`` and ``ITEMS ${A}`` are
+equivalent.
+
+The following example shows how the ``LISTS`` option is
+processed:
+
+.. code-block:: cmake
+
+  set(A 0;1)
+  set(B 2 3)
+  set(C "4 5")
+  set(D 6;7 8)
+  set(E "")
+  foreach(X IN LISTS A B C D E)
+      message(STATUS "X=${X}")
+  endforeach()
+
+yields
 ::
 
-  foreach(loop_var arg1 arg2 ...)
+  -- X=0
-    COMMAND1(ARGS ...)
+  -- X=1
-    COMMAND2(ARGS ...)
+  -- X=2
-    ...
+  -- X=3
-  endforeach(loop_var)
+  -- X=4 5
-
+  -- X=6
-All commands between foreach and the matching endforeach are recorded
+  -- X=7
-without being invoked.  Once the endforeach is evaluated, the recorded
+  -- X=8
-list of commands is invoked once for each argument listed in the
-original foreach command.  Before each iteration of the loop
-``${loop_var}`` will be set as a variable with the current value in the
-list.
-
-::
-
-  foreach(loop_var RANGE total)
-  foreach(loop_var RANGE start stop [step])
-
-Foreach can also iterate over a generated range of numbers.  There are
-three types of this iteration:
-
-* When specifying single number, the range will have elements [0, ... to
-  "total"] (inclusive).
-
-* When specifying two numbers, the range will have elements from the
-  first number to the second number (inclusive).
-
-* The third optional number is the increment used to iterate from the
-  first number to the second number (inclusive).
-
-::
-
-  foreach(loop_var IN [LISTS [list1 [...]]]
-                      [ITEMS [item1 [...]]])
-
-Iterates over a precise list of items.  The ``LISTS`` option names
-list-valued variables to be traversed, including empty elements (an
-empty string is a zero-length list).  (Note macro
-arguments are not variables.)  The ``ITEMS`` option ends argument
-parsing and includes all arguments following it in the iteration.

Help/command/function.rst

@@ -1,36 +1,70 @@
 function
 --------
 
-Start recording a function for later invocation as a command::
+Start recording a function for later invocation as a command.
 
-  function(<name> [arg1 [arg2 [arg3 ...]]])
+.. code-block:: cmake
-    COMMAND1(ARGS ...)
-    COMMAND2(ARGS ...)
-    ...
-  endfunction(<name>)
 
-Define a function named ``<name>`` that takes arguments named ``arg1``,
+  function(<name> [<arg1> ...])
-``arg2``, ``arg3``, (...).
+    <commands>
-Commands listed after function, but before the matching
+  endfunction()
-:command:`endfunction()`, are not invoked until the function is invoked.
+
-When it is invoked, the commands recorded in the function are first
+Defines a function named ``<name>`` that takes arguments named
-modified by replacing formal parameters (``${arg1}``) with the arguments
+``<arg1>``, ...  The ``<commands>`` in the function definition
-passed, and then invoked as normal commands.
+are recorded; they are not executed until the function is invoked.
-In addition to referencing the formal parameters you can reference the
+
-``ARGC`` variable which will be set to the number of arguments passed
+Per legacy, the :command:`endfunction` command admits an optional
-into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ...  which
+``<name>`` argument. If used, it must be a verbatim repeat of the
-will have the actual values of the arguments passed in.
+argument of the opening ``function`` command.
-This facilitates creating functions with optional arguments.
-Additionally ``ARGV`` holds the list of all arguments given to the
-function and ``ARGN`` holds the list of arguments past the last expected
-argument.
-Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined
-behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
-to ensure that ``ARGV#`` was passed to the function as an extra
-argument.
 
 A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
 details.
 
 See the :command:`cmake_policy()` command documentation for the behavior
 of policies inside functions.
+
+See the :command:`macro()` command documentation for differences
+between CMake functions and macros.
+
+Invocation
+^^^^^^^^^^
+
+The function invocation is case-insensitive. A function defined as
+
+.. code-block:: cmake
+
+  function(foo)
+    <commands>
+  endfunction()
+
+can be invoked through any of
+
+.. code-block:: cmake
+
+  foo()
+  Foo()
+  FOO()
+
+and so on. However, it is strongly recommended to stay with the
+case chosen in the function definition. Typically functions use
+all-lowercase names.
+
+Arguments
+^^^^^^^^^
+
+When the function is invoked, the recorded ``<commands>`` are first
+modified by replacing formal parameters (``${arg1}``, ...) with the
+arguments passed, and then invoked as normal commands.
+
+In addition to referencing the formal parameters you can reference the
+``ARGC`` variable which will be set to the number of arguments passed
+into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ...  which
+will have the actual values of the arguments passed in.  This facilitates
+creating functions with optional arguments.
+
+Furthermore, ``ARGV`` holds the list of all arguments given to the
+function and ``ARGN`` holds the list of arguments past the last expected
+argument.  Referencing to ``ARGV#`` arguments beyond ``ARGC`` have
+undefined behavior.  Checking that ``ARGC`` is greater than ``#`` is
+the only way to ensure that ``ARGV#`` was passed to the function as an
+extra argument.

Help/command/get_cmake_property.rst

@@ -3,14 +3,14 @@ get_cmake_property
 
 Get a global property of the CMake instance.
 
-::
+.. code-block:: cmake
 
-  get_cmake_property(VAR property)
+  get_cmake_property(<var> <property>)
 
-Get a global property from the CMake instance.  The value of the property is
+Gets a global property from the CMake instance.  The value of
-stored in the variable ``VAR``.  If the property is not found, ``VAR``
+the ``<property>`` is stored in the variable ``<var>``.
-will be  set to "NOTFOUND".  See the :manual:`cmake-properties(7)` manual
+If the property is not found, ``<var>`` will be set to ``NOTFOUND``.
-for available properties.
+See the :manual:`cmake-properties(7)` manual for available properties.
 
 See also the :command:`get_property` command ``GLOBAL`` option.
 

Help/command/get_directory_property.rst

@@ -3,11 +3,11 @@ get_directory_property
 
 Get a property of ``DIRECTORY`` scope.
 
-::
+.. code-block:: cmake
 
   get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
 
-Store a property of directory scope in the named ``<variable>``.
+Stores a property of directory scope in the named ``<variable>``.
 The ``DIRECTORY`` argument specifies another directory from which
 to retrieve the property value instead of the current directory.
 The specified directory must have already been traversed by CMake.
@@ -18,7 +18,7 @@ if the property is not found for the nominated directory scope,
 the search will chain to a parent scope as described for the
 :command:`define_property` command.
 
-::
+.. code-block:: cmake
 
   get_directory_property(<variable> [DIRECTORY <dir>]
                          DEFINITION <var-name>)

Help/command/get_filename_component.rst

@@ -3,13 +3,11 @@ get_filename_component
 
 Get a specific component of a full filename.
 
-------------------------------------------------------------------------------
+.. code-block:: cmake
 
-::
+  get_filename_component(<var> <FileName> <mode> [CACHE])
 
-  get_filename_component(<VAR> <FileName> <COMP> [CACHE])
+Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:
-
-Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of:
 
 ::
 
@@ -17,22 +15,19 @@ Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of:
  NAME      = File name without directory
  EXT       = File name longest extension (.b.c from d/a.b.c)
  NAME_WE   = File name without directory or longest extension
+ LAST_EXT  = File name last extension (.c from d/a.b.c)
+ NAME_WLE  = File name without directory or last extension
  PATH      = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
 
 Paths are returned with forward slashes and have no trailing slashes.
-The longest file extension is always considered.  If the optional
+If the optional ``CACHE`` argument is specified, the result variable is
-``CACHE`` argument is specified, the result variable is added to the
+added to the cache.
-cache.
 
-------------------------------------------------------------------------------
+.. code-block:: cmake
 
-::
+  get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
 
-  get_filename_component(<VAR> <FileName>
+Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
-                         <COMP> [BASE_DIR <BASE_DIR>]
-                         [CACHE])
-
-Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one
 of:
 
 ::
@@ -41,7 +36,7 @@ of:
  REALPATH  = Full path to existing file with symlinks resolved
 
 If the provided ``<FileName>`` is a relative path, it is evaluated relative
-to the given base directory ``<BASE_DIR>``.  If no base directory is
+to the given base directory ``<dir>``.  If no base directory is
 provided, the default base directory will be
 :variable:`CMAKE_CURRENT_SOURCE_DIR`.
 
@@ -49,16 +44,12 @@ Paths are returned with forward slashes and have no trailing slashes.  If the
 optional ``CACHE`` argument is specified, the result variable is added to the
 cache.
 
-------------------------------------------------------------------------------
+.. code-block:: cmake
 
-::
+  get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
-
-  get_filename_component(<VAR> <FileName>
-                         PROGRAM [PROGRAM_ARGS <ARG_VAR>]
-                         [CACHE])
 
 The program in ``<FileName>`` will be found in the system search path or
 left as a full path.  If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
 any command-line arguments present in the ``<FileName>`` string are split
-from the program name and stored in ``<ARG_VAR>``.  This is used to
+from the program name and stored in ``<arg_var>``.  This is used to
 separate a program name from its arguments in a command line string.

Help/command/get_property.rst

@@ -3,32 +3,33 @@ get_property
 
 Get a property.
 
-::
+.. code-block:: cmake
 
   get_property(<variable>
                <GLOBAL             |
-                DIRECTORY [dir]    |
+                DIRECTORY [<dir>]  |
                 TARGET    <target> |
                 SOURCE    <source> |
                 INSTALL   <file>   |
                 TEST      <test>   |
                 CACHE     <entry>  |
-                VARIABLE>
+                VARIABLE           >
                PROPERTY <name>
                [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
 
-Get one property from one object in a scope.  The first argument
+Gets one property from one object in a scope.
-specifies the variable in which to store the result.  The second
+
-argument determines the scope from which to get the property.  It must
+The first argument specifies the variable in which to store the result.
-be one of the following:
+The second argument determines the scope from which to get the property.
+It must be one of the following:
 
 ``GLOBAL``
   Scope is unique and does not accept a name.
 
 ``DIRECTORY``
   Scope defaults to the current directory but another
-  directory (already processed by CMake) may be named by full or
+  directory (already processed by CMake) may be named by the
-  relative path.
+  full or relative path ``<dir>``.
 
 ``TARGET``
   Scope must name one existing target.
@@ -58,6 +59,7 @@ value indicating whether the property has been set.  If the ``DEFINED``
 option is given the variable is set to a boolean value indicating
 whether the property has been defined such as with the
 :command:`define_property` command.
+
 If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
 string containing documentation for the requested property.  If
 documentation is requested for a property that has not been defined

Help/command/get_source_file_property.rst

@@ -3,11 +3,11 @@ get_source_file_property
 
 Get a property for a source file.
 
-::
+.. code-block:: cmake
 
   get_source_file_property(VAR file property)
 
-Get a property from a source file.  The value of the property is
+Gets a property from a source file.  The value of the property is
 stored in the variable ``VAR``.  If the source property is not found, the
 behavior depends on whether it has been defined to be an ``INHERITED`` property
 or not (see :command:`define_property`).  Non-inherited properties will set

Help/command/get_target_property.rst

@@ -3,7 +3,7 @@ get_target_property
 
 Get a property from a target.
 
-::
+.. code-block:: cmake
 
   get_target_property(VAR target property)
 
@@ -11,7 +11,7 @@ Get a property from a target.  The value of the property is stored in
 the variable ``VAR``.  If the target property is not found, the behavior
 depends on whether it has been defined to be an ``INHERITED`` property
 or not (see :command:`define_property`).  Non-inherited properties will
-set ``VAR`` to "NOTFOUND", whereas inherited properties will search the
+set ``VAR`` to ``NOTFOUND``, whereas inherited properties will search the
 relevant parent scope as described for the :command:`define_property`
 command and if still unable to find the property, ``VAR`` will be set to
 an empty string.
@@ -23,3 +23,5 @@ target so far created.  The targets do not need to be in the current
 ``CMakeLists.txt`` file.
 
 See also the more general :command:`get_property` command.
+
+See :ref:`Target Properties` for the list of properties known to CMake.

Help/command/get_test_property.rst

@@ -3,7 +3,7 @@ get_test_property
 
 Get a property of the test.
 
-::
+.. code-block:: cmake
 
   get_test_property(test property VAR)
 

Help/command/if.rst

@@ -3,41 +3,49 @@ if
 
 Conditionally execute a group of commands.
 
+Synopsis
+^^^^^^^^
+
 .. code-block:: cmake
 
- if(expression)
+  if(<condition>)
-   # then section.
+    <commands>
-   COMMAND1(ARGS ...)
+  elseif(<condition>) # optional block, can be repeated
-   COMMAND2(ARGS ...)
+    <commands>
-   #...
+  else()              # optional block
- elseif(expression2)
+    <commands>
-   # elseif section.
+  endif()
-   COMMAND1(ARGS ...)
-   COMMAND2(ARGS ...)
-   #...
- else(expression)
-   # else section.
-   COMMAND1(ARGS ...)
-   COMMAND2(ARGS ...)
-   #...
- endif(expression)
 
-Evaluates the given expression.  If the result is true, the commands
+Evaluates the ``condition`` argument of the ``if`` clause according to the
-in the THEN section are invoked.  Otherwise, the commands in the else
+`Condition syntax`_ described below. If the result is true, then the
-section are invoked.  The elseif and else sections are optional.  You
+``commands`` in the ``if`` block are executed.
-may have multiple elseif clauses.  Note that the expression in the
+Otherwise, optional ``elseif`` blocks are processed in the same way.
-else and endif clause is optional.  Long expressions can be used and
+Finally, if no ``condition`` is true, ``commands`` in the optional ``else``
-there is a traditional order of precedence.  Parenthetical expressions
+block are executed.
-are evaluated first followed by unary tests such as ``EXISTS``,
+
-``COMMAND``, and ``DEFINED``.  Then any binary tests such as
+Per legacy, the :command:`else` and :command:`endif` commands admit
+an optional ``<condition>`` argument.
+If used, it must be a verbatim
+repeat of the argument of the opening
+``if`` command.
+
+Condition Syntax
+^^^^^^^^^^^^^^^^
+
+The following syntax applies to the ``condition`` argument of
+the ``if``, ``elseif`` and :command:`while` clauses.
+
+Compound conditions are evaluated in the following order of precedence:
+Innermost parentheses are evaluated first. Next come unary tests such
+as ``EXISTS``, ``COMMAND``, and ``DEFINED``.  Then binary tests such as
 ``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``,
 ``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``,
 ``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``,
 ``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``,
-and ``MATCHES`` will be evaluated.  Then boolean ``NOT`` operators and
+and ``MATCHES``.  Then the boolean operators in the order ``NOT``,  ``AND``,
-finally boolean ``AND`` and then ``OR`` operators will be evaluated.
+and finally ``OR``.
 
-Possible expressions are:
+Possible conditions are:
 
 ``if(<constant>)``
  True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
@@ -52,14 +60,14 @@ Possible expressions are:
  True if given a variable that is defined to a value that is not a false
  constant.  False otherwise.  (Note macro arguments are not variables.)
 
-``if(NOT <expression>)``
+``if(NOT <condition>)``
- True if the expression is not true.
+ True if the condition is not true.
 
-``if(<expr1> AND <expr2>)``
+``if(<cond1> AND <cond2>)``
- True if both expressions would be considered true individually.
+ True if both conditions would be considered true individually.
 
-``if(<expr1> OR <expr2>)``
+``if(<cond1> OR <cond2>)``
- True if either expression would be considered true individually.
+ True if either condition would be considered true individually.
 
 ``if(COMMAND command-name)``
  True if the given name is a command, macro or function that can be
@@ -80,7 +88,9 @@ Possible expressions are:
 
 ``if(EXISTS path-to-file-or-directory)``
  True if the named file or directory exists.  Behavior is well-defined
- only for full paths.
+ only for full paths. Resolves symbolic links, i.e. if the named file or
+ directory is a symbolic link, returns true if the target of the
+ symbolic link exists.
 
 ``if(file1 IS_NEWER_THAN file2)``
  True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
@@ -103,7 +113,7 @@ Possible expressions are:
 
 ``if(<variable|string> MATCHES regex)``
  True if the given string or variable's value matches the given regular
- expression.  See :ref:`Regex Specification` for regex format.
+ condition.  See :ref:`Regex Specification` for regex format.
  ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables.
 
 ``if(<variable|string> LESS <variable|string>)``
@@ -179,42 +189,51 @@ Possible expressions are:
 ``if(<variable|string> IN_LIST <variable>)``
  True if the given element is contained in the named list variable.
 
-``if(DEFINED <variable>)``
+``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})``
- True if the given variable is defined.  It does not matter if the
+ True if a variable, cache variable or environment variable
- variable is true or false just if it has been set.  (Note macro
+ with given ``<name>`` is defined. The value of the variable
- arguments are not variables.)
+ does not matter. Note that macro arguments are not variables.
 
-``if((expression) AND (expression OR (expression)))``
+``if((condition) AND (condition OR (condition)))``
- The expressions inside the parenthesis are evaluated first and then
+ The conditions inside the parenthesis are evaluated first and then
- the remaining expression is evaluated as in the previous examples.
+ the remaining condition is evaluated as in the previous examples.
  Where there are nested parenthesis the innermost are evaluated as part
- of evaluating the expression that contains them.
+ of evaluating the condition that contains them.
+
+Variable Expansion
+^^^^^^^^^^^^^^^^^^
 
 The if command was written very early in CMake's history, predating
 the ``${}`` variable evaluation syntax, and for convenience evaluates
 variables named by its arguments as shown in the above signatures.
 Note that normal variable evaluation with ``${}`` applies before the if
-command even receives the arguments.  Therefore code like::
+command even receives the arguments.  Therefore code like
+
+.. code-block:: cmake
 
  set(var1 OFF)
  set(var2 "var1")
  if(${var2})
 
-appears to the if command as::
+appears to the if command as
 
- if(var1)
+.. code-block:: cmake
+
+  if(var1)
 
 and is evaluated according to the ``if(<variable>)`` case documented
 above.  The result is ``OFF`` which is false.  However, if we remove the
-``${}`` from the example then the command sees::
+``${}`` from the example then the command sees
 
- if(var2)
+.. code-block:: cmake
 
-which is true because ``var2`` is defined to "var1" which is not a false
+  if(var2)
+
+which is true because ``var2`` is defined to ``var1`` which is not a false
 constant.
 
 Automatic evaluation applies in the other cases whenever the
-above-documented signature accepts ``<variable|string>``:
+above-documented condition syntax accepts ``<variable|string>``:
 
 * The left hand argument to ``MATCHES`` is first checked to see if it is
   a defined variable, if so the variable's value is used, otherwise the
@@ -252,3 +271,8 @@ specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`.
 A quoted or bracketed variable or keyword will be interpreted as a
 string and not dereferenced or interpreted.
 See policy :policy:`CMP0054`.
+
+There is no automatic evaluation for environment or cache
+:ref:`Variable References`.  Their values must be referenced as
+``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
+condition syntax accepts ``<variable|string>``.

Help/command/include.rst

@@ -3,16 +3,16 @@ include
 
 Load and run CMake code from a file or module.
 
-::
+.. code-block:: cmake
 
-  include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
+  include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
                         [NO_POLICY_SCOPE])
 
-Load and run CMake code from the file given.  Variable reads and
+Loads and runs CMake code from the file given.  Variable reads and
 writes access the scope of the caller (dynamic scoping).  If ``OPTIONAL``
 is present, then no error is raised if the file does not exist.  If
-``RESULT_VARIABLE`` is given the variable will be set to the full filename
+``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
-which has been included or NOTFOUND if it failed.
+full filename which has been included or ``NOTFOUND`` if it failed.
 
 If a module is specified instead of a file, the file with name
 ``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,

Help/command/include_directories.rst

@@ -3,7 +3,7 @@ include_directories
 
 Add include directories to the build.
 
-::
+.. code-block:: cmake
 
   include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
 

Help/command/include_external_msproject.rst

@@ -3,7 +3,7 @@ include_external_msproject
 
 Include an external Microsoft project file in a workspace.
 
-::
+.. code-block:: cmake
 
   include_external_msproject(projectname location
                              [TYPE projectTypeGUID]
@@ -13,11 +13,11 @@ Include an external Microsoft project file in a workspace.
 
 Includes an external Microsoft project in the generated workspace
 file.  Currently does nothing on UNIX.  This will create a target
-named [projectname].  This can be used in the :command:`add_dependencies`
+named ``[projectname]``.  This can be used in the :command:`add_dependencies`
 command to make things depend on the external project.
 
 ``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to
-specify the type of project, id (GUID) of the project and the name of
+specify the type of project, id (``GUID``) of the project and the name of
 the target platform.  This is useful for projects requiring values
 other than the default (e.g.  WIX projects).
 

Help/command/include_guard.rst

@@ -3,7 +3,7 @@ include_guard
 
 Provides an include guard for the file currently being processed by CMake.
 
-::
+.. code-block:: cmake
 
   include_guard([DIRECTORY|GLOBAL])
 

Help/command/include_regular_expression.rst

@@ -3,11 +3,11 @@ include_regular_expression
 
 Set the regular expression used for dependency checking.
 
-::
+.. code-block:: cmake
 
   include_regular_expression(regex_match [regex_complain])
 
-Set the regular expressions used in dependency checking.  Only files
+Sets the regular expressions used in dependency checking.  Only files
 matching ``regex_match`` will be traced as dependencies.  Only files
 matching ``regex_complain`` will generate warnings if they cannot be found
 (standard header paths are not searched).  The defaults are:

Help/command/install.rst

@@ -9,11 +9,11 @@ Synopsis
 .. parsed-literal::
 
   install(`TARGETS`_ <target>... [...])
-  install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
+  install({`FILES`_ | `PROGRAMS`_} <file>... [...])
-  install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
+  install(`DIRECTORY`_ <dir>... [...])
   install(`SCRIPT`_ <file> [...])
   install(`CODE`_ <code> [...])
-  install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
+  install(`EXPORT`_ <export-name> [...])
 
 Introduction
 ^^^^^^^^^^^^
@@ -99,9 +99,10 @@ Windows platforms are unaffected.
 Installing Targets
 ^^^^^^^^^^^^^^^^^^
 
+.. _`install(TARGETS)`:
 .. _TARGETS:
 
-::
+.. code-block:: cmake
 
   install(TARGETS targets... [EXPORT <export-name>]
           [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
@@ -147,13 +148,13 @@ project.  There are several kinds of target files that may be installed:
   property are treated as ``FRAMEWORK`` targets on macOS.
 
 ``BUNDLE``
-  Executables marked with the ``MACOSX_BUNDLE`` property are treated as
+  Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as
   ``BUNDLE`` targets on macOS.
 
 ``PUBLIC_HEADER``
-  Any ``PUBLIC_HEADER`` files associated with a library are installed in
+  Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in
   the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple
-  platforms. Rules defined by this argument are ignored for ``FRAMEWORK``
+  platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK`
   libraries on Apple platforms because the associated files are installed
   into the appropriate locations inside the framework folder. See
   :prop_tgt:`PUBLIC_HEADER` for details.
@@ -172,6 +173,54 @@ installation properties apply to all target types. If only one is given then
 only targets of that type will be installed (which can be used to install
 just a DLL or just an import library.)
 
+For regular executables, static libraries and shared libraries, the
+``DESTINATION`` argument is not required.  For these target types, when
+``DESTINATION`` is omitted, a default destination will be taken from the
+appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
+default value if that variable is not defined.  The same is true for the
+public and private headers associated with the installed targets through the
+:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties.
+A destination must always be provided for module libraries, Apple bundles and
+frameworks.  A destination can be omitted for interface and object libraries,
+but they are handled differently (see the discussion of this topic toward the
+end of this section).
+
+The following table shows the target types with their associated variables and
+built-in defaults that apply when no destination is given:
+
+================== =============================== ======================
+   Target Type         GNUInstallDirs Variable        Built-In Default
+================== =============================== ======================
+``RUNTIME``        ``${CMAKE_INSTALL_BINDIR}``     ``bin``
+``LIBRARY``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``ARCHIVE``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+``PUBLIC_HEADER``  ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+================== =============================== ======================
+
+Projects wishing to follow the common practice of installing headers into a
+project-specific subdirectory will need to provide a destination rather than
+rely on the above.
+
+To make packages compliant with distribution filesystem layout policies, if
+projects must specify a ``DESTINATION``, it is recommended that they use a
+path that begins with the appropriate :module:`GNUInstallDirs` variable.
+This allows package maintainers to control the install destination by setting
+the appropriate cache variables.  The following example shows a static library
+being installed to the default destination provided by
+:module:`GNUInstallDirs`, but with its headers installed to a project-specific
+subdirectory that follows the above recommendation:
+
+.. code-block:: cmake
+
+  add_library(mylib STATIC ...)
+  set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
+  include(GNUInstallDirs)
+  install(TARGETS mylib
+          PUBLIC_HEADER
+            DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
+  )
+
 In addition to the common options listed above, each target can accept
 the following additional arguments:
 
@@ -195,11 +244,9 @@ the following additional arguments:
 
     install(TARGETS mylib
             LIBRARY
-              DESTINATION lib
               COMPONENT Libraries
               NAMELINK_COMPONENT Development
             PUBLIC_HEADER
-              DESTINATION include
               COMPONENT Development
            )
 
@@ -242,18 +289,20 @@ the following additional arguments:
   is not recommended to use ``NAMELINK_SKIP`` in conjunction with
   ``NAMELINK_COMPONENT``.
 
-The ``install(TARGETS)`` command can also accept the following options at the
+The `install(TARGETS)`_ command can also accept the following options at the
 top level:
 
 ``EXPORT``
   This option associates the installed target files with an export called
   ``<export-name>``.  It must appear before any target options.  To actually
-  install the export file itself, call ``install(EXPORT)``, documented below.
+  install the export file itself, call `install(EXPORT)`_, documented below.
+  See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
+  the name of the exported target.
 
 ``INCLUDES DESTINATION``
   This option specifies a list of directories which will be added to the
   :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
-  ``<targets>`` when exported by the :command:`install(EXPORT)` command. If a
+  ``<targets>`` when exported by the `install(EXPORT)`_ command. If a
   relative path is specified, it is treated as relative to the
   ``$<INSTALL_PREFIX>``.
 
@@ -287,7 +336,7 @@ targets that link to the object libraries in their implementation.
 Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
 set to ``TRUE`` has undefined behavior.
 
-:command:`install(TARGETS)` can install targets that were created in
+`install(TARGETS)`_ can install targets that were created in
 other directories.  When using such cross-directory install rules, running
 ``make install`` (or similar) from a subdirectory will not guarantee that
 targets from other directories are up-to-date.  You can use
@@ -295,19 +344,22 @@ targets from other directories are up-to-date.  You can use
 to ensure that such out-of-directory targets are built before the
 subdirectory-specific install rules are run.
 
-The install destination given to the target install ``DESTINATION`` may
+An install destination given as a ``DESTINATION`` argument may
 use "generator expressions" with the syntax ``$<...>``.  See the
 :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
 Installing Files
 ^^^^^^^^^^^^^^^^
 
+.. _`install(FILES)`:
+.. _`install(PROGRAMS)`:
 .. _FILES:
 .. _PROGRAMS:
 
-::
+.. code-block:: cmake
 
-  install(<FILES|PROGRAMS> files... DESTINATION <dir>
+  install(<FILES|PROGRAMS> files...
+          TYPE <type> | DESTINATION <dir>
           [PERMISSIONS permissions...]
           [CONFIGURATIONS [Debug|Release|...]]
           [COMPONENT <component>]
@@ -331,18 +383,71 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
 However, if any item begins in a generator expression it must evaluate
 to a full path.
 
-The install destination given to the files install ``DESTINATION`` may
+Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
+A ``TYPE`` argument specifies the generic file type of the files being
+installed.  A destination will then be set automatically by taking the
+corresponding variable from :module:`GNUInstallDirs`, or by using a
+built-in default if that variable is not defined.  See the table below for
+the supported file types and their corresponding variables and built-in
+defaults.  Projects can provide a ``DESTINATION`` argument instead of a
+file type if they wish to explicitly define the install destination.
+
+======================= ================================== =========================
+   ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
+======================= ================================== =========================
+``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
+``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
+``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
+``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
+``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
+``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
+``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
+``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
+``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
+``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
+``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
+``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
+``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
+======================= ================================== =========================
+
+Projects wishing to follow the common practice of installing headers into a
+project-specific subdirectory will need to provide a destination rather than
+rely on the above.
+
+Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
+a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
+``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
+default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
+``DATA`` instead.
+
+To make packages compliant with distribution filesystem layout policies, if
+projects must specify a ``DESTINATION``, it is recommended that they use a
+path that begins with the appropriate :module:`GNUInstallDirs` variable.
+This allows package maintainers to control the install destination by setting
+the appropriate cache variables.  The following example shows how to follow
+this advice while installing headers to a project-specific subdirectory:
+
+.. code-block:: cmake
+
+  include(GNUInstallDirs)
+  install(FILES mylib.h
+          DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
+  )
+
+An install destination given as a ``DESTINATION`` argument may
 use "generator expressions" with the syntax ``$<...>``.  See the
 :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
 Installing Directories
 ^^^^^^^^^^^^^^^^^^^^^^
 
+.. _`install(DIRECTORY)`:
 .. _DIRECTORY:
 
-::
+.. code-block:: cmake
 
-  install(DIRECTORY dirs... DESTINATION <dir>
+  install(DIRECTORY dirs...
+          TYPE <type> | DESTINATION <dir>
           [FILE_PERMISSIONS permissions...]
           [DIRECTORY_PERMISSIONS permissions...]
           [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
@@ -413,18 +518,60 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the
 file permissions, the scripts will be given specific permissions, and any
 ``CVS`` directories will be excluded.
 
-The list of ``dirs...`` given to ``DIRECTORY`` and the install destination
+Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
-given to the directory install ``DESTINATION`` may use "generator expressions"
+A ``TYPE`` argument specifies the generic file type of the files within the
+listed directories being installed.  A destination will then be set
+automatically by taking the corresponding variable from
+:module:`GNUInstallDirs`, or by using a built-in default if that variable
+is not defined.  See the table below for the supported file types and their
+corresponding variables and built-in defaults.  Projects can provide a
+``DESTINATION`` argument instead of a file type if they wish to explicitly
+define the install destination.
+
+======================= ================================== =========================
+   ``TYPE`` Argument         GNUInstallDirs Variable           Built-In Default
+======================= ================================== =========================
+``BIN``                 ``${CMAKE_INSTALL_BINDIR}``        ``bin``
+``SBIN``                ``${CMAKE_INSTALL_SBINDIR}``       ``sbin``
+``LIB``                 ``${CMAKE_INSTALL_LIBDIR}``        ``lib``
+``INCLUDE``             ``${CMAKE_INSTALL_INCLUDEDIR}``    ``include``
+``SYSCONF``             ``${CMAKE_INSTALL_SYSCONFDIR}``    ``etc``
+``SHAREDSTATE``         ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
+``LOCALSTATE``          ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
+``RUNSTATE``            ``${CMAKE_INSTALL_RUNSTATEDIR}``   ``<LOCALSTATE dir>/run``
+``DATA``                ``${CMAKE_INSTALL_DATADIR}``       ``<DATAROOT dir>``
+``INFO``                ``${CMAKE_INSTALL_INFODIR}``       ``<DATAROOT dir>/info``
+``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
+``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
+``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
+======================= ================================== =========================
+
+Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
+a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
+``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
+default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
+``DATA`` instead.
+
+To make packages compliant with distribution filesystem layout policies, if
+projects must specify a ``DESTINATION``, it is recommended that they use a
+path that begins with the appropriate :module:`GNUInstallDirs` variable.
+This allows package maintainers to control the install destination by setting
+the appropriate cache variables.
+
+The list of ``dirs...`` given to ``DIRECTORY`` and an install destination
+given as a ``DESTINATION`` argument may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.
 
 Custom Installation Logic
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. _`install(CODE)`:
+.. _`install(SCRIPT)`:
 .. _CODE:
 .. _SCRIPT:
 
-::
+.. code-block:: cmake
 
   install([[SCRIPT <file>] [CODE <code>]]
           [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
@@ -442,12 +589,18 @@ example, the code
 
 will print a message during installation.
 
+``<file>`` or ``<code>`` may use "generator expressions" with the syntax
+``$<...>`` (in the case of ``<file>``, this refers to their use in the file
+name, not the file's contents).  See the
+:manual:`cmake-generator-expressions(7)` manual for available expressions.
+
 Installing Exports
 ^^^^^^^^^^^^^^^^^^
 
+.. _`install(EXPORT)`:
 .. _EXPORT:
 
-::
+.. code-block:: cmake
 
   install(EXPORT <export-name> DESTINATION <dir>
           [NAMESPACE <namespace>] [[FILE <name>.cmake]|
@@ -461,7 +614,7 @@ Installing Exports
 The ``EXPORT`` form generates and installs a CMake file containing code to
 import targets from the installation tree into another project.
 Target installations are associated with the export ``<export-name>``
-using the ``EXPORT`` option of the ``install(TARGETS)`` signature
+using the ``EXPORT`` option of the `install(TARGETS)`_ signature
 documented above.  The ``NAMESPACE`` option will prepend ``<namespace>`` to
 the target names as they are written to the import file.  By default
 the generated file will be called ``<export-name>.cmake`` but the ``FILE``
@@ -507,9 +660,9 @@ and installed by the current project.  For example, the code
 
   install(TARGETS myexe EXPORT myproj DESTINATION bin)
   install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
-  install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)
+  install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
 
-will install the executable myexe to ``<prefix>/bin`` and code to import
+will install the executable ``myexe`` to ``<prefix>/bin`` and code to import
 it in the file ``<prefix>/lib/myproj/myproj.cmake`` and
 ``<prefix>/share/ndk-modules/Android.mk``.  An outside project
 may load this file with the include command and reference the ``myexe``

Help/command/install_files.rst

@@ -1,7 +1,9 @@
 install_files
 -------------
 
-Deprecated.  Use the :command:`install(FILES)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`install(FILES)` command instead.
 
 This command has been superceded by the :command:`install` command.  It is
 provided for compatibility with older CMake code.  The ``FILES`` form is
@@ -19,7 +21,7 @@ or its corresponding location in the binary tree may be listed.  If a
 file specified already has an extension, that extension will be
 removed first.  This is useful for providing lists of source files
 such as foo.cxx when you want the corresponding foo.h to be installed.
-A typical extension is '.h'.
+A typical extension is ``.h``.
 
 ::
 

Help/command/install_programs.rst

@@ -1,7 +1,9 @@
 install_programs
 ----------------
 
-Deprecated. Use the :command:`install(PROGRAMS)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`install(PROGRAMS)` command instead.
 
 This command has been superceded by the :command:`install` command.  It is
 provided for compatibility with older CMake code.  The ``FILES`` form is

Help/command/install_targets.rst

@@ -1,7 +1,9 @@
 install_targets
 ---------------
 
-Deprecated. Use the :command:`install(TARGETS)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`install(TARGETS)` command instead.
 
 This command has been superceded by the :command:`install` command.  It is
 provided for compatibility with older CMake code.

Help/command/link_directories.rst

@@ -3,11 +3,11 @@ link_directories
 
 Add directories in which the linker will look for libraries.
 
-::
+.. code-block:: cmake
 
   link_directories([AFTER|BEFORE] directory1 [directory2 ...])
 
-Add the paths in which the linker should search for libraries.
+Adds the paths in which the linker should search for libraries.
 Relative paths given to this command are interpreted as relative to
 the current source directory, see :policy:`CMP0015`.
 

Help/command/link_libraries.rst

@@ -3,7 +3,7 @@ link_libraries
 
 Link libraries to all targets added later.
 
-::
+.. code-block:: cmake
 
   link_libraries([item1 [item2 [...]]]
                  [[debug|optimized|general] <item>] ...)

Help/command/list.rst

@@ -21,6 +21,9 @@ Synopsis
     list(`APPEND`_ <list> [<element>...])
     list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
     list(`INSERT`_ <list> <index> [<element>...])
+    list(`POP_BACK`_ <list> [<out-var>...])
+    list(`POP_FRONT`_ <list> [<out-var>...])
+    list(`PREPEND`_ <list> [<element>...])
     list(`REMOVE_ITEM`_ <list> <value>...)
     list(`REMOVE_AT`_ <list> <index>...)
     list(`REMOVE_DUPLICATES`_ <list>)
@@ -33,8 +36,9 @@ Synopsis
 Introduction
 ^^^^^^^^^^^^
 
-The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``,
+The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``,
-``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
+``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``,
+``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
 new values for the list within the current CMake variable scope.  Similar to
 the :command:`set` command, the LIST command creates new variable values in
 the current scope, even if the list itself is actually defined in a parent
@@ -64,7 +68,7 @@ Reading
 
 .. _LENGTH:
 
-::
+.. code-block:: cmake
 
   list(LENGTH <list> <output variable>)
 
@@ -72,7 +76,7 @@ Returns the list's length.
 
 .. _GET:
 
-::
+.. code-block:: cmake
 
   list(GET <list> <element index> [<element index> ...] <output variable>)
 
@@ -80,7 +84,7 @@ Returns the list of elements specified by indices from the list.
 
 .. _JOIN:
 
-::
+.. code-block:: cmake
 
   list(JOIN <list> <glue> <output variable>)
 
@@ -90,7 +94,7 @@ from :command:`string` command.
 
 .. _SUBLIST:
 
-::
+.. code-block:: cmake
 
   list(SUBLIST <list> <begin> <length> <output variable>)
 
@@ -104,7 +108,7 @@ Search
 
 .. _FIND:
 
-::
+.. code-block:: cmake
 
   list(FIND <list> <value> <output variable>)
 
@@ -116,7 +120,7 @@ Modification
 
 .. _APPEND:
 
-::
+.. code-block:: cmake
 
   list(APPEND <list> [<element> ...])
 
@@ -124,7 +128,7 @@ Appends elements to the list.
 
 .. _FILTER:
 
-::
+.. code-block:: cmake
 
   list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
 
@@ -136,15 +140,43 @@ For more information on regular expressions see also the
 
 .. _INSERT:
 
-::
+.. code-block:: cmake
 
   list(INSERT <list> <element_index> <element> [<element> ...])
 
 Inserts elements to the list to the specified location.
 
+.. _POP_BACK:
+
+.. code-block:: cmake
+
+  list(POP_BACK <list> [<out-var>...])
+
+If no variable name is given, removes exactly one element. Otherwise,
+assign the last element's value to the given variable and removes it,
+up to the last variable name given.
+
+.. _POP_FRONT:
+
+.. code-block:: cmake
+
+  list(POP_FRONT <list> [<out-var>...])
+
+If no variable name is given, removes exactly one element. Otherwise,
+assign the first element's value to the given variable and removes it,
+up to the last variable name given.
+
+.. _PREPEND:
+
+.. code-block:: cmake
+
+  list(PREPEND <list> [<element> ...])
+
+Insert elements to the 0th position in the list.
+
 .. _REMOVE_ITEM:
 
-::
+.. code-block:: cmake
 
   list(REMOVE_ITEM <list> <value> [<value> ...])
 
@@ -152,7 +184,7 @@ Removes the given items from the list.
 
 .. _REMOVE_AT:
 
-::
+.. code-block:: cmake
 
   list(REMOVE_AT <list> <index> [<index> ...])
 
@@ -160,82 +192,96 @@ Removes items at given indices from the list.
 
 .. _REMOVE_DUPLICATES:
 
-::
+.. code-block:: cmake
 
   list(REMOVE_DUPLICATES <list>)
 
-Removes duplicated items in the list.
+Removes duplicated items in the list. The relative order of items is preserved,
+but if duplicates are encountered, only the first instance is preserved.
 
 .. _TRANSFORM:
 
-::
+.. code-block:: cmake
 
   list(TRANSFORM <list> <ACTION> [<SELECTOR>]
                         [OUTPUT_VARIABLE <output variable>])
 
 Transforms the list by applying an action to all or, by specifying a
-``<SELECTOR>``, to the selected elements of the list, storing result in-place
+``<SELECTOR>``, to the selected elements of the list, storing the result
-or in the specified output variable.
+in-place or in the specified output variable.
 
 .. note::
 
-   ``TRANSFORM`` sub-command does not change the number of elements of the
+   The ``TRANSFORM`` sub-command does not change the number of elements in the
    list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
-   the other ones will remain same as before the transformation.
+   the other ones will remain the same as before the transformation.
 
-``<ACTION>`` specify the action to apply to the elements of list.
+``<ACTION>`` specifies the action to apply to the elements of the list.
-The actions have exactly the same semantics as sub-commands of
+The actions have exactly the same semantics as sub-commands of the
-:command:`string` command.
+:command:`string` command.  ``<ACTION>`` must be one of the following:
-
-The ``<ACTION>`` may be one of:
 
 ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
-the list. ::
+the list.
 
-  list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
+  .. code-block:: cmake
+
+    list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
 
 ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
-characters. ::
+characters.
 
-  list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
+  .. code-block:: cmake
+
+    list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
 
 ``STRIP``: Remove leading and trailing spaces from each element of the
-list. ::
+list.
 
-  list(TRANSFORM <list> STRIP ...)
+  .. code-block:: cmake
+
+    list(TRANSFORM <list> STRIP ...)
 
 ``GENEX_STRIP``: Strip any
 :manual:`generator expressions <cmake-generator-expressions(7)>` from each
-element of the list. ::
+element of the list.
 
-  list(TRANSFORM <list> GENEX_STRIP ...)
+  .. code-block:: cmake
+
+    list(TRANSFORM <list> GENEX_STRIP ...)
 
 ``REPLACE``: Match the regular expression as many times as possible and
 substitute the replacement expression for the match for each element
 of the list
-(Same semantic as ``REGEX REPLACE`` from :command:`string` command). ::
+(Same semantic as ``REGEX REPLACE`` from :command:`string` command).
 
-  list(TRANSFORM <list> REPLACE <regular_expression>
+  .. code-block:: cmake
-                                <replace_expression> ...)
 
-``<SELECTOR>`` select which elements of the list will be transformed. Only one
+    list(TRANSFORM <list> REPLACE <regular_expression>
-type of selector can be specified at a time.
+                                  <replace_expression> ...)
 
-The ``<SELECTOR>`` may be one of:
+``<SELECTOR>`` determines which elements of the list will be transformed.
+Only one type of selector can be specified at a time.  When given,
+``<SELECTOR>`` must be one of the following:
 
-``AT``: Specify a list of indexes. ::
+``AT``: Specify a list of indexes.
 
-  list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
+  .. code-block:: cmake
+
+    list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
 
 ``FOR``: Specify a range with, optionally, an increment used to iterate over
-the range. ::
+the range.
 
-  list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
+  .. code-block:: cmake
+
+    list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
 
 ``REGEX``: Specify a regular expression. Only elements matching the regular
-expression will be transformed. ::
+expression will be transformed.
 
-  list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
+  .. code-block:: cmake
+
+    list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
 
 
 Ordering
@@ -243,7 +289,7 @@ Ordering
 
 .. _REVERSE:
 
-::
+.. code-block:: cmake
 
   list(REVERSE <list>)
 
@@ -251,7 +297,7 @@ Reverses the contents of the list in-place.
 
 .. _SORT:
 
-::
+.. code-block:: cmake
 
   list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
 

Help/command/load_cache.rst

@@ -3,21 +3,20 @@ load_cache
 
 Load in the values from another project's CMake cache.
 
-::
+.. code-block:: cmake
 
-  load_cache(pathToCacheFile READ_WITH_PREFIX
+  load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...)
-             prefix entry1...)
 
-Read the cache and store the requested entries in variables with their
+Reads the cache and store the requested entries in variables with their
 name prefixed with the given prefix.  This only reads the values, and
 does not create entries in the local project's cache.
 
-::
+.. code-block:: cmake
 
   load_cache(pathToCacheFile [EXCLUDE entry1...]
              [INCLUDE_INTERNALS entry1...])
 
-Load in the values from another cache and store them in the local
+Loads in the values from another cache and store them in the local
 project's cache as internal entries.  This is useful for a project
 that depends on another project built in a different tree.  ``EXCLUDE``
 option can be used to provide a list of entries to be excluded.

Help/command/load_command.rst

@@ -1,7 +1,7 @@
 load_command
 ------------
 
-Disallowed.  See CMake Policy :policy:`CMP0031`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0031`.
 
 Load a command into a running CMake.
 

Help/command/macro.rst

@@ -1,27 +1,66 @@
 macro
 -----
 
-Start recording a macro for later invocation as a command::
+Start recording a macro for later invocation as a command
 
-  macro(<name> [arg1 [arg2 [arg3 ...]]])
+.. code-block:: cmake
-    COMMAND1(ARGS ...)
+
-    COMMAND2(ARGS ...)
+  macro(<name> [<arg1> ...])
-    ...
+    <commands>
-  endmacro(<name>)
+  endmacro()
+
+Defines a macro named ``<name>`` that takes arguments named
+``<arg1>``, ... Commands listed after macro, but before the
+matching :command:`endmacro()`, are not executed until the macro
+is invoked.
+
+Per legacy, the :command:`endmacro` command admits an optional
+``<name>`` argument. If used, it must be a verbatim repeat of the
+argument of the opening ``macro`` command.
+
+See the :command:`cmake_policy()` command documentation for the behavior
+of policies inside macros.
+
+See the :ref:`Macro vs Function` section below for differences
+between CMake macros and :command:`functions <function>`.
+
+Invocation
+^^^^^^^^^^
+
+The macro invocation is case-insensitive. A macro defined as
+
+.. code-block:: cmake
+
+  macro(foo)
+    <commands>
+  endmacro()
+
+can be invoked through any of
+
+.. code-block:: cmake
+
+  foo()
+  Foo()
+  FOO()
+
+and so on. However, it is strongly recommended to stay with the
+case chosen in the macro definition.  Typically macros use
+all-lowercase names.
+
+Arguments
+^^^^^^^^^
+
+When a macro is invoked, the commands recorded in the macro are
+first modified by replacing formal parameters (``${arg1}``, ...)
+with the arguments passed, and then invoked as normal commands.
 
-Define a macro named ``<name>`` that takes arguments named ``arg1``,
-``arg2``, ``arg3``, (...).
-Commands listed after macro, but before the matching
-:command:`endmacro()`, are not invoked until the macro is invoked.
-When it is invoked, the commands recorded in the macro are first
-modified by replacing formal parameters (``${arg1}``) with the arguments
-passed, and then invoked as normal commands.
 In addition to referencing the formal parameters you can reference the
 values ``${ARGC}`` which will be set to the number of arguments passed
 into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
 ...  which will have the actual values of the arguments passed in.
 This facilitates creating macros with optional arguments.
-Additionally ``${ARGV}`` holds the list of all arguments given to the
+
+Furthermore, ``${ARGV}`` holds the list of all arguments given to the
 macro and ``${ARGN}`` holds the list of arguments past the last expected
 argument.
 Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
@@ -29,48 +68,73 @@ behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
 way to ensure that ``${ARGV#}`` was passed to the function as an extra
 argument.
 
-See the :command:`cmake_policy()` command documentation for the behavior
+.. _`Macro vs Function`:
-of policies inside macros.
 
-Macro Argument Caveats
+Macro vs Function
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^
 
-Note that the parameters to a macro and values such as ``ARGN`` are
+The ``macro`` command is very similar to the :command:`function` command.
-not variables in the usual CMake sense.  They are string
+Nonetheless, there are a few important differences.
-replacements much like the C preprocessor would do with a macro.
+
-Therefore you will NOT be able to use commands like::
+In a function, ``ARGN``, ``ARGC``, ``ARGV`` and ``ARGV0``, ``ARGV1``, ...
+are true variables in the usual CMake sense.  In a macro, they are not,
+they are string replacements much like the C preprocessor would do
+with a macro.  This has a number of consequences, as explained in
+the :ref:`Argument Caveats` section below.
+
+Another difference between macros and functions is the control flow.
+A function is executed by transferring control from the calling
+statement to the function body.  A macro is executed as if the macro
+body were pasted in place of the calling statement.  This has the
+consequence that a :command:`return()` in a macro body does not
+just terminate execution of the macro; rather, control is returned
+from the scope of the macro call.  To avoid confusion, it is recommended
+to avoid :command:`return()` in macros altogether.
+
+.. _`Argument Caveats`:
+
+Argument Caveats
+^^^^^^^^^^^^^^^^
+
+Since ``ARGN``, ``ARGC``, ``ARGV``, ``ARGV0`` etc. are not variables,
+you will NOT be able to use commands like
+
+.. code-block:: cmake
 
  if(ARGV1) # ARGV1 is not a variable
  if(DEFINED ARGV2) # ARGV2 is not a variable
  if(ARGC GREATER 2) # ARGC is not a variable
  foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
 
-In the first case, you can use ``if(${ARGV1})``.
+In the first case, you can use ``if(${ARGV1})``.  In the second and
-In the second and third case, the proper way to check if an optional
+third case, the proper way to check if an optional variable was
-variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
+passed to the macro is to use ``if(${ARGC} GREATER 2)``.  In the
-In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
+last case, you can use ``foreach(loop_var ${ARGN})`` but this will
-will skip empty arguments.
+skip empty arguments.  If you need to include them, you can use
-If you need to include them, you can use::
+
+.. code-block:: cmake
 
  set(list_var "${ARGN}")
  foreach(loop_var IN LISTS list_var)
 
 Note that if you have a variable with the same name in the scope from
 which the macro is called, using unreferenced names will use the
-existing variable instead of the arguments. For example::
+existing variable instead of the arguments. For example:
 
- macro(_BAR)
+.. code-block:: cmake
+
+ macro(bar)
    foreach(arg IN LISTS ARGN)
-     [...]
+     <commands>
    endforeach()
  endmacro()
 
- function(_FOO)
+ function(foo)
-   _bar(x y z)
+   bar(x y z)
  endfunction()
 
- _foo(a b c)
+ foo(a b c)
 
-Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting.
+Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected.
 If you want true CMake variables and/or better CMake scope control you
 should look at the function command.

Help/command/make_directory.rst

@@ -1,7 +1,9 @@
 make_directory
 --------------
 
-Deprecated. Use the :command:`file(MAKE_DIRECTORY)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`file(MAKE_DIRECTORY)` command instead.
 
 ::
 

Help/command/mark_as_advanced.rst

@@ -3,17 +3,22 @@ mark_as_advanced
 
 Mark cmake cached variables as advanced.
 
-::
+.. code-block:: cmake
 
-  mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...])
+  mark_as_advanced([CLEAR|FORCE] <var1> ...)
 
-Mark the named cached variables as advanced.  An advanced variable
+Sets the advanced/non-advanced state of the named
-will not be displayed in any of the cmake GUIs unless the show
+cached variables.
-advanced option is on.  If ``CLEAR`` is the first argument advanced
-variables are changed back to unadvanced.  If ``FORCE`` is the first
-argument, then the variable is made advanced.  If neither ``FORCE`` nor
-``CLEAR`` is specified, new values will be marked as advanced, but if the
-variable already has an advanced/non-advanced state, it will not be
-changed.
 
-It does nothing in script mode.
+An advanced variable will not be displayed in any
+of the cmake GUIs unless the ``show advanced`` option is on.
+In script mode, the advanced/non-advanced state has no effect.
+
+If the keyword ``CLEAR`` is given
+then advanced variables are changed back to unadvanced.
+If the keyword ``FORCE`` is given
+then the variables are made advanced.
+If neither ``FORCE`` nor ``CLEAR`` is specified,
+new values will be marked as advanced, but if a
+variable already has an advanced/non-advanced state,
+it will not be changed.

Help/command/math.rst

@@ -1,30 +1,36 @@
 math
 ----
 
-Mathematical expressions.
+Evaluate a mathematical expression.
 
-::
+.. code-block:: cmake
 
-  math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>])
+  math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
 
-``EXPR`` evaluates mathematical expression and returns result in the
+Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
-output variable.  Example mathematical expression is ``5 * (10 + 13)``.
+resulting value.
+
+The mathematical expression must be given as a string (i.e. enclosed in
+double quotation marks). An example is ``"5 * (10 + 13)"``.
 Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
-``^``, ``~``, ``<<``, ``>>``, and ``(...)``.  They have the same meaning
+``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning
-as they do in C code.
+as in C code.
 
-Numeric constants are evaluated in decimal or hexadecimal representation.
+Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code.
 
-The result is formatted according to the option "OUTPUT_FORMAT" ,
+The result is formatted according to the option ``OUTPUT_FORMAT``,
-where ``<format>`` is one of:
+where ``<format>`` is one of
-::
 
- HEXADECIMAL = Result in output variable will be formatted in C code
+``HEXADECIMAL``
- Hexadecimal notation.
+  Hexadecimal notation as in C code, i. e. starting with "0x".
- DECIMAL = Result in output variable will be formatted in decimal notation.
+``DECIMAL``
+  Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option
+  is specified.
 
 
-For example::
+For example
 
-  math(EXPR value "100 * 0xA" DECIMAL)  results in value is set to "1000"
+.. code-block:: cmake
-  math(EXPR value "100 * 0xA" HEXADECIMAL)  results in value is set to "0x3e8"
+
+  math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL)      # value is set to "1000"
+  math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL)  # value is set to "0x3e8"

Help/command/message.rst

@@ -3,30 +3,62 @@ message
 
 Display a message to the user.
 
-::
+.. code-block:: cmake
 
   message([<mode>] "message to display" ...)
 
 The optional ``<mode>`` keyword determines the type of message:
 
-::
+``FATAL_ERROR``
+  CMake Error, stop processing and generation.
 
-  (none)         = Important information
+``SEND_ERROR``
-  STATUS         = Incidental information
+  CMake Error, continue processing, but skip generation.
-  WARNING        = CMake Warning, continue processing
-  AUTHOR_WARNING = CMake Warning (dev), continue processing
-  SEND_ERROR     = CMake Error, continue processing,
-                                but skip generation
-  FATAL_ERROR    = CMake Error, stop processing and generation
-  DEPRECATION    = CMake Deprecation Error or Warning if variable
-                   CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED
-                   is enabled, respectively, else no message.
 
-The CMake command-line tool displays STATUS messages on stdout and all
+``WARNING``
-other message types on stderr.  The CMake GUI displays all messages in
+  CMake Warning, continue processing.
-its log area.  The interactive dialogs (ccmake and CMakeSetup) show
+
-STATUS messages one at a time on a status line and other messages in
+``AUTHOR_WARNING``
-interactive pop-up boxes.
+  CMake Warning (dev), continue processing.
+
+``DEPRECATION``
+  CMake Deprecation Error or Warning if variable
+  :variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED`
+  is enabled, respectively, else no message.
+
+(none) or ``NOTICE``
+  Important message printed to stderr to attract user's attention.
+
+``STATUS``
+  The main interesting messages that project users might be interested in.
+  Ideally these should be concise, no more than a single line, but still
+  informative.
+
+``VERBOSE``
+  Detailed informational messages intended for project users.  These messages
+  should provide additional details that won't be of interest in most cases,
+  but which may be useful to those building the project when they want deeper
+  insight into what's happening.
+
+``DEBUG``
+  Detailed informational messages intended for developers working on the
+  project itself as opposed to users who just want to build it.  These messages
+  will not typically be of interest to other users building the project and
+  will often be closely related to internal implementation details.
+
+``TRACE``
+  Fine-grained messages with very low-level implementation details.  Messages
+  using this log level would normally only be temporary and would expect to be
+  removed before releasing the project, packaging up the files, etc.
+
+The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout
+with the message preceded by two hyphens and a space.  All other message types
+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
+these tools can be used to control which messages will be shown.
 
 CMake Warning and Error message text displays using a simple markup
 language.  Non-indented text is formatted in line-wrapped paragraphs

Help/command/option.rst

@@ -1,17 +1,16 @@
 option
 ------
 
-Provides an option that the user can optionally select.
+Provide an option that the user can optionally select.
 
-::
+.. code-block:: cmake
 
-  option(<option_variable> "help string describing option"
+  option(<variable> "<help_text>" [value])
-         [initial value])
 
-Provide an option for the user to select as ``ON`` or ``OFF``.  If no
+Provides an option for the user to select as ``ON`` or ``OFF``.
-initial value is provided, ``OFF`` is used.  If the option is already
+If no initial ``<value>`` is provided, ``OFF`` is used.
-set as a normal variable then the command does nothing
+If ``<variable>`` is already set as a normal variable
-(see policy :policy:`CMP0077`).
+then the command does nothing (see policy :policy:`CMP0077`).
 
 If you have options that depend on the values of other options, see
 the module help for :module:`CMakeDependentOption`.

Help/command/output_required_files.rst

@@ -1,7 +1,7 @@
 output_required_files
 ---------------------
 
-Disallowed.  See CMake Policy :policy:`CMP0032`.
+Disallowed since version 3.0.  See CMake Policy :policy:`CMP0032`.
 
 Approximate C preprocessor dependency scanning.
 
@@ -14,6 +14,6 @@ more advanced scanner.
   output_required_files(srcfile outputfile)
 
 Outputs a list of all the source files that are required by the
-specified srcfile.  This list is written into outputfile.  This is
+specified ``srcfile``.  This list is written into ``outputfile``.  This is
-similar to writing out the dependencies for srcfile except that it
+similar to writing out the dependencies for ``srcfile`` except that it
-jumps from .h files into .cxx, .c and .cpp files if possible.
+jumps from ``.h`` files into ``.cxx``, ``.c`` and ``.cpp`` files if possible.

Help/command/project.rst

@@ -1,90 +1,129 @@
 project
 -------
 
-Sets project details such as name, version, etc. and enables languages.
+Set the name of the project.
+
+Synopsis
+^^^^^^^^
 
 .. code-block:: cmake
 
- project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
+ project(<PROJECT-NAME> [<language-name>...])
  project(<PROJECT-NAME>
          [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
          [DESCRIPTION <project-description-string>]
          [HOMEPAGE_URL <url-string>]
          [LANGUAGES <language-name>...])
 
-Sets the name of the project and stores the name in the
+Sets the name of the project, and stores it in the variable
-:variable:`PROJECT_NAME` variable.  Additionally this sets variables
+:variable:`PROJECT_NAME`. When called from the top-level
+``CMakeLists.txt`` also stores the project name in the
+variable :variable:`CMAKE_PROJECT_NAME`.
+
+Also sets the variables
 
 * :variable:`PROJECT_SOURCE_DIR`,
   :variable:`<PROJECT-NAME>_SOURCE_DIR`
 * :variable:`PROJECT_BINARY_DIR`,
   :variable:`<PROJECT-NAME>_BINARY_DIR`
 
-If ``VERSION`` is specified, given components must be non-negative integers.
+Further variables are set by the optional arguments described in the following.
-If ``VERSION`` is not specified, the default version is the empty string.
+If any of these arguments is not used, then the corresponding variables are
-The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is
+set to the empty string.
-set to ``NEW``.
 
-The :command:`project()` command stores the version number and its components
+Options
-in variables
+^^^^^^^
 
-* :variable:`PROJECT_VERSION`,
+The options are:
-  :variable:`<PROJECT-NAME>_VERSION`
-* :variable:`PROJECT_VERSION_MAJOR`,
-  :variable:`<PROJECT-NAME>_VERSION_MAJOR`
-* :variable:`PROJECT_VERSION_MINOR`,
-  :variable:`<PROJECT-NAME>_VERSION_MINOR`
-* :variable:`PROJECT_VERSION_PATCH`,
-  :variable:`<PROJECT-NAME>_VERSION_PATCH`
-* :variable:`PROJECT_VERSION_TWEAK`,
-  :variable:`<PROJECT-NAME>_VERSION_TWEAK`
 
-Variables corresponding to unspecified versions are set to the empty string
+``VERSION <version>``
-(if policy :policy:`CMP0048` is set to ``NEW``).
+  Optional; may not be used unless policy :policy:`CMP0048` is
+  set to ``NEW``.
 
-If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION`
+  Takes a ``<version>`` argument composed of non-negative integer components,
-and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument.
+  i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``,
-These variables will be cleared if ``DESCRIPTION`` is not given.
+  and sets the variables
-The description is expected to be a relatively short string, usually no more
-than a few words.
 
-The optional ``HOMEPAGE_URL`` sets the analogous variables
+  * :variable:`PROJECT_VERSION`,
-:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`.
+    :variable:`<PROJECT-NAME>_VERSION`
-When this option is given, the URL provided should be the canonical home for
+  * :variable:`PROJECT_VERSION_MAJOR`,
-the project.
+    :variable:`<PROJECT-NAME>_VERSION_MAJOR`
-These variables will be cleared if ``HOMEPAGE_URL`` is not given.
+  * :variable:`PROJECT_VERSION_MINOR`,
+    :variable:`<PROJECT-NAME>_VERSION_MINOR`
+  * :variable:`PROJECT_VERSION_PATCH`,
+    :variable:`<PROJECT-NAME>_VERSION_PATCH`
+  * :variable:`PROJECT_VERSION_TWEAK`,
+    :variable:`<PROJECT-NAME>_VERSION_TWEAK`.
 
-Note that the description and homepage URL may be used as defaults for
+  When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
-things like packaging meta-data, documentation, etc.
+  then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`.
 
-Optionally you can specify which languages your project supports.
+``DESCRIPTION <project-description-string>``
-Example languages include ``C``, ``CXX`` (i.e.  C++), ``CUDA``,
+  Optional.
-``Fortran``, and ``ASM``.
+  Sets the variables
-By default ``C`` and ``CXX`` are enabled if no language options are
-given.  Specify language ``NONE``, or use the ``LANGUAGES`` keyword
-and list no languages, to skip enabling any languages.
 
-If enabling ``ASM``, list it last so that CMake can check whether
+  * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION`
-compilers for other languages like ``C`` work for assembly too.
 
-If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`,
+  to ``<project-description-string>``.
-the file pointed to by that variable will be included as the last step of the
+  It is recommended that this description is a relatively short string,
-project command.
+  usually no more than a few words.
+
+  When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
+  then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`.
+
+``HOMEPAGE_URL <url-string>``
+  Optional.
+  Sets the variables
+
+  * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`
+
+  to ``<url-string>``, which should be the canonical home URL for the project.
+
+  When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
+  then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.
+
+``LANGUAGES <language-name>...``
+  Optional.
+  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``.
+  By default ``C`` and ``CXX`` are enabled if no language options are given.
+  Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
+  to skip enabling any languages.
+
+  If enabling ``ASM``, list it last so that CMake can check whether
+  compilers for other languages like ``C`` work for assembly too.
+
+The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
+options are intended for use as default values in package metadata and documentation.
+
+Code Injection
+^^^^^^^^^^^^^^
+
+If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file
+pointed to by that variable will be included as the first step of the
+``project()`` command.
+
+If the :variable:`CMAKE_PROJECT_INCLUDE` or
+:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files
+they point to will be included as the last step of the ``project()`` command.
+If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before
+:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`.
+
+Usage
+^^^^^
 
 The top-level ``CMakeLists.txt`` file for a project must contain a
-literal, direct call to the :command:`project` command; loading one
+literal, direct call to the ``project()`` command; loading one
 through the :command:`include` command is not sufficient.  If no such
-call exists CMake will implicitly add one to the top that enables the
+call exists, CMake will issue a warning and pretend there is a
-default languages (``C`` and ``CXX``).  The name of the project set in
+``project(Project)`` at the top to enable the default languages
-the top level ``CMakeLists.txt`` file is available from the
+(``C`` and ``CXX``).
-:variable:`CMAKE_PROJECT_NAME` variable, its description from
-:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from
-:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from
-:variable:`CMAKE_PROJECT_VERSION`.
 
 .. note::
-  Call the :command:`cmake_minimum_required` command at the beginning
+  Call the ``project()`` command near the top of the top-level
-  of the top-level ``CMakeLists.txt`` file even before calling the
+  ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`.
-  ``project()`` command.  It is important to establish version and
+  It is important to establish version and policy settings before invoking
-  policy settings before invoking other commands whose behavior they
+  other commands whose behavior they may affect.
-  may affect.  See also policy :policy:`CMP0000`.
+  See also policy :policy:`CMP0000`.

Help/command/qt_wrap_cpp.rst

@@ -1,12 +1,23 @@
 qt_wrap_cpp
 -----------
 
-Create Qt Wrappers.
+.. deprecated:: 3.14
 
-::
+  This command was originally added to support Qt 3 before the
+  :command:`add_custom_command()` command was sufficiently mature.  The
+  :module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which
+  should be used instead for Qt 4 projects.  For projects using Qt 5 or
+  later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
+  ``qt5_wrap_cpp()``).
 
-  qt_wrap_cpp(resultingLibraryName DestName
+Manually create Qt Wrappers.
-              SourceLists ...)
 
-Produce moc files for all the .h files listed in the SourceLists.  The
+.. code-block:: cmake
+
+  qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
+
+Produces moc files for all the .h files listed in the SourceLists.  The
 moc files will be added to the library using the ``DestName`` source list.
+
+Consider updating the project to use the :prop_tgt:`AUTOMOC` target property
+instead for a more automated way of invoking the ``moc`` tool.

Help/command/qt_wrap_ui.rst

@@ -1,14 +1,26 @@
 qt_wrap_ui
 ----------
 
-Create Qt user interfaces Wrappers.
+.. deprecated:: 3.14
 
-::
+  This command was originally added to support Qt 3 before the
+  :command:`add_custom_command()` command was sufficiently mature.  The
+  :module:`FindQt4` module provides the ``qt4_wrap_ui()`` macro, which
+  should be used instead for Qt 4 projects.  For projects using Qt 5 or
+  later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
+  ``qt5_wrap_ui()``).
+
+Manually create Qt user interfaces Wrappers.
+
+.. code-block:: cmake
 
   qt_wrap_ui(resultingLibraryName HeadersDestName
              SourcesDestName SourceLists ...)
 
-Produce .h and .cxx files for all the .ui files listed in the
+Produces .h and .cxx files for all the .ui files listed in the
 ``SourceLists``.  The .h files will be added to the library using the
 ``HeadersDestNamesource`` list.  The .cxx files will be added to the
 library using the ``SourcesDestNamesource`` list.
+
+Consider updating the project to use the :prop_tgt:`AUTOUIC` target property
+instead for a more automated way of invoking the ``uic`` tool.

Help/command/remove.rst

@@ -1,7 +1,9 @@
 remove
 ------
 
-Deprecated. Use the :command:`list(REMOVE_ITEM)` command instead.
+.. deprecated:: 3.0
+
+  Use the :command:`list(REMOVE_ITEM)` command instead.
 
 ::
 

Help/command/remove_definitions.rst

@@ -1,9 +1,9 @@
 remove_definitions
 ------------------
 
-Removes -D define flags added by :command:`add_definitions`.
+Remove -D define flags added by :command:`add_definitions`.
 
-::
+.. code-block:: cmake
 
   remove_definitions(-DFOO -DBAR ...)
 

Help/command/return.rst

@@ -3,7 +3,7 @@ return
 
 Return from a file, directory or function.
 
-::
+.. code-block:: cmake
 
   return()
 
@@ -14,5 +14,6 @@ and control is returned to the including file.  If it is encountered in a
 file which is not included by another file, e.g.  a ``CMakeLists.txt``,
 control is returned to the parent directory if there is one.  If return is
 called in a function, control is returned to the caller of the function.
-Note that a macro is not a function and does not handle return like a
+
-function does.
+Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
+is expanded in place and therefore cannot handle ``return()``.

Help/command/separate_arguments.rst

@@ -1,33 +1,43 @@
 separate_arguments
 ------------------
 
-Parse space-separated arguments into a semicolon-separated list.
+Parse command-line arguments into a semicolon-separated list.
 
-::
+.. code-block:: cmake
 
-  separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>")
+  separate_arguments(<variable> <mode> <args>)
 
-Parses a UNIX- or Windows-style command-line string "<args>" and
+Parses a space-separated string ``<args>`` into a list of items,
-stores a semicolon-separated list of the arguments in ``<var>``.  The
+and stores this list in semicolon-separated standard form in ``<variable>``.
-entire command line must be given in one "<args>" argument.
 
-The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace.  It
+This function is intended for parsing command-line arguments.
-recognizes both single-quote and double-quote pairs.  A backslash
+The entire command line must be passed as one string in the
-escapes the next literal character (``\"`` is ``"``); there are no special
+argument ``<args>``.
-escapes (``\n`` is just ``n``).
 
-The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same
+The exact parsing rules depend on the operating system.
-syntax the runtime library uses to construct argv at startup.  It
+They are specified by the ``<mode>`` argument which must
-separates arguments by whitespace that is not double-quoted.
+be one of the following keywords:
-Backslashes are literal unless they precede double-quotes.  See the
-MSDN article `Parsing C Command-Line Arguments`_ for details.
 
-The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host
+``UNIX_COMMAND``
-system is Windows, and a UNIX command-line otherwise.
+  Arguments are separated by by unquoted whitespace.
+  Both single-quote and double-quote pairs are respected.
+  A backslash escapes the next literal character (``\"`` is ``"``);
+  there are no special escapes (``\n`` is just ``n``).
+
+``WINDOWS_COMMAND``
+  A Windows command-line is parsed using the same
+  syntax the runtime library uses to construct argv at startup.  It
+  separates arguments by whitespace that is not double-quoted.
+  Backslashes are literal unless they precede double-quotes.  See the
+  MSDN article `Parsing C Command-Line Arguments`_ for details.
+
+``NATIVE_COMMAND``
+  Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows.
+  Otherwise proceeds as in ``UNIX_COMMAND`` mode.
 
 .. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx
 
-::
+.. code-block:: cmake
 
   separate_arguments(<var>)
 

Help/command/set.rst

@@ -8,18 +8,18 @@ and cache entries.
 
 Signatures of this command that specify a ``<value>...`` placeholder
 expect zero or more arguments.  Multiple arguments will be joined as
-a :ref:`;-list <CMake Language Lists>` to form the actual variable
+a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable
 value to be set.  Zero arguments will cause normal variables to be
 unset.  See the :command:`unset` command to unset variables explicitly.
 
 Set Normal Variable
 ^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   set(<variable> <value>... [PARENT_SCOPE])
 
-Set the given ``<variable>`` in the current function or directory scope.
+Sets the given ``<variable>`` in the current function or directory scope.
 
 If the ``PARENT_SCOPE`` option is given the variable will be set in
 the scope above the current scope.  Each new directory or function
@@ -32,11 +32,11 @@ undefined and if it had a value, it is still that value).
 Set Cache Entry
 ^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   set(<variable> <value>... CACHE <type> <docstring> [FORCE])
 
-Set the given cache ``<variable>`` (cache entry).  Since cache entries
+Sets the given cache ``<variable>`` (cache entry).  Since cache entries
 are meant to provide user-settable values this does not overwrite
 existing cache entries by default.  Use the ``FORCE`` option to
 overwrite existing entries.
@@ -84,8 +84,21 @@ current working directory and convert it to an absolute path.
 Set Environment Variable
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
-  set(ENV{<variable>} <value>...)
+  set(ENV{<variable>} [<value>])
 
-Set the current process environment ``<variable>`` to the given value.
+Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
+to the given value.
+Subsequent calls of ``$ENV{<variable>}`` will return this new value.
+
+This command affects only the current CMake process, not the process
+from which CMake was called, nor the system environment at large,
+nor the environment of subsequent build or test processes.
+
+If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
+an empty string, then this command will clear any existing value of the
+environment variable.
+
+Arguments after ``<value>`` are ignored. If extra arguments are found,
+then an author warning is issued.

Help/command/set_directory_properties.rst

@@ -1,11 +1,15 @@
 set_directory_properties
 ------------------------
 
-Set properties of the current directory and subdirectories in key-value pairs.
+Set properties of the current directory and subdirectories.
 
-::
+.. code-block:: cmake
 
-  set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
+  set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
+
+Sets properties of the current directory and its subdirectories in key-value pairs.
+
+See also the :command:`set_property(DIRECTORY)` command.
 
 See :ref:`Directory Properties` for the list of properties known to CMake
 and their individual documentation for the behavior of each property.

Help/command/set_property.rst

@@ -3,37 +3,40 @@ set_property
 
 Set a named property in a given scope.
 
-::
+.. code-block:: cmake
 
-  set_property(<GLOBAL                            |
+  set_property(<GLOBAL                      |
-                DIRECTORY [dir]                   |
+                DIRECTORY [<dir>]           |
-                TARGET    [target1 [target2 ...]] |
+                TARGET    [<target1> ...]   |
-                SOURCE    [src1 [src2 ...]]       |
+                SOURCE    [<src1> ...]      |
-                INSTALL   [file1 [file2 ...]]     |
+                INSTALL   [<file1> ...]     |
-                TEST      [test1 [test2 ...]]     |
+                TEST      [<test1> ...]     |
-                CACHE     [entry1 [entry2 ...]]>
+                CACHE     [<entry1> ...]    >
                [APPEND] [APPEND_STRING]
-               PROPERTY <name> [value1 [value2 ...]])
+               PROPERTY <name> [value1 ...])
 
-Set one property on zero or more objects of a scope.  The first
+Sets one property on zero or more objects of a scope.
-argument determines the scope in which the property is set.  It must
+
-be one of the following:
+The first argument determines the scope in which the property is set.
+It must be one of the following:
 
 ``GLOBAL``
   Scope is unique and does not accept a name.
 
 ``DIRECTORY``
-  Scope defaults to the current directory but another
+  Scope defaults to the current directory but another directory
-  directory (already processed by CMake) may be named by full or
+  (already processed by CMake) may be named by full or relative path.
-  relative path.
+  See also the :command:`set_directory_properties` command.
 
 ``TARGET``
   Scope may name zero or more existing targets.
+  See also the :command:`set_target_properties` command.
 
 ``SOURCE``
   Scope may name zero or more source files.  Note that source
   file properties are visible only to targets added in the same
-  directory (CMakeLists.txt).
+  directory (``CMakeLists.txt``).
+  See also the :command:`set_source_files_properties` command.
 
 ``INSTALL``
   Scope may name zero or more installed file paths.
@@ -45,7 +48,7 @@ be one of the following:
   Path components have to be separated by forward slashes,
   must be normalized and are case sensitive.
 
-  To reference the installation prefix itself with a relative path use ".".
+  To reference the installation prefix itself with a relative path use ``.``.
 
   Currently installed file properties are only defined for
   the WIX generator where the given paths are relative
@@ -53,6 +56,7 @@ be one of the following:
 
 ``TEST``
   Scope may name zero or more existing tests.
+  See also the :command:`set_tests_properties` command.
 
 ``CACHE``
   Scope must name zero or more cache existing entries.

Help/command/set_source_files_properties.rst

@@ -3,13 +3,17 @@ set_source_files_properties
 
 Source files can have properties that affect how they are built.
 
-::
+.. code-block:: cmake
 
   set_source_files_properties([file1 [file2 [...]]]
                               PROPERTIES prop1 value1
                               [prop2 value2 [...]])
 
-Set properties associated with source files using a key/value paired
+Sets properties associated with source files using a key/value paired
-list.  See :ref:`Source File Properties` for the list of properties known
+list.
+
+See also the :command:`set_property(SOURCE)` command.
+
+See :ref:`Source File Properties` for the list of properties known
 to CMake.  Source file properties are visible only to targets added
-in the same directory (CMakeLists.txt).
+in the same directory (``CMakeLists.txt``).

Help/command/set_target_properties.rst

@@ -3,13 +3,13 @@ set_target_properties
 
 Targets can have properties that affect how they are built.
 
-::
+.. code-block:: cmake
 
   set_target_properties(target1 target2 ...
                         PROPERTIES prop1 value1
                         prop2 value2 ...)
 
-Set properties on targets.  The syntax for the command is to list all
+Sets properties on targets.  The syntax for the command is to list all
 the targets you want to change, and then provide the values you want to
 set next.  You can use any prop value pair you want and extract it
 later with the :command:`get_property` or :command:`get_target_property`

Help/command/set_tests_properties.rst

@@ -3,12 +3,15 @@ set_tests_properties
 
 Set a property of the tests.
 
-::
+.. code-block:: cmake
 
   set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
 
-Set a property for the tests.  If the test is not found, CMake
+Sets a property for the tests.  If the test is not found, CMake
 will report an error.
 :manual:`Generator expressions <cmake-generator-expressions(7)>` will be
-expanded the same as supported by the test's :command:`add_test` call.  See
+expanded the same as supported by the test's :command:`add_test` call.
-:ref:`Test Properties` for the list of properties known to CMake.
+
+See also the :command:`set_property(TEST)` command.
+
+See :ref:`Test Properties` for the list of properties known to CMake.