Merge remote-tracking branch 'cmake/release'

.gitignore

@@ -0,0 +1,7 @@
+# Exclude MacOS Finder files.
+.DS_Store
+
+*.user*
+
+*.pyc
+Testing

.hooks-config.bash

@@ -1,14 +1,5 @@
-#=============================================================================
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-# CMake - Cross Platform Makefile Generator
+# file Copyright.txt or https://cmake.org/licensing for details.
-# Copyright 2000-2011 Kitware, Inc., Insight Software Consortium
-#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
-#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
 
 # Loaded by .git/hooks/(pre-commit|commit-msg|prepare-commit-msg)
 # during git commit after local hooks have been installed.

Auxiliary/CMakeLists.txt

@@ -1,4 +1,4 @@
-install(FILES cmake-help.vim cmake-indent.vim cmake-syntax.vim DESTINATION ${CMAKE_DATA_DIR}/editors/vim)
+install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMAKE_DATA_DIR}/editors/vim)
 install(FILES cmake-mode.el DESTINATION ${CMAKE_DATA_DIR}/editors/emacs)
 install(FILES cmake.m4 DESTINATION share/aclocal)
 add_subdirectory (bash-completion)

Auxiliary/bash-completion/cmake

@@ -102,7 +102,7 @@ _cmake()
             ;;
         -E)
             COMPREPLY=( $( compgen -W "$( cmake -E help |& sed -n \
-                '/^  /{s|^  \([^ ]\{1,\}\) .*$|\1|;p}' 2>/dev/null )" \
+                '/^  [^ ]/{s|^  \([^ ]\{1,\}\) .*$|\1|;p}' 2>/dev/null )" \
                 -- "$cur" ) )
             return
             ;;

Auxiliary/cmake-help.vim

@@ -1,21 +0,0 @@
-nmap ,hc :call OpenCmakeHelp()<CR>
-
-function! OpenCmakeHelp()
-    let s = getline( '.' )
-    let i = col( '.' ) - 1
-    while i > 0 && strpart( s, i, 1 ) =~ '[A-Za-z0-9_]'
-        let i = i - 1
-    endwhile
-    while i < col('$') && strpart( s, i, 1 ) !~ '[A-Za-z0-9_]'
-        let i = i + 1
-    endwhile
-    let start = match( s, '[A-Za-z0-9_]\+', i )
-    let end = matchend( s, '[A-Za-z0-9_]\+', i )
-    let ident = strpart( s, start, end - start )
-    execute "vertical new"
-    execute "%!cmake --help-command ".ident
-    set nomodified
-    set readonly
-endfunction
-
-autocmd BufRead,BufNewFile *.cmake,CMakeLists.txt,*.cmake.in nmap <F1> :call OpenCmakeHelp()<CR>

Auxiliary/cmake-mode.el

@@ -1,16 +1,7 @@
 ;;; cmake-mode.el --- major-mode for editing CMake sources
 
-;=============================================================================
+; Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-; CMake - Cross Platform Makefile Generator
+; file Copyright.txt or https://cmake.org/licensing for details.
-; Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
-;
-; Distributed under the OSI-approved BSD License (the "License");
-; see accompanying file Copyright.txt for details.
-;
-; This software is distributed WITHOUT ANY WARRANTY; without even the
-; implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-; See the License for more information.
-;=============================================================================
 
 ;------------------------------------------------------------------------------
 
@@ -113,6 +104,14 @@ set the path with these commands:
 
 ;------------------------------------------------------------------------------
 
+;;
+;; Indentation increment.
+;;
+(defcustom cmake-tab-width 2
+  "Number of columns to indent cmake blocks"
+  :type 'integer
+  :group 'cmake)
+
 ;;
 ;; Line indentation function.
 ;;
@@ -225,13 +224,6 @@ the indentation.  Otherwise it retains the same position on the line"
 ;;
 (defvar cmake-mode-hook nil)
 
-;;
-;; Indentation increment.
-;;
-(defcustom cmake-tab-width 2
-  "Number of columns to indent cmake blocks"
-  :type 'integer)
-
 ;------------------------------------------------------------------------------
 
 ;; For compatibility with Emacs < 24
@@ -270,7 +262,7 @@ optional argument topic will be appended to the argument list."
     (save-selected-window
       (select-window (display-buffer buffer 'not-this-window))
       (cmake-mode)
-      (toggle-read-only t))
+      (read-only-mode 1))
     )
   )
 

Auxiliary/cmake-syntax.vim

@@ -1,89 +0,0 @@
-" =============================================================================
-"
-"   Program:   CMake - Cross-Platform Makefile Generator
-"   Module:    $RCSfile$
-"   Language:  VIM
-"   Date:      $Date$
-"   Version:   $Revision$
-"
-" =============================================================================
-
-" Vim syntax file
-" Language:     CMake
-" Author:       Andy Cedilnik <andy.cedilnik@kitware.com>
-" Maintainer:   Karthik Krishnan <karthik.krishnan@kitware.com>
-" Last Change:  $Date$
-" Version:      $Revision$
-"
-" Licence:      The CMake license applies to this file. See
-"               https://cmake.org/licensing
-"               This implies that distribution with Vim is allowed
-
-" For version 5.x: Clear all syntax items
-" For version 6.x: Quit when a syntax file was already loaded
-if version < 600
-  syntax clear
-elseif exists("b:current_syntax")
-  finish
-endif
-
-syn case ignore
-syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained
-syn region cmakeComment start="#" end="$" contains=cmakeTodo
-syn region cmakeRegistry start=/\[/ end=/]/
-            \ contained oneline contains=CONTAINED,cmakeTodo,cmakeEscaped
-syn region cmakeVariableValue start=/\${/ end=/}/
-            \ contained oneline contains=CONTAINED,cmakeTodo
-syn region cmakeEnvironment start=/\$ENV{/ end=/}/
-            \ contained oneline contains=CONTAINED,cmakeTodo
-syn region cmakeString start=/"/ end=/"/
-            \ contains=CONTAINED,cmakeTodo,cmakeOperators
-syn region cmakeArguments start=/(/ end=/)/
-            \ contains=ALLBUT,cmakeArguments,cmakeTodo
-syn keyword cmakeSystemVariables
-            \ WIN32 UNIX APPLE CYGWIN BORLAND MINGW MSVC MSVC_IDE MSVC60 MSVC70 MSVC71 MSVC80 MSVC90
-syn keyword cmakeOperators
-            \ ABSOLUTE AND BOOL CACHE COMMAND DEFINED DOC EQUAL EXISTS EXT FALSE GREATER INTERNAL LESS MATCHES NAME NAMES NAME_WE NOT OFF ON OR PATH PATHS PROGRAM STREQUAL STRGREATER STRING STRLESS TRUE
-            \ contained
-syn keyword cmakeDeprecated ABSTRACT_FILES BUILD_NAME SOURCE_FILES SOURCE_FILES_REMOVE VTK_MAKE_INSTANTIATOR VTK_WRAP_JAVA VTK_WRAP_PYTHON VTK_WRAP_TCL WRAP_EXCLUDE_FILES
-           \ nextgroup=cmakeArguments
-
-" The keywords are generated as:  cmake --help-command-list | tr "\n" " " | tr "[:lower:]" "[:upper:]"
-syn keyword cmakeStatement
-            \ ADD_COMPILE_OPTIONS ADD_CUSTOM_COMMAND ADD_CUSTOM_TARGET ADD_DEFINITIONS ADD_DEPENDENCIES ADD_EXECUTABLE ADD_LIBRARY ADD_SUBDIRECTORY ADD_TEST AUX_SOURCE_DIRECTORY BREAK BUILD_COMMAND BUILD_NAME CMAKE_HOST_SYSTEM_INFORMATION CMAKE_MINIMUM_REQUIRED CMAKE_POLICY CONFIGURE_FILE CREATE_TEST_SOURCELIST CTEST_BUILD CTEST_CONFIGURE CTEST_COVERAGE CTEST_EMPTY_BINARY_DIRECTORY CTEST_MEMCHECK CTEST_READ_CUSTOM_FILES CTEST_RUN_SCRIPT CTEST_SLEEP CTEST_START CTEST_SUBMIT CTEST_TEST CTEST_UPDATE CTEST_UPLOAD DEFINE_PROPERTY ELSE ELSEIF ENABLE_LANGUAGE ENABLE_TESTING ENDFOREACH ENDFUNCTION ENDIF ENDMACRO ENDWHILE EXEC_PROGRAM EXECUTE_PROCESS EXPORT EXPORT_LIBRARY_DEPENDENCIES FILE FIND_FILE FIND_LIBRARY FIND_PACKAGE FIND_PATH FIND_PROGRAM FLTK_WRAP_UI FOREACH FUNCTION GET_CMAKE_PROPERTY GET_DIRECTORY_PROPERTY GET_FILENAME_COMPONENT GET_PROPERTY GET_SOURCE_FILE_PROPERTY GET_TARGET_PROPERTY GET_TEST_PROPERTY IF INCLUDE INCLUDE_DIRECTORIES INCLUDE_EXTERNAL_MSPROJECT INCLUDE_REGULAR_EXPRESSION INSTALL INSTALL_FILES INSTALL_PROGRAMS INSTALL_TARGETS LINK_DIRECTORIES LINK_LIBRARIES LIST LOAD_CACHE LOAD_COMMAND MACRO MAKE_DIRECTORY MARK_AS_ADVANCED MATH MESSAGE OPTION OUTPUT_REQUIRED_FILES PROJECT QT_WRAP_CPP QT_WRAP_UI REMOVE REMOVE_DEFINITIONS RETURN SEPARATE_ARGUMENTS SET SET_DIRECTORY_PROPERTIES SET_PROPERTY SET_SOURCE_FILES_PROPERTIES SET_TARGET_PROPERTIES SET_TESTS_PROPERTIES SITE_NAME SOURCE_GROUP STRING SUBDIR_DEPENDS SUBDIRS TARGET_COMPILE_DEFINITIONS TARGET_COMPILE_FEATURES TARGET_COMPILE_OPTIONS TARGET_INCLUDE_DIRECTORIES TARGET_LINK_LIBRARIES TARGET_SOURCES TRY_COMPILE TRY_RUN UNSET USE_MANGLED_MESA UTILITY_SOURCE VARIABLE_REQUIRES VARIABLE_WATCH WHILE WRITE_FILE
-            \ nextgroup=cmakeArguments
-syn keyword cmakeTodo
-            \ TODO FIXME XXX
-            \ contained
-
-" Define the default highlighting.
-" For version 5.7 and earlier: only when not done already
-" For version 5.8 and later: only when an item doesn't have highlighting yet
-if version >= 508 || !exists("did_cmake_syntax_inits")
-  if version < 508
-    let did_cmake_syntax_inits = 1
-    command -nargs=+ HiLink hi link <args>
-  else
-    command -nargs=+ HiLink hi def link <args>
-  endif
-
-  HiLink cmakeStatement Statement
-  HiLink cmakeComment Comment
-  HiLink cmakeString String
-  HiLink cmakeVariableValue Type
-  HiLink cmakeRegistry Underlined
-  HiLink cmakeArguments Identifier
-  HiLink cmakeArgument Constant
-  HiLink cmakeEnvironment Special
-  HiLink cmakeOperators Operator
-  HiLink cmakeMacro PreProc
-  HiLink cmakeError Error
-  HiLink cmakeTodo TODO
-  HiLink cmakeEscaped Special
-
-  delcommand HiLink
-endif
-
-let b:current_syntax = "cmake"
-
-"EOF"

Auxiliary/cmake.m4

@@ -1,14 +1,5 @@
-dnl ============================================================================
+dnl Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-dnl   CMake - Cross Platform Makefile Generator
+dnl file Copyright.txt or https://cmake.org/licensing for details.
-dnl   Copyright 2011 Matthias Kretz, kretz@kde.org
-dnl
-dnl   Distributed under the OSI-approved BSD License (the "License");
-dnl   see accompanying file Copyright.txt for details.
-dnl
-dnl   This software is distributed WITHOUT ANY WARRANTY; without even the
-dnl   implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-dnl   See the License for more information.
-dnl ============================================================================
 
 AC_DEFUN([CMAKE_FIND_BINARY],
 [AC_ARG_VAR([CMAKE_BINARY], [path to the cmake binary])dnl

Auxiliary/vim/extract-upper-case.pl

@@ -0,0 +1,141 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+
+my @variables;
+my @commands;
+my @properties;
+my @modules;
+my %keywords; # command => keyword-list
+
+# unwanted upper-cases
+my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR);
+	# cannot remove ALL - exists for add_custom_command
+
+# control-statements
+my %conditional = map { $_ => 1 } qw(if else elseif endif);
+my %loop = map { $_ => 1 } qw(foreach while endforeach endwhile);
+
+# decrecated
+my %deprecated = map { $_ => 1 } qw(build_name exec_program export_library_dependencies install_files install_programs install_targets link_libraries make_directory output_required_files remove subdir_depends subdirs use_mangled_mesa utility_source variable_requires write_file);
+
+# add some (popular) modules
+push @modules, "ExternalProject";
+
+# variables
+open(CMAKE, "cmake --help-variable-list|") or die "could not run cmake";
+while (<CMAKE>) {
+	chomp;
+	push @variables, $_;
+}
+close(CMAKE);
+
+# transform all variables in a hash - to be able to use exists later on
+my %variables = map { $_ => 1 } @variables;
+
+# commands
+open(CMAKE, "cmake --help-command-list|");
+while (my $cmd = <CMAKE>) {
+	chomp $cmd;
+
+	push @commands, $cmd;
+}
+close(CMAKE);
+
+# now generate a keyword-list per command
+foreach my $cmd (@commands) {
+	my @word = extract_upper("cmake --help-command $cmd|");
+
+	next if scalar @word == 0;
+
+	$keywords{$cmd} = [ sort keys %{ { map { $_ => 1 } @word } } ];
+}
+
+# and now for modules
+foreach my $mod (@modules) {
+	my @word = extract_upper("cmake --help-module $mod|");
+
+	next if scalar @word == 0;
+
+	$keywords{$mod} = [ sort keys %{ { map { $_ => 1 } @word } } ];
+}
+
+# and now for generator-expressions
+my @generator_expr = extract_upper("cmake --help-manual cmake-generator-expressions |");
+
+# properties
+open(CMAKE, "cmake --help-property-list|");
+while (<CMAKE>) {
+	chomp;
+	push @properties, $_;
+}
+close(CMAKE);
+
+# generate cmake.vim
+open(IN,  "<cmake.vim.in") or die "could not read cmake.vim.in";
+open(OUT, ">syntax/cmake.vim") or die "could not write to syntax/cmake.vim";
+
+my @keyword_hi;
+
+while(<IN>)
+{
+	if (m/\@([A-Z0-9_]+)\@/) { # match for @SOMETHING@
+		if ($1 eq "COMMAND_LIST") {
+			# do not include "special" commands in this list
+			my @tmp = grep { ! exists $conditional{$_} and
+			                 ! exists $loop{$_} and
+			                 ! exists $deprecated{$_} } @commands;
+			print OUT " " x 12 , "\\ ", join(" ", @tmp), "\n";
+		} elsif ($1 eq "VARIABLE_LIST") {
+			print OUT " " x 12 , "\\ ", join(" ", @variables), "\n";
+		} elsif ($1 eq "MODULES") {
+			print OUT " " x 12 , "\\ ", join("\n", @modules), "\n";
+		} elsif ($1 eq "GENERATOR_EXPRESSIONS") {
+			print OUT " " x 12 , "\\ ", join(" ", @generator_expr), "\n";
+		} elsif ($1 eq "CONDITIONALS") {
+			print OUT " " x 12 , "\\ ", join(" ", sort keys %conditional), "\n";
+		} elsif ($1 eq "LOOPS") {
+			print OUT " " x 12 , "\\ ", join(" ", sort keys %loop), "\n";
+		} elsif ($1 eq "DEPRECATED") {
+			print OUT " " x 12 , "\\ ", join(" ", sort keys %deprecated), "\n";
+		} elsif ($1 eq "KEYWORDS") {
+			foreach my $k (sort keys %keywords) {
+				print OUT "syn keyword cmakeKW$k\n";
+				print OUT " " x 12, "\\ ", join(" ", @{$keywords{$k}}), "\n";
+				print OUT " " x 12, "\\ contained\n";
+				print OUT "\n";
+				push @keyword_hi, "hi def link cmakeKW$k ModeMsg";
+			}
+		} elsif ($1 eq "KEYWORDS_HIGHLIGHT") {
+			print OUT join("\n", @keyword_hi), "\n";
+		} else {
+			print "ERROR do not know how to replace $1\n";
+		}
+	} else {
+		print OUT $_;
+	}
+}
+close(IN);
+close(OUT);
+
+sub extract_upper
+{
+	my $input = shift;
+	my @word;
+
+	open(KW, $input);
+	while (<KW>) {
+
+		foreach my $w (m/\b([A-Z_]{2,})\b/g) {
+			next
+				if exists $variables{$w} or  # skip if it is a variable
+				   exists $unwanted{$w};     # skip if not wanted
+
+			push @word, $w;
+		}
+	}
+	close(KW);
+
+	return @word;
+}

Auxiliary/vim/indent/cmake.vim

@@ -1,13 +1,3 @@
-" =============================================================================
-"
-"   Program:   CMake - Cross-Platform Makefile Generator
-"   Module:    $RCSfile$
-"   Language:  VIM
-"   Date:      $Date$
-"   Version:   $Revision$
-"
-" =============================================================================
-
 " Vim indent file
 " Language:     CMake (ft=cmake)
 " Author:       Andy Cedilnik <andy.cedilnik@kitware.com>

CMakeCPack.cmake

@@ -1,14 +1,5 @@
-#=============================================================================
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-# CMake - Cross Platform Makefile Generator
+# file Copyright.txt or https://cmake.org/licensing for details.
-# Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
-#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
-#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
 
 # If the cmake version includes cpack, use it
 if(EXISTS "${CMAKE_ROOT}/Modules/CPack.cmake")
@@ -70,6 +61,9 @@ if(EXISTS "${CMAKE_ROOT}/Modules/CPack.cmake")
   # Components
   if(CMake_INSTALL_COMPONENTS)
     set(_CPACK_IFW_COMPONENTS_ALL cmake ctest cpack)
+    if(WIN32 AND NOT CYGWIN)
+        list(APPEND _CPACK_IFW_COMPONENTS_ALL cmcldeps)
+    endif()
     if(APPLE)
       list(APPEND _CPACK_IFW_COMPONENTS_ALL cmakexbuild)
     endif()
@@ -87,8 +81,10 @@ if(EXISTS "${CMAKE_ROOT}/Modules/CPack.cmake")
     endif()
     if(BUILD_QtDialog)
       list(APPEND _CPACK_IFW_COMPONENTS_ALL cmake-gui)
-      set(_CPACK_IFW_COMPONENT_CMAKE-GUI_LICENSES "set(CPACK_IFW_COMPONENT_CMAKE-GUI_LICENSES
+      if(USE_LGPL)
-    \"LGPLv2.1\" \"${CMake_SOURCE_DIR}/Licenses/LGPLv2.1.txt\")")
+        set(_CPACK_IFW_COMPONENT_CMAKE-GUI_LICENSES "set(CPACK_IFW_COMPONENT_CMAKE-GUI_LICENSES
+    \"LGPLv${USE_LGPL}\" \"${CMake_SOURCE_DIR}/Licenses/LGPLv${USE_LGPL}.txt\")")
+      endif()
     endif()
     if(SPHINX_MAN)
       list(APPEND _CPACK_IFW_COMPONENTS_ALL sphinx-man)
@@ -102,22 +98,31 @@ if(EXISTS "${CMAKE_ROOT}/Modules/CPack.cmake")
     if(SPHINX_QTHELP)
       list(APPEND _CPACK_IFW_COMPONENTS_ALL sphinx-qthelp)
     endif()
+    if(CMake_BUILD_DEVELOPER_REFERENCE)
+      if(CMake_BUILD_DEVELOPER_REFERENCE_HTML)
+        list(APPEND _CPACK_IFW_COMPONENTS_ALL cmake-developer-reference-html)
+      endif()
+      if(CMake_BUILD_DEVELOPER_REFERENCE_QTHELP)
+        list(APPEND _CPACK_IFW_COMPONENTS_ALL cmake-developer-reference-qthelp)
+      endif()
+    endif()
     set(_CPACK_IFW_COMPONENTS_CONFIGURATION "
   # Components
   set(CPACK_COMPONENTS_ALL \"${_CPACK_IFW_COMPONENTS_ALL}\")
   set(CPACK_COMPONENTS_GROUPING IGNORE)
 ")
   else()
-    if(BUILD_QtDialog AND CMake_GUI_DISTRIBUTE_WITH_Qt_LGPL)
+    if(BUILD_QtDialog AND USE_LGPL)
       set(_CPACK_IFW_ADDITIONAL_LICENSES
-        "\"LGPLv2.1\" \"${CMake_SOURCE_DIR}/Licenses/LGPLv2.1.txt\"")
+        "\"LGPLv${USE_LGPL}\" \"${CMake_SOURCE_DIR}/Licenses/LGPLv${USE_LGPL}.txt\"")
     endif()
   endif()
 
   # Components scripts configuration
   foreach(_script
     CMake
-    CMake.Documentation.SphinxHTML)
+    CMake.Documentation.SphinxHTML
+    CMake.DeveloperReference.HTML)
     configure_file("${CMake_SOURCE_DIR}/Source/QtIFW/${_script}.qs.in"
       "${CMake_BINARY_DIR}/${_script}.qs" @ONLY)
   endforeach()
@@ -131,6 +136,11 @@ if(EXISTS "${CMAKE_ROOT}/Modules/CPack.cmake")
     if(SPHINX_HTML)
       set(_CPACK_IFW_SHORTCUT_OPTIONAL "${_CPACK_IFW_SHORTCUT_OPTIONAL}component.addOperation(\"CreateShortcut\", \"@TargetDir@/doc/cmake-${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}/html/index.html\", \"@StartMenuDir@/CMake Documentation.lnk\");\n")
     endif()
+    if(CMake_BUILD_DEVELOPER_REFERENCE)
+      if(CMake_BUILD_DEVELOPER_REFERENCE_HTML)
+      set(_CPACK_IFW_SHORTCUT_OPTIONAL "${_CPACK_IFW_SHORTCUT_OPTIONAL}component.addOperation(\"CreateShortcut\", \"@TargetDir@/doc/cmake-${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}/developer-reference/html/index.html\", \"@StartMenuDir@/CMake Developer Reference.lnk\");\n")
+      endif()
+    endif()
     configure_file("${CMake_SOURCE_DIR}/Source/QtIFW/installscript.qs.in"
       "${CMake_BINARY_DIR}/installscript.qs" @ONLY
     )
@@ -166,36 +176,11 @@ if(EXISTS "${CMAKE_ROOT}/Modules/CPack.cmake")
   set(CPACK_PACKAGE_CONTACT "cmake@cmake.org")
 
   if(UNIX)
-    set(CPACK_STRIP_FILES "bin/ccmake;bin/cmake;bin/cpack;bin/ctest")
+    set(CPACK_STRIP_FILES "${CMAKE_BIN_DIR}/ccmake;${CMAKE_BIN_DIR}/cmake;${CMAKE_BIN_DIR}/cpack;${CMAKE_BIN_DIR}/ctest")
     set(CPACK_SOURCE_STRIP_FILES "")
     set(CPACK_PACKAGE_EXECUTABLES "ccmake" "CMake")
   endif()
 
-  # cygwin specific packaging stuff
-  if(CYGWIN)
-    # setup the cygwin package name
-    set(CPACK_PACKAGE_NAME cmake)
-    # setup the name of the package for cygwin cmake-2.4.3
-    set(CPACK_PACKAGE_FILE_NAME
-      "${CPACK_PACKAGE_NAME}-${CMake_VERSION}")
-    # the source has the same name as the binary
-    set(CPACK_SOURCE_PACKAGE_FILE_NAME ${CPACK_PACKAGE_FILE_NAME})
-    # Create a cygwin version number in case there are changes for cygwin
-    # that are not reflected upstream in CMake
-    set(CPACK_CYGWIN_PATCH_NUMBER 1 CACHE STRING "patch number for CMake cygwin packages")
-    mark_as_advanced(CPACK_CYGWIN_PATCH_NUMBER)
-    # These files are required by the cmCPackCygwinSourceGenerator and the files
-    # put into the release tar files.
-    set(CPACK_CYGWIN_BUILD_SCRIPT
-      "${CMake_BINARY_DIR}/${CPACK_PACKAGE_FILE_NAME}-${CPACK_CYGWIN_PATCH_NUMBER}.sh")
-    set(CPACK_CYGWIN_PATCH_FILE
-      "${CMake_BINARY_DIR}/${CPACK_PACKAGE_FILE_NAME}-${CPACK_CYGWIN_PATCH_NUMBER}.patch")
-    # include the sub directory cmake file for cygwin that
-    # configures some files and adds some install targets
-    # this file uses some of the package file name variables
-    include(Utilities/Release/Cygwin/CMakeLists.txt)
-  endif()
-
   set(CPACK_WIX_UPGRADE_GUID "8ffd1d72-b7f1-11e2-8ee5-00238bca4991")
 
   if(MSVC AND NOT "$ENV{WIX}" STREQUAL "")

CMakeCPackOptions.cmake.in

@@ -102,13 +102,21 @@ if(CPACK_GENERATOR MATCHES "IFW")
   set(CPACK_IFW_COMPONENT_CPACK_PRIORITY 87)
   set(CPACK_IFW_COMPONENT_CPACK_VERSION "@_CPACK_IFW_PACKAGE_VERSION@")
 
+  set(CPACK_COMPONENT_CMCLDEPS_DISPLAY_NAME "cmcldeps")
+  set(CPACK_COMPONENT_CMCLDEPS_DESCRIPTION
+    "The \"cmcldeps\" executable is wrapper around \"cl\" program")
+  set(CPACK_COMPONENT_CMCLDEPS_GROUP Tools)
+  set(CPACK_IFW_COMPONENT_CMCLDEPS_NAME "CMClDeps")
+  set(CPACK_IFW_COMPONENT_CMCLDEPS_PRIORITY 86)
+  set(CPACK_IFW_COMPONENT_CMCLDEPS_VERSION "@_CPACK_IFW_PACKAGE_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 86)
+  set(CPACK_IFW_COMPONENT_CMAKEXBUILD_PRIORITY 85)
   set(CPACK_IFW_COMPONENT_CMAKEXBUILD_VERSION "@_CPACK_IFW_PACKAGE_VERSION@")
 
   # Dialogs
@@ -167,6 +175,29 @@ if(CPACK_GENERATOR MATCHES "IFW")
   set(CPACK_IFW_COMPONENT_SPHINX-QTHELP_NAME "SphinxQtHelp")
   set(CPACK_IFW_COMPONENT_SPHINX-QTHELP_VERSION "@_CPACK_IFW_PACKAGE_VERSION@")
 
+  # Developer Reference
+  set(CPACK_COMPONENT_GROUP_DEVELOPERREFERENCE_DISPLAY_NAME "Developer Reference")
+  set(CPACK_COMPONENT_GROUP_DEVELOPERREFERENCE_DESCRIPTION
+    "CMake Reference in different formats (html, qch)")
+  set(CPACK_COMPONENT_GROUP_DEVELOPERREFERENCE_PARENT_GROUP CMake)
+  set(CPACK_IFW_COMPONENT_GROUP_DEVELOPERREFERENCE_PRIORITY 50)
+  set(CPACK_IFW_COMPONENT_GROUP_DEVELOPERREFERENCE_VERSION
+    "@_CPACK_IFW_PACKAGE_VERSION@")
+
+  set(CPACK_COMPONENT_CMAKE-DEVELOPER-REFERENCE-HTML_DISPLAY_NAME "HTML")
+  set(CPACK_COMPONENT_CMAKE-DEVELOPER-REFERENCE-HTML_GROUP DeveloperReference)
+  set(CPACK_COMPONENT_CMAKE-DEVELOPER-REFERENCE-HTML_DISABLED TRUE)
+  set(CPACK_IFW_COMPONENT_CMAKE-DEVELOPER-REFERENCE-HTML_NAME "HTML")
+  set(CPACK_IFW_COMPONENT_CMAKE-DEVELOPER-REFERENCE-HTML_SCRIPT
+    "@CMake_BINARY_DIR@/CMake.DeveloperReference.HTML.qs")
+  set(CPACK_IFW_COMPONENT_CMAKE-DEVELOPER-REFERENCE-HTML_VERSION "@_CPACK_IFW_PACKAGE_VERSION@")
+
+  set(CPACK_COMPONENT_CMAKE-DEVELOPER-REFERENCE-QTHELP_DISPLAY_NAME "Qt Compressed Help")
+  set(CPACK_COMPONENT_CMAKE-DEVELOPER-REFERENCE-QTHELP_GROUP DeveloperReference)
+  set(CPACK_COMPONENT_CMAKE-DEVELOPER-REFERENCE-QTHELP_DISABLED TRUE)
+  set(CPACK_IFW_COMPONENT_CMAKE-DEVELOPER-REFERENCE-QTHELP_NAME "QtHelp")
+  set(CPACK_IFW_COMPONENT_CMAKE-DEVELOPER-REFERENCE-QTHELP_VERSION "@_CPACK_IFW_PACKAGE_VERSION@")
+
 endif()
 
 if(CPACK_GENERATOR MATCHES "CygwinSource")

CMakeLists.txt

@@ -1,15 +1,7 @@
-#=============================================================================
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-# CMake - Cross Platform Makefile Generator
+# file Copyright.txt or https://cmake.org/licensing for details.
-# Copyright 2000-2012 Kitware, Inc., Insight Software Consortium
+
-#
+cmake_minimum_required(VERSION 2.8.12.2 FATAL_ERROR)
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
-#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
-cmake_minimum_required(VERSION 2.8.4 FATAL_ERROR)
 if(POLICY CMP0025)
   cmake_policy(SET CMP0025 NEW)
 endif()
@@ -18,6 +10,10 @@ if(POLICY CMP0053)
 endif()
 project(CMake)
 
+# Make sure we can find internal find_package modules only used for
+# building CMake and not for shipping externally
+list(INSERT CMAKE_MODULE_PATH 0 ${CMake_SOURCE_DIR}/Source/Modules)
+
 if(CMAKE_BOOTSTRAP)
   # Running from bootstrap script.  Set local variable and remove from cache.
   set(CMAKE_BOOTSTRAP 1)
@@ -28,6 +24,16 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
   set(CMake_BIN_DIR ${CMake_BINARY_DIR}/bin)
 endif()
 
+if(CMake_GUI_DISTRIBUTE_WITH_Qt_LGPL)
+  if(CMake_GUI_DISTRIBUTE_WITH_Qt_LGPL MATCHES "^3|2\\.1$")
+    set(USE_LGPL "${CMake_GUI_DISTRIBUTE_WITH_Qt_LGPL}")
+  else()
+    set(USE_LGPL "2.1")
+  endif()
+else()
+  set(USE_LGPL "")
+endif()
+
 if("${CMake_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
   # Disallow architecture-specific try_run.  It may not run on the host.
   macro(TRY_RUN)
@@ -57,7 +63,7 @@ if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
   endif()
 endif()
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
-  include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx11_unordered_map.cmake)
+  include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx_features.cmake)
 endif()
 
 # option to set the internal encoding of CMake to UTF-8
@@ -83,6 +89,11 @@ option(CMake_INSTALL_DEPENDENCIES
   "Whether to install 3rd-party runtime dependencies" OFF)
 mark_as_advanced(CMake_INSTALL_DEPENDENCIES)
 
+# option to build reference for CMake developers
+option(CMake_BUILD_DEVELOPER_REFERENCE
+  "Build CMake Developer Reference" OFF)
+mark_as_advanced(CMake_BUILD_DEVELOPER_REFERENCE)
+
 #-----------------------------------------------------------------------
 # a macro to deal with system libraries, implemented as a macro
 # simply to improve readability of the main script
@@ -97,7 +108,7 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
 
   # Allow the user to enable/disable all system utility library options by
   # defining CMAKE_USE_SYSTEM_LIBRARIES or CMAKE_USE_SYSTEM_LIBRARY_${util}.
-  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA ZLIB)
+  set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBUV ZLIB)
   foreach(util ${UTILITIES})
     if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
         AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
@@ -137,6 +148,7 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
     "${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}")
   option(CMAKE_USE_SYSTEM_JSONCPP "Use system-installed jsoncpp" "${CMAKE_USE_SYSTEM_LIBRARY_JSONCPP}")
+  option(CMAKE_USE_SYSTEM_LIBUV "Use system-installed libuv" "${CMAKE_USE_SYSTEM_LIBRARY_LIBUV}")
 
   # For now use system KWIML only if explicitly requested rather
   # than activating via the general system libs options.
@@ -433,7 +445,7 @@ macro (CMAKE_BUILD_UTILITIES)
   # Build jsoncpp library.
   if(CMAKE_USE_SYSTEM_JSONCPP)
     if(NOT CMAKE_VERSION VERSION_LESS 3.0)
-      include(${CMake_SOURCE_DIR}/Source/Modules/FindJsonCpp.cmake)
+      find_package(JsonCpp)
     else()
       message(FATAL_ERROR "CMAKE_USE_SYSTEM_JSONCPP requires CMake >= 3.0")
     endif()
@@ -448,6 +460,55 @@ macro (CMAKE_BUILD_UTILITIES)
     CMAKE_SET_TARGET_FOLDER(cmjsoncpp "Utilities/3rdParty")
   endif()
 
+  #---------------------------------------------------------------------
+  # Build libuv library.
+  if(NOT DEFINED CMAKE_USE_LIBUV)
+    set(CMAKE_USE_LIBUV 1)
+    if(APPLE)
+      include(CheckCSourceCompiles)
+      check_c_source_compiles("
+#include <CoreServices/CoreServices.h>
+#include <AvailabilityMacros.h>
+#ifndef MAC_OS_X_VERSION_10_5
+#error \"MAC_OS_X_VERSION_10_5 is not defined\"
+#endif
+int main(void) { return 0; }
+" HAVE_CoreServices_OS_X_10_5)
+      if(NOT HAVE_CoreServices_OS_X_10_5)
+        set(CMAKE_USE_LIBUV 0)
+      endif()
+    elseif(CYGWIN)
+      # libuv does not support Cygwin
+      set(CMAKE_USE_LIBUV 0)
+    elseif(CMAKE_SYSTEM_NAME STREQUAL "HP-UX")
+      # Disable until it can be ported.
+      set(CMAKE_USE_LIBUV 0)
+    elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "sparc")
+      # Disable until it can be ported.
+      set(CMAKE_USE_LIBUV 0)
+    endif()
+  endif()
+  if(CMAKE_USE_LIBUV)
+    if(CMAKE_USE_SYSTEM_LIBUV)
+      if(NOT CMAKE_VERSION VERSION_LESS 3.0)
+        find_package(LibUV 1.0.0)
+      else()
+        message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBUV requires CMake >= 3.0")
+      endif()
+      if(NOT LIBUV_FOUND)
+        message(FATAL_ERROR
+          "CMAKE_USE_SYSTEM_LIBUV is ON but a libuv is not found!")
+      endif()
+      set(CMAKE_LIBUV_LIBRARIES LibUV::LibUV)
+    else()
+      set(CMAKE_LIBUV_LIBRARIES cmlibuv)
+      add_subdirectory(Utilities/cmlibuv)
+      CMAKE_SET_TARGET_FOLDER(cmlibuv "Utilities/3rdParty")
+    endif()
+  else()
+    set(CMAKE_LIBUV_LIBRARIES)
+  endif()
+
   #---------------------------------------------------------------------
   # Build XMLRPC library for CMake and CTest.
   if(CTEST_USE_XMLRPC)
@@ -637,6 +698,31 @@ endif()
 # setup some Testing support (a macro defined in this file)
 CMAKE_SETUP_TESTING()
 
+# Check whether to build server mode or not:
+if(NOT CMake_TEST_EXTERNAL_CMAKE)
+  if(NOT DEFINED CMake_ENABLE_SERVER_MODE)
+    list(FIND CMAKE_CXX_COMPILE_FEATURES cxx_auto_type CMake_HAVE_CXX_AUTO_TYPE)
+    list(FIND CMAKE_CXX_COMPILE_FEATURES cxx_range_for CMake_HAVE_CXX_RANGE_FOR)
+    if(CMAKE_USE_LIBUV
+        AND CMake_HAVE_CXX_AUTO_TYPE
+        AND CMake_HAVE_CXX_MAKE_UNIQUE
+        AND CMake_HAVE_CXX_RANGE_FOR
+        )
+      set(CMake_ENABLE_SERVER_MODE 1)
+    else()
+      set(CMake_ENABLE_SERVER_MODE 0)
+    endif()
+  endif()
+  if(CMake_ENABLE_SERVER_MODE AND NOT CMAKE_USE_LIBUV)
+    message(FATAL_ERROR "The server mode requires libuv!")
+  endif()
+else()
+  set(CMake_ENABLE_SERVER_MODE 0)
+endif()
+if(NOT DEFINED CMake_TEST_SERVER_MODE)
+  set(CMake_TEST_SERVER_MODE ${CMake_ENABLE_SERVER_MODE})
+endif()
+
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
   if(NOT CMake_VERSION_IS_RELEASE)
     if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND

CONTRIBUTING.rst

@@ -6,22 +6,26 @@ Community
 
 CMake is maintained and supported by `Kitware`_ and developed in
 collaboration with a productive community of contributors.
+Please subscribe and post to the `CMake Developers List`_ to raise
+discussion of development topics.
 
 .. _`Kitware`: http://www.kitware.com/cmake
-
-The preferred entry point for new contributors is the mailing list.
-Please subscribe and post to the `CMake Developers List`_ to offer
-contributions.  Regular and productive contributors may be invited
-to gain direct push access.
-
 .. _`CMake Developers List`: https://cmake.org/mailman/listinfo/cmake-developers
 
 Patches
 =======
 
-Please base all new work on the ``master`` branch.  Then use
+CMake uses `Kitware's GitLab Instance`_ to manage development and code review.
-``git format-patch`` to produce patches suitable to post to
+To contribute patches:
-the mailing list.
+
+#. Fork the upstream `CMake Repository`_ into a personal account.
+#. Base all new work on the upstream ``master`` branch.
+#. Create commits making incremental, distinct, logically complete changes.
+#. Push a topic branch to a personal repository fork on GitLab.
+#. Create a GitLab Merge Request targeting the upstream ``master`` branch.
+
+.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
+.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
 
 Code Style
 ==========
@@ -29,9 +33,11 @@ Code Style
 We use `clang-format`_ to define our style for C++ code in the CMake source
 tree.  See the `.clang-format`_ configuration file for our style settings.
 Use ``clang-format`` version 3.8 or higher to format source files.
+See also the `Utilities/Scripts/clang-format.bash`_ script.
 
 .. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
 .. _`.clang-format`: .clang-format
+.. _`Utilities/Scripts/clang-format.bash`: Utilities/Scripts/clang-format.bash
 
 License
 =======

CTestConfig.cmake

@@ -1,14 +1,6 @@
-#=============================================================================
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-# CMake - Cross Platform Makefile Generator
+# file Copyright.txt or https://cmake.org/licensing for details.
-# Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
+
-#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
-#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
 set(CTEST_PROJECT_NAME "CMake")
 set(CTEST_NIGHTLY_START_TIME "1:00:00 UTC")
 

CTestCustom.cmake.in

@@ -49,6 +49,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "stl_deque.h:1051"
   "(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"
   "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.*"
@@ -62,13 +63,17 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "warning.*This version of Mac OS X is unsupported"
   "clang.*: warning: argument unused during compilation: .-g"
   "note: in expansion of macro" # diagnostic context note
+  "note: expanded from macro" # diagnostic context note
   "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*rand.*may return deterministic values"
   "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*rand.*isn.*t random" # we do not do crypto
   "cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*srand.*seed choices are.*poor" # we do not do crypto
+  "IPA warning: function.*multiply defined in"
 
   # Ignore clang's summary warning, assuming prior text has matched some
   # other warning expression:
   "[0-9,]+ warnings? generated."
+  # similarly for PGI
+  "compilation completed with warnings"
 
 # scanbuild exceptions
   "char_traits.h:.*: warning: Null pointer argument in call to string length function"
@@ -80,8 +85,11 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "index_encoder.c.241.2. warning: Value stored to .out_start. is never read"
   "index.c.*warning: Access to field.*results in a dereference of a null pointer.*loaded from variable.*"
   "cm_sha2.*warning: Value stored to.*is never read"
+  "cmFortranLexer.cxx:[0-9]+:[0-9]+: warning: Call to 'realloc' has an allocation size of 0 bytes"
   "testProcess.*warning: Dereference of null pointer .loaded from variable .invalidAddress.."
   "liblzma/simple/x86.c:[0-9]+:[0-9]+: warning: The result of the '<<' expression is undefined"
+  "libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
+  "libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '==' is a garbage value"
   )
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")

CompileFlags.cmake

@@ -1,14 +1,5 @@
-#=============================================================================
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-# CMake - Cross Platform Makefile Generator
+# file Copyright.txt or https://cmake.org/licensing for details.
-# Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
-#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
-#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
 
 #-----------------------------------------------------------------------------
 # set some special flags for different compilers
@@ -64,7 +55,7 @@ endif()
 
 # Workaround for short jump tables on PA-RISC
 if(CMAKE_SYSTEM_PROCESSOR MATCHES "^parisc")
-  if(CMAKE_COMPILER_IS_GNUC)
+  if(CMAKE_COMPILER_IS_GNUCC)
     set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mlong-calls")
   endif()
   if(CMAKE_COMPILER_IS_GNUCXX)
@@ -80,6 +71,13 @@ if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro)
   endif()
 endif()
 
+foreach(lang C CXX)
+  # Suppress warnings from PGI compiler.
+  if (CMAKE_${lang}_COMPILER_ID STREQUAL "PGI")
+    set(CMAKE_${lang}_FLAGS "${CMAKE_${lang}_FLAGS} -w")
+  endif()
+endforeach()
+
 # use the ansi CXX compile flag for building cmake
 if (CMAKE_ANSI_CXXFLAGS)
   set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CMAKE_ANSI_CXXFLAGS}")

Copyright.txt

@@ -1,6 +1,5 @@
 CMake - Cross Platform Makefile Generator
-Copyright 2000-2016 Kitware, Inc.
+Copyright 2000-2016 Kitware, Inc. and Contributors
-Copyright 2000-2011 Insight Software Consortium
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -14,10 +13,9 @@ are met:
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
 
-* Neither the names of Kitware, Inc., the Insight Software Consortium,
+* Neither the name of Kitware, Inc. nor the names of Contributors
-  nor the names of their contributors may be used to endorse or promote
+  may be used to endorse or promote products derived from this
-  products derived from this software without specific prior written
+  software without specific prior written permission.
-  permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
@@ -33,12 +31,77 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 ------------------------------------------------------------------------------
 
+The following individuals and institutions are among the Contributors:
+
+* Aaron C. Meadows <cmake@shadowguarddev.com>
+* Aleksey Avdeev <solo@altlinux.ru>
+* Alexander Neundorf <neundorf@kde.org>
+* Alexander Smorkalov <alexander.smorkalov@itseez.com>
+* Alex Turbov <i.zaufi@gmail.com>
+* Andreas Pakulat <apaku@gmx.de>
+* Andreas Schneider <asn@cryptomilk.org>
+* André Rigland Brodtkorb <Andre.Brodtkorb@ifi.uio.no>
+* Axel Huebl, Helmholtz-Zentrum Dresden - Rossendorf
+* Benjamin Eikel
+* Bjoern Ricks <bjoern.ricks@gmail.com>
+* Brad Hards <bradh@kde.org>
+* Christopher Harvey
+* Christoph Grüninger <foss@grueninger.de>
+* Clement Creusot <creusot@cs.york.ac.uk>
+* Daniel Blezek <blezek@gmail.com>
+* Daniel Pfeifer <daniel@pfeifer-mail.de>
+* Enrico Scholz <enrico.scholz@informatik.tu-chemnitz.de>
+* Eran Ifrah <eran.ifrah@gmail.com>
+* Esben Mose Hansen, Ange Optimization ApS
+* Geoffrey Viola <geoffrey.viola@asirobots.com>
+* Gregor Jasny
+* Helio Chissini de Castro <helio@kde.org>
+* Ilya Lavrenov <ilya.lavrenov@itseez.com>
+* Insight Software Consortium <insightsoftwareconsortium.org>
+* Jan Woetzel
+* Kelly Thompson <kgt@lanl.gov>
+* Konstantin Podsvirov <konstantin@podsvirov.pro>
+* Mario Bensi <mbensi@ipsquad.net>
+* Mathieu Malaterre <mathieu.malaterre@gmail.com>
+* Matthaeus G. Chajdas
+* Matthias Kretz <kretz@kde.org>
+* Matthias Maennich <matthias@maennich.net>
+* Miguel A. Figueroa-Villanueva
+* Mike Jackson
+* Mike McQuaid <mike@mikemcquaid.com>
+* Nicolas Bock <nicolasbock@gmail.com>
+* Nicolas Despres <nicolas.despres@gmail.com>
+* Nikita Krupen'ko <krnekit@gmail.com>
+* OpenGamma Ltd. <opengamma.com>
+* Per Øyvind Karlsen <peroyvind@mandriva.org>
+* Peter Collingbourne <peter@pcc.me.uk>
+* Petr Gotthard <gotthard@honeywell.com>
+* Philip Lowman <philip@yhbt.com>
+* Philippe Proulx <pproulx@efficios.com>
+* Raffi Enficiaud, Max Planck Society
+* Raumfeld <raumfeld.com>
+* Roger Leigh <rleigh@codelibre.net>
+* Rolf Eike Beer <eike@sf-mail.de>
+* Roman Donchenko <roman.donchenko@itseez.com>
+* Roman Kharitonov <roman.kharitonov@itseez.com>
+* Ruslan Baratov
+* Sebastian Holtermann <sebholt@xwmw.org>
+* Stephen Kelly <steveire@gmail.com>
+* Sylvain Joubert <joubert.sy@gmail.com>
+* Thomas Sondergaard <ts@medical-insight.com>
+* Tobias Hunger <tobias.hunger@qt.io>
+* Todd Gamblin <tgamblin@llnl.gov>
+* Tristan Carel
+* University of Dundee
+* Vadim Zhukov
+* Will Dicharry <wdicharry@stellarscience.com>
+
+See version control history for details of individual contributions.
+
 The above copyright and license notice applies to distributions of
-CMake in source and binary form.  Some source files contain additional
+CMake in source and binary form.  Third-party software packages supplied
-notices of original copyright by their contributors; see each source
+with CMake under compatible licenses provide their own copyright notices
-for details.  Third-party software packages supplied with CMake under
+documented in corresponding subdirectories or source files.
-compatible licenses provide their own copyright notices documented in
-corresponding subdirectories.
 
 ------------------------------------------------------------------------------
 

DartConfig.cmake

@@ -1,14 +1,6 @@
-#=============================================================================
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
-# CMake - Cross Platform Makefile Generator
+# file Copyright.txt or https://cmake.org/licensing for details.
-# Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
+
-#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
-#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
 set(CTEST_PROJECT_NAME "CMake")
 set(CTEST_NIGHTLY_START_TIME "21:00:00 EDT")
 

Help/command/add_custom_command.rst

@@ -20,6 +20,7 @@ The first signature is for adding a custom command to produce an output::
                                       [<lang2> depend2] ...]
                      [WORKING_DIRECTORY dir]
                      [COMMENT comment]
+                     [DEPFILE depfile]
                      [VERBATIM] [APPEND] [USES_TERMINAL])
 
 This defines a command to generate specified ``OUTPUT`` file(s).
@@ -170,6 +171,12 @@ The options are:
   If it is a relative path it will be interpreted relative to the
   build tree directory corresponding to the current source directory.
 
+``DEPFILE``
+  Specify a ``.d`` depfile for the :generator:`Ninja` generator.
+  A ``.d`` file holds dependencies usually emitted by the custom
+  command itself.
+  Using ``DEPFILE`` with other generators than Ninja is an error.
+
 Build Events
 ^^^^^^^^^^^^
 

Help/command/cmake_parse_arguments.rst

@@ -11,6 +11,17 @@ respective options.
   cmake_parse_arguments(<prefix> <options> <one_value_keywords>
                         <multi_value_keywords> args...)
 
+  cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
+                        <multi_value_keywords>)
+
+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 values to have special characters like ``;`` in them.
 
 The ``<options>`` argument contains all options for the respective macro,
 i.e.  keywords which can be used when calling the macro without any value

Help/command/ctest_build.rst

@@ -13,6 +13,7 @@ Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
               [NUMBER_ERRORS <num-err-var>]
               [NUMBER_WARNINGS <num-warn-var>]
               [RETURN_VALUE <result-var>]
+              [CAPTURE_CMAKE_ERROR <result-var>]
               )
 
 Build the project and store results in ``Build.xml``
@@ -29,9 +30,11 @@ The options are:
   :variable:`CTEST_BINARY_DIRECTORY` variable is used.
 
 ``APPEND``
-  Mark results for append to those previously submitted to a
+  Mark ``Build.xml`` for append to results previously submitted to a
   dashboard server since the last :command:`ctest_start` call.
   Append semantics are defined by the dashboard server in use.
+  This does *not* cause results to be appended to a ``.xml`` file
+  produced by a previous call to this command.
 
 ``CONFIGURATION <config>``
   Specify the build configuration (e.g. ``Debug``).  If not
@@ -66,6 +69,10 @@ The options are:
 ``RETURN_VALUE <result-var>``
   Store the return value of the native build tool in the given variable.
 
+``CAPTURE_CMAKE_ERROR <result-var>``
+  Store in the ``<result-var>`` variable -1 if there are any errors running
+  the command and prevent ctest from returning non-zero if an error occurs.
+
 ``QUIET``
   Suppress any CTest-specific non-error output that would have been
   printed to the console otherwise.  The summary of warnings / errors,

Help/command/ctest_configure.rst

@@ -6,7 +6,8 @@ Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
 ::
 
   ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
-                  [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET])
+                  [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
+                  [CAPTURE_CMAKE_ERROR <result-var>])
 
 Configure the project build tree and record results in ``Configure.xml``
 for submission with the :command:`ctest_submit` command.
@@ -22,9 +23,11 @@ The options are:
   :variable:`CTEST_SOURCE_DIRECTORY` variable is used.
 
 ``APPEND``
-  Mark results for append to those previously submitted to a
+  Mark ``Configure.xml`` for append to results previously submitted to a
   dashboard server since the last :command:`ctest_start` call.
   Append semantics are defined by the dashboard server in use.
+  This does *not* cause results to be appended to a ``.xml`` file
+  produced by a previous call to this command.
 
 ``OPTIONS <options>``
   Specify command-line arguments to pass to the configuration tool.
@@ -33,6 +36,10 @@ The options are:
   Store in the ``<result-var>`` variable the return value of the native
   configuration tool.
 
+``CAPTURE_CMAKE_ERROR <result-var>``
+  Store in the ``<result-var>`` variable -1 if there are any errors running
+  the command and prevent ctest from returning non-zero if an error occurs.
+
 ``QUIET``
   Suppress any CTest-specific non-error messages that would have
   otherwise been printed to the console.  Output from the underlying

Help/command/ctest_coverage.rst

@@ -8,6 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
   ctest_coverage([BUILD <build-dir>] [APPEND]
                  [LABELS <label>...]
                  [RETURN_VALUE <result-var>]
+                 [CAPTURE_CMAKE_ERROR <result-var]
                  [QUIET]
                  )
 
@@ -21,9 +22,11 @@ The options are:
   :variable:`CTEST_BINARY_DIRECTORY` variable is used.
 
 ``APPEND``
-  Mark results for append to those previously submitted to a
+  Mark ``Coverage.xml`` for append to results previously submitted to a
   dashboard server since the last :command:`ctest_start` call.
   Append semantics are defined by the dashboard server in use.
+  This does *not* cause results to be appended to a ``.xml`` file
+  produced by a previous call to this command.
 
 ``LABELS``
   Filter the coverage report to include only source files labeled
@@ -33,6 +36,10 @@ The options are:
   Store in the ``<result-var>`` variable ``0`` if coverage tools
   ran without error and non-zero otherwise.
 
+``CAPTURE_CMAKE_ERROR <result-var>``
+  Store in the ``<result-var>`` variable -1 if there are any errors running
+  the command and prevent ctest from returning non-zero if an error occurs.
+
 ``QUIET``
   Suppress any CTest-specific non-error output that would have been
   printed to the console otherwise.  The summary indicating how many

Help/command/ctest_test.rst

@@ -18,6 +18,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
              [SCHEDULE_RANDOM <ON|OFF>]
              [STOP_TIME <time-of-day>]
              [RETURN_VALUE <result-var>]
+             [CAPTURE_CMAKE_ERROR <result-var>]
              [QUIET]
              )
 
@@ -31,9 +32,11 @@ The options are:
   :variable:`CTEST_BINARY_DIRECTORY` variable is used.
 
 ``APPEND``
-  Mark results for append to those previously submitted to a
+  Mark ``Test.xml`` for append to results previously submitted to a
   dashboard server since the last :command:`ctest_start` call.
   Append semantics are defined by the dashboard server in use.
+  This does *not* cause results to be appended to a ``.xml`` file
+  produced by a previous call to this command.
 
 ``START <start-number>``
   Specify the beginning of a range of test numbers.
@@ -80,6 +83,10 @@ The options are:
   Store in the ``<result-var>`` variable ``0`` if all tests passed.
   Store non-zero if anything went wrong.
 
+``CAPTURE_CMAKE_ERROR <result-var>``
+  Store in the ``<result-var>`` variable -1 if there are any errors running
+  the command and prevent ctest from returning non-zero if an error occurs.
+
 ``QUIET``
   Suppress any CTest-specific non-error messages that would have otherwise
   been printed to the console.  Output from the underlying test command is not

Help/command/ctest_upload.rst

@@ -5,7 +5,7 @@ Upload files to a dashboard server as a :ref:`Dashboard Client`.
 
 ::
 
-  ctest_upload(FILES <file>... [QUIET])
+  ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
 
 The options are:
 
@@ -16,3 +16,7 @@ The options are:
 ``QUIET``
   Suppress any CTest-specific non-error output that would have been
   printed to the console otherwise.
+
+``CAPTURE_CMAKE_ERROR <result-var>``
+  Store in the ``<result-var>`` variable -1 if there are any errors running
+  the command and prevent ctest from returning non-zero if an error occurs.

Help/command/export.rst

@@ -55,3 +55,18 @@ 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
 is enabled, the ``export(PACKAGE)`` command will do nothing.
+
+::
+
+  export(TARGETS [target1 [target2 [...]]]  [ANDROID_MK <filename>])
+
+This signature exports cmake built targets to the android ndk build system
+by creating an Android.mk file that references the prebuilt targets. The
+Android NDK supports the use of prebuilt libraries, both static and shared.
+This allows cmake to build the libraries of a project and make them available
+to an ndk build system complete with transitive dependencies, include flags
+and defines required to use the libraries. The signature takes a list of
+targets and puts them in the Android.mk file specified by the ``<filename>``
+given. This signature can only be used if policy CMP0022 is NEW for all
+targets given. A error will be issued if that policy is set to OLD for one
+of the targets.

Help/command/file.rst

@@ -222,6 +222,12 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 ``TIMEOUT <seconds>``
   Terminate the operation after a given total time has elapsed.
 
+``USERPWD <username>:<password>``
+  Set username and password for operation.
+
+``HTTPHEADER <HTTP-header>``
+  HTTP header for operation. Suboption can be repeated several times.
+
 Additional options to ``DOWNLOAD`` are:
 
 ``EXPECTED_HASH ALGO=<value>``

Help/command/find_library.rst

@@ -49,6 +49,13 @@ path to the framework ``<fullPath>/A.framework``.  When a full path to a
 framework is used as a library, CMake will use a ``-framework A``, and a
 ``-F<fullPath>`` to link the framework to the target.
 
+If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set
+all search paths will be tested as normal, with ``32/`` appended, and
+with all matches of ``lib/`` replaced with ``lib32/``.  This property is
+automatically set for the platforms that are known to need it if at
+least one of the languages supported by the :command:`project` command
+is enabled.
+
 If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
 all search paths will be tested as normal, with ``64/`` appended, and
 with all matches of ``lib/`` replaced with ``lib64/``.  This property is

Help/command/find_package.rst

@@ -170,11 +170,21 @@ is acceptable the following variables are set:
 ``<package>_VERSION_COUNT``
   number of version components, 0 to 4
 
-and the corresponding package configuration file is loaded.  When
+and the corresponding package configuration file is loaded.
-multiple package configuration files are available whose version files
+When multiple package configuration files are available whose version files
 claim compatibility with the version requested it is unspecified which
-one is chosen.  No attempt is made to choose a highest or closest
+one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
-version number.
+is set no attempt is made to choose a highest or closest version number.
+
+To control the order in which ``find_package`` checks for compatibiliy 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::
+
+  SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
+  SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+before calling ``find_package``.
 
 Config mode provides an elaborate interface and search procedure.
 Much of the interface is provided for completeness and for use
@@ -194,13 +204,16 @@ configuration file.  The tables below show the directories searched.
 Each entry is meant for installation trees following Windows (W), UNIX
 (U), or Apple (A) conventions::
 
-  <prefix>/                                               (W)
+  <prefix>/                                                       (W)
-  <prefix>/(cmake|CMake)/                                 (W)
+  <prefix>/(cmake|CMake)/                                         (W)
-  <prefix>/<name>*/                                       (W)
+  <prefix>/<name>*/                                               (W)
-  <prefix>/<name>*/(cmake|CMake)/                         (W)
+  <prefix>/<name>*/(cmake|CMake)/                                 (W)
-  <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/          (U)
+  <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/                  (U)
-  <prefix>/(lib/<arch>|lib|share)/<name>*/                (U)
+  <prefix>/(lib/<arch>|lib|share)/<name>*/                        (U)
-  <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (U)
+  <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/          (U)
+  <prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/          (W/U)
+  <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/                (W/U)
+  <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (W/U)
 
 On systems supporting OS X Frameworks and Application Bundles the
 following directories are searched for frameworks or bundles

Help/command/get_cmake_property.rst

@@ -1,15 +1,20 @@
 get_cmake_property
 ------------------
 
-Get a property of the CMake instance.
+Get a global property of the CMake instance.
 
 ::
 
   get_cmake_property(VAR property)
 
-Get a property from the CMake instance.  The value of the property is
+Get a global property from the CMake instance.  The value of the property is
 stored in the variable ``VAR``.  If the property is not found, ``VAR``
 will be  set to "NOTFOUND".  See the :manual:`cmake-properties(7)` manual
 for available properties.
 
-See also the more general :command:`get_property` command.
+See also the :command:`get_property` command ``GLOBAL`` option.
+
+In addition to global properties, this command (for historical reasons)
+also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory
+properties.  It also supports a special ``COMPONENTS`` global property that
+lists the components given to the :command:`install` command.

Help/command/if.rst

@@ -30,10 +30,12 @@ else and endif clause is optional.  Long expressions can be used and
 there is a traditional order of precedence.  Parenthetical expressions
 are evaluated first followed by unary tests such as ``EXISTS``,
 ``COMMAND``, and ``DEFINED``.  Then any binary tests such as
-``EQUAL``, ``LESS``, ``GREATER``, ``STRLESS``, ``STRGREATER``,
+``EQUAL``, ``LESS``, ``LESS_EQUAL, ``GREATER``, ``GREATER_EQUAL``,
-``STREQUAL``, and ``MATCHES`` will be evaluated.  Then boolean ``NOT``
+``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``,
-operators and finally boolean ``AND`` and then ``OR`` operators will
+``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``,
-be evaluated.
+``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``,
+and ``MATCHES`` will be evaluated.  Then boolean ``NOT`` operators and
+finally boolean ``AND`` and then ``OR`` operators will be evaluated.
 
 Possible expressions are:
 
@@ -115,6 +117,14 @@ Possible expressions are:
  True if the given string or variable's value is a valid number and equal
  to that on the right.
 
+``if(<variable|string> LESS_EQUAL <variable|string>)``
+ True if the given string or variable's value is a valid number and less
+ than or equal to that on the right.
+
+``if(<variable|string> GREATER_EQUAL <variable|string>)``
+ True if the given string or variable's value is a valid number and greater
+ than or equal to that on the right.
+
 ``if(<variable|string> STRLESS <variable|string>)``
  True if the given string or variable's value is lexicographically less
  than the string or variable on the right.
@@ -127,15 +137,31 @@ Possible expressions are:
  True if the given string or variable's value is lexicographically equal
  to the string or variable on the right.
 
+``if(<variable|string> STRLESS_EQUAL <variable|string>)``
+ True if the given string or variable's value is lexicographically less
+ than or equal to the string or variable on the right.
+
+``if(<variable|string> STRGREATER_EQUAL <variable|string>)``
+ True if the given string or variable's value is lexicographically greater
+ than or equal to the string or variable on the right.
+
 ``if(<variable|string> VERSION_LESS <variable|string>)``
  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``).
 
+``if(<variable|string> VERSION_GREATER <variable|string>)``
+ Component-wise integer version number comparison (version format is
+ ``major[.minor[.patch[.tweak]]]``).
+
 ``if(<variable|string> VERSION_EQUAL <variable|string>)``
  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``).
 
-``if(<variable|string> VERSION_GREATER <variable|string>)``
+``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)``
+ Component-wise integer version number comparison (version format is
+ ``major[.minor[.patch[.tweak]]]``).
+
+``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)``
  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``).
 
@@ -186,20 +212,21 @@ above-documented signature accepts ``<variable|string>``:
 * If the left hand argument to ``MATCHES`` is missing it returns false
   without error
 
-* Both left and right hand arguments to ``LESS``, ``GREATER``, and
+* Both left and right hand arguments to ``LESS``, ``GREATER``, ``EQUAL``,
-  ``EQUAL`` are independently tested to see if they are defined
+  ``LESS_EQUAL``, and ``GREATER_EQUAL``, are independently tested to see if
-  variables, if so their defined values are used otherwise the original
+  they are defined variables, if so their defined values are used otherwise
-  value is used.
+  the original value is used.
 
-* Both left and right hand arguments to ``STRLESS``, ``STREQUAL``, and
+* Both left and right hand arguments to ``STRLESS``, ``STRGREATER``,
-  ``STRGREATER`` are independently tested to see if they are defined
+  ``STREQUAL``, ``STRLESS_EQUAL``, and ``STRGREATER_EQUAL`` are independently
-  variables, if so their defined values are used otherwise the original
+  tested to see if they are defined variables, if so their defined values are
-  value is used.
+  used otherwise the original value is used.
 
 * Both left and right hand arguments to ``VERSION_LESS``,
-  ``VERSION_EQUAL``, and ``VERSION_GREATER`` are independently tested
+  ``VERSION_GREATER``, ``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, and
-  to see if they are defined variables, if so their defined values are
+  ``VERSION_GREATER_EQUAL`` are independently tested to see if they are defined
-  used otherwise the original value is used.
+  variables, if so their defined values are used otherwise the original value
+  is used.
 
 * The right hand argument to ``NOT`` is tested to see if it is a boolean
   constant, if so the value is used, otherwise it is assumed to be a

Help/command/include.rst

@@ -15,10 +15,10 @@ is present, then no error is raised if the file does not exist.  If
 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`,
+``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,
 then in the CMake module directory.  There is one exception to this: if
-the file which calls ``include()`` is located itself in the CMake module
+the file which calls ``include()`` is located itself in the CMake builtin
-directory, then first the CMake module directory is searched and
+module directory, then first the CMake builtin module directory is searched and
 :variable:`CMAKE_MODULE_PATH` afterwards.  See also policy :policy:`CMP0017`.
 
 See the :command:`cmake_policy` command documentation for discussion of the

Help/command/install.rst

@@ -314,7 +314,8 @@ Installing Exports
 ::
 
   install(EXPORT <export-name> DESTINATION <dir>
-          [NAMESPACE <namespace>] [FILE <name>.cmake]
+          [NAMESPACE <namespace>] [[FILE <name>.cmake]|
+          [EXPORT_ANDROID_MK <name>.mk]]
           [PERMISSIONS permissions...]
           [CONFIGURATIONS [Debug|Release|...]]
           [EXPORT_LINK_INTERFACE_LIBRARIES]
@@ -342,6 +343,13 @@ specified that does not match that given to the targets associated with
 included in the export but a target to which it links is not included
 the behavior is unspecified.
 
+In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe
+used to specifiy an export to the android ndk build system.  The Android
+NDK supports the use of prebuilt libraries, both static and shared. This
+allows cmake to build the libraries of a project and make them available
+to an ndk build system complete with transitive dependencies, include flags
+and defines required to use the libraries.
+
 The ``EXPORT`` form is useful to help outside projects use targets built
 and installed by the current project.  For example, the code
 
@@ -349,9 +357,11 @@ 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)
 
 will install the executable myexe to ``<prefix>/bin`` and code to import
-it in the file ``<prefix>/lib/myproj/myproj.cmake``.  An outside project
+it in the file ``<prefix>/lib/myproj/myproj.cmake`` and
+``<prefix>/lib/share/ndk-modules/Android.mk``.  An outside project
 may load this file with the include command and reference the ``myexe``
 executable from the installation tree using the imported target name
 ``mp_myexe`` as if the target were built in its own tree.

Help/command/math.rst

@@ -5,9 +5,10 @@ Mathematical expressions.
 
 ::
 
-  math(EXPR <output variable> <math expression>)
+  math(EXPR <output-variable> <math-expression>)
 
 ``EXPR`` evaluates mathematical expression and returns result in the
-output variable.  Example mathematical expression is '5 * ( 10 + 13
+output variable.  Example mathematical expression is ``5 * (10 + 13)``.
-)'.  Supported operators are + - * / % | & ^ ~ << >> * / %.  They have
+Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
-the same meaning as they do in C code.
+``^``, ``~``, ``<<``, ``>>``, and ``(...)``.  They have the same meaning
+as they do in C code.

Help/command/separate_arguments.rst

@@ -13,19 +13,21 @@ entire command line must be given in one "<args>" argument.
 
 The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace.  It
 recognizes both single-quote and double-quote pairs.  A backslash
-escapes the next literal character (\" is "); there are no special
+escapes the next literal character (``\"`` is ``"``); there are no special
-escapes (\n is just n).
+escapes (``\n`` is just ``n``).
 
 The ``WINDOWS_COMMAND`` mode parses a windows command-line 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.
+MSDN article `Parsing C Command-Line Arguments`_ for details.
+
+.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx
 
 ::
 
-  separate_arguments(VARIABLE)
+  separate_arguments(<var>)
 
-Convert the value of ``VARIABLE`` to a semi-colon separated list.  All
+Convert the value of ``<var>`` to a semi-colon separated list.  All
 spaces are replaced with ';'.  This helps with generating command
 lines.

Help/command/set.rst

@@ -25,7 +25,9 @@ If the ``PARENT_SCOPE`` option is given the variable will be set in
 the scope above the current scope.  Each new directory or function
 creates a new scope.  This command will set the value of a variable
 into the parent directory or calling function (whichever is applicable
-to the case at hand).
+to the case at hand). The previous state of the variable's value stays the
+same in the current scope (e.g., if it was undefined before, it is still
+undefined and if it had a value, it is still that value).
 
 Set Cache Entry
 ^^^^^^^^^^^^^^^

Help/command/string.rst

@@ -197,10 +197,12 @@ Comparison
 
 ::
 
-  string(COMPARE EQUAL <string1> <string2> <output variable>)
-  string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
   string(COMPARE LESS <string1> <string2> <output variable>)
   string(COMPARE GREATER <string1> <string2> <output variable>)
+  string(COMPARE EQUAL <string1> <string2> <output variable>)
+  string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
+  string(COMPARE LESS_EQUAL <string1> <string2> <output variable>)
+  string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>)
 
 Compare the strings and store true or false in the output variable.
 
@@ -276,12 +278,14 @@ specifiers:
    %I        The hour on a 12-hour clock (01-12).
    %j        The day of the current year (001-366).
    %m        The month of the current year (01-12).
+   %b        Abbreviated month name (e.g. Oct).
    %M        The minute of the current hour (00-59).
    %s        Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
    %S        The second of the current minute.
              60 represents a leap second. (00-60)
    %U        The week number of the current year (00-53).
    %w        The day of the current week. 0 is Sunday. (0-6)
+   %a        Abbreviated weekday name (e.g. Fri).
    %y        The last two digits of the current year (00-99)
    %Y        The current year.
 

Help/command/target_link_libraries.rst

@@ -62,6 +62,12 @@ Each ``<item>`` may be:
   dependencies, so they are generally safe to specify only as private link
   items that will not propagate to dependents.
 
+  Link flags specified here are inserted into the link command in the same
+  place as the link libraries. This might not be correct, depending on
+  the linker. Use the :prop_tgt:`LINK_FLAGS` target property to add link
+  flags explicitly. The flags will then be placed at the toolchain-defined
+  flag position in the link command.
+
 * A ``debug``, ``optimized``, or ``general`` keyword immediately followed
   by another ``<item>``.  The item following such a keyword will be used
   only for the corresponding build configuration.  The ``debug`` keyword

Help/generator/CodeLite.rst

@@ -5,7 +5,11 @@ Generates CodeLite project files.
 
 Project files for CodeLite will be created in the top directory and
 in every subdirectory which features a CMakeLists.txt file containing
-a PROJECT() call. The appropriate make program can build the
+a :command:`project` call.
+The :variable:`CMAKE_CODELITE_USE_TARGETS` variable may be set to ``ON``
+to change the default behaviour from projects to targets as the basis
+for project files.
+The appropriate make program can build the
 project through the default make target.  A "make install" target is
 also provided.
 

Help/generator/Ninja.rst

@@ -7,6 +7,27 @@ A build.ninja file is generated into the build tree.  Recent versions
 of the ninja program can build the project through the "all" target.
 An "install" target is also provided.
 
-For each subdirectory ``sub/dir`` of the project an additional target
+For each subdirectory ``sub/dir`` of the project, additional targets
-named ``sub/dir/all`` is generated that depends on all targets required
+are generated:
-by that subdirectory.
+
+``sub/dir/all``
+  Depends on all targets required by the subdirectory.
+
+``sub/dir/install``
+  Runs the install step in the subdirectory, if any.
+
+``sub/dir/test``
+  Runs the test step in the subdirectory, if any.
+
+``sub/dir/package``
+  Runs the package step in the subdirectory, if any.
+
+Fortran Support
+^^^^^^^^^^^^^^^
+
+The ``Ninja`` generator conditionally supports Fortran when the ``ninja``
+tool has the required features.  As of this version of CMake the needed
+features have not been integrated into upstream Ninja.  Kitware maintains
+a branch of Ninja with the required features on `github.com/Kitware/ninja`_.
+
+.. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme

Help/generator/Visual Studio 10 2010.rst

@@ -4,7 +4,7 @@ Visual Studio 10 2010
 Generates Visual Studio 10 (VS 2010) project files.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name.
+to specify a target platform name (architecture).
 
 For compatibility with CMake versions prior to 3.1, one may specify
 a target platform name optionally at the end of this generator name:

Help/generator/Visual Studio 11 2012.rst

@@ -4,7 +4,7 @@ Visual Studio 11 2012
 Generates Visual Studio 11 (VS 2012) project files.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name.
+to specify a target platform name (architecture).
 
 For compatibility with CMake versions prior to 3.1, one may specify
 a target platform name optionally at the end of this generator name:

Help/generator/Visual Studio 12 2013.rst

@@ -4,7 +4,7 @@ Visual Studio 12 2013
 Generates Visual Studio 12 (VS 2013) project files.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name.
+to specify a target platform name (architecture).
 
 For compatibility with CMake versions prior to 3.1, one may specify
 a target platform name optionally at the end of this generator name:

Help/generator/Visual Studio 14 2015.rst

@@ -4,7 +4,7 @@ Visual Studio 14 2015
 Generates Visual Studio 14 (VS 2015) project files.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
-to specify a target platform name.
+to specify a target platform name (architecture).
 
 For compatibility with CMake versions prior to 3.1, one may specify
 a target platform name optionally at the end of this generator name:

Help/generator/Visual Studio 15 2017.rst

@@ -0,0 +1,16 @@
+Visual Studio 15 2017
+---------------------
+
+Generates Visual Studio 15 (VS 2017) project files.
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set
+to specify a target platform name (architecture).
+
+For compatibility with CMake versions prior to 3.1, one may specify
+a target platform name optionally at the end of this generator name:
+
+``Visual Studio 15 2017 Win64``
+  Specify target platform ``x64``.
+
+``Visual Studio 15 2017 ARM``
+  Specify target platform ``ARM``.

Help/index.rst

@@ -32,6 +32,7 @@ Reference Manuals
    /manual/cmake-generator-expressions.7
    /manual/cmake-generators.7
    /manual/cmake-language.7
+   /manual/cmake-server.7
    /manual/cmake-modules.7
    /manual/cmake-packages.7
    /manual/cmake-policies.7

Help/manual/OPTIONS_BUILD.txt

@@ -66,10 +66,12 @@
  Specify platform name if supported by generator.
 
  Some CMake generators support a platform name to be given to the
- native build system to choose a compiler or SDK.  This is supported only on
+ native build system to choose a compiler or SDK.  See the
- specific generators::
+ :variable:`CMAKE_GENERATOR_PLATFORM` variable.
+ This is supported only on specific generators:
 
-   Visual Studio >= 8
+ * For :ref:`Visual Studio Generators` with VS 2005 and above this
+   specifies the target architecture.
 
  See native build system documentation for allowed platform names.
 

Help/manual/cmake-buildsystem.7.rst

@@ -860,7 +860,7 @@ with :prop_tgt:`IMPORTED` targets.
 Alias Targets
 -------------
 
-An ``ALIAS`` target is a name which may be used interchangably with
+An ``ALIAS`` target is a name which may be used interchangeably with
 a binary target name in read-only contexts.  A primary use-case for ``ALIAS``
 targets is for example or unit test executables accompanying a library, which
 may be part of the same buildsystem or built separately based on user

Help/manual/cmake-developer.7.rst

@@ -24,9 +24,10 @@ to build with such toolchains.
 std::auto_ptr
 -------------
 
-Some implementations have a ``std::auto_ptr`` which can not be used as a
+The ``std::auto_ptr`` template is deprecated in C++11.  We want to use it
-return value from a function. ``std::auto_ptr`` may not be used. Use
+so we can build on C++98 compilers but we do not want to turn off compiler
-``cmsys::auto_ptr`` instead.
+warnings about deprecated interfaces in general.  Use the ``CM_AUTO_PTR``
+macro instead.
 
 size_t
 ------
@@ -518,8 +519,16 @@ containing just the line::
 
 The ``cmake-module`` directive will scan the module file to extract
 reStructuredText markup from comment blocks that start in ``.rst:``.
-Add to the top of ``Modules/<module-name>.cmake`` a
+At the top of ``Modules/<module-name>.cmake``, begin with the following
-:ref:`Line Comment` block of the form:
+license notice:
+
+.. code-block:: cmake
+
+ # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+ # file Copyright.txt or https://cmake.org/licensing for details.
+
+After this notice, add a *BLANK* line.  Then, add documentation using
+a :ref:`Line Comment` block of the form:
 
 .. code-block:: cmake
 
@@ -551,6 +560,9 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
 
 .. code-block:: cmake
 
+ # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+ # file Copyright.txt or https://cmake.org/licensing for details.
+
  #.rst:
  # FindXxx
  # -------
@@ -578,25 +590,6 @@ For example, a ``Modules/Findxxx.cmake`` module may contain:
    <code>
  endmacro()
 
-After the top documentation block, leave a *BLANK* line, and then add a
-copyright and licence notice block like this one (change only the year
-range and name)
-
-.. code-block:: cmake
-
-  #=============================================================================
-  # Copyright 2009-2011 Your Name
-  #
-  # Distributed under the OSI-approved BSD License (the "License");
-  # see accompanying file Copyright.txt for details.
-  #
-  # This software is distributed WITHOUT ANY WARRANTY; without even the
-  # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-  # See the License for more information.
-  #=============================================================================
-  # (To distribute this file outside of CMake, substitute the full
-  #  License text for the above reference.)
-
 Test the documentation formatting by running
 ``cmake --help-module <module-name>``, and also by enabling the
 ``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation.
@@ -790,10 +783,17 @@ A Sample Find Module
 We will describe how to create a simple find module for a library
 ``Foo``.
 
-The first thing that is needed is documentation.  CMake's documentation
+The first thing that is needed is a license notice.
-system requires you to start the file with a documentation marker and
+
-the name of the module.  You should follow this with a simple statement
+.. code-block:: cmake
-of what the module does.
+
+ # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+ # file Copyright.txt or https://cmake.org/licensing for details.
+
+Next we need module documentation.  CMake's documentation system requires you
+to follow the license notice with a blank line and then with a documentation
+marker and the name of the module.  You should follow this with a simple
+statement of what the module does.
 
 .. code-block:: cmake
 
@@ -824,24 +824,6 @@ If the package provides any macros, they should be listed here, but can
 be documented where they are defined.  See the `Module
 Documentation`_ section above for more details.
 
-After the documentation, leave a blank line, and then add a copyright and
-licence notice block
-
-.. code-block:: cmake
-
-  #=============================================================================
-  # Copyright 2009-2011 Your Name
-  #
-  # Distributed under the OSI-approved BSD License (the "License");
-  # see accompanying file Copyright.txt for details.
-  #
-  # This software is distributed WITHOUT ANY WARRANTY; without even the
-  # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-  # See the License for more information.
-  #=============================================================================
-  # (To distribute this file outside of CMake, substitute the full
-  #  License text for the above reference.)
-
 Now the actual libraries and so on have to be found.  The code here will
 obviously vary from module to module (dealing with that, after all, is the
 point of find modules), but there tends to be a common pattern for libraries.

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

@@ -66,12 +66,16 @@ Available logical expressions are:
   ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``.
 ``$<CXX_COMPILER_ID:comp>``
   ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``.
-``$<VERSION_GREATER:v1,v2>``
-  ``1`` if ``v1`` is a version greater than ``v2``, else ``0``.
 ``$<VERSION_LESS:v1,v2>``
   ``1`` if ``v1`` is a version less than ``v2``, else ``0``.
+``$<VERSION_GREATER:v1,v2>``
+  ``1`` if ``v1`` is a version greater than ``v2``, else ``0``.
 ``$<VERSION_EQUAL:v1,v2>``
   ``1`` if ``v1`` is the same version as ``v2``, else ``0``.
+``$<VERSION_LESS_EQUAL:v1,v2>``
+  ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``.
+``$<VERSION_GREATER_EQUAL:v1,v2>``
+  ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``.
 ``$<C_COMPILER_VERSION:ver>``
   ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``.
 ``$<CXX_COMPILER_VERSION:ver>``

Help/manual/cmake-generators.7.rst

@@ -82,6 +82,7 @@ Visual Studio Generators
    /generator/Visual Studio 11 2012
    /generator/Visual Studio 12 2013
    /generator/Visual Studio 14 2015
+   /generator/Visual Studio 15 2017
 
 Other Generators
 ^^^^^^^^^^^^^^^^

Help/manual/cmake-modules.7.rst

@@ -14,6 +14,7 @@ All Modules
    :maxdepth: 1
 
    /module/AddFileDependencies
+   /module/AndroidTestUtilities
    /module/BundleUtilities
    /module/CheckCCompilerFlag
    /module/CheckCSourceCompiles
@@ -60,6 +61,7 @@ All Modules
    /module/CPackIFW
    /module/CPackNSIS
    /module/CPackPackageMaker
+   /module/CPackProductBuild
    /module/CPackRPM
    /module/CPack
    /module/CPackWIX
@@ -120,6 +122,7 @@ All Modules
    /module/FindHTMLHelp
    /module/FindIce
    /module/FindIcotool
+   /module/FindICU
    /module/FindImageMagick
    /module/FindIntl
    /module/FindITK
@@ -209,6 +212,7 @@ All Modules
    /module/FindTIFF
    /module/FindUnixCommands
    /module/FindVTK
+   /module/FindVulkan
    /module/FindWget
    /module/FindWish
    /module/FindwxWidgets

Help/manual/cmake-policies.7.rst

@@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.7
+================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0066: Honor per-config flags in try_compile() source-file signature. </policy/CMP0066>
+
 Policies Introduced by CMake 3.4
 ================================
 

Help/manual/cmake-properties.7.rst

@@ -24,6 +24,7 @@ Properties of Global Scope
    /prop_gbl/DISABLED_FEATURES
    /prop_gbl/ENABLED_FEATURES
    /prop_gbl/ENABLED_LANGUAGES
+   /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS
    /prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS
    /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING
    /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE
@@ -53,6 +54,8 @@ Properties on Directories
    :maxdepth: 1
 
    /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES
+   /prop_dir/BINARY_DIR
+   /prop_dir/BUILDSYSTEM_TARGETS
    /prop_dir/CACHE_VARIABLES
    /prop_dir/CLEAN_NO_CUSTOM
    /prop_dir/CMAKE_CONFIGURE_DEPENDS
@@ -72,6 +75,8 @@ Properties on Directories
    /prop_dir/RULE_LAUNCH_COMPILE
    /prop_dir/RULE_LAUNCH_CUSTOM
    /prop_dir/RULE_LAUNCH_LINK
+   /prop_dir/SOURCE_DIR
+   /prop_dir/SUBDIRECTORIES
    /prop_dir/TEST_INCLUDE_FILE
    /prop_dir/VARIABLES
    /prop_dir/VS_GLOBAL_SECTION_POST_section
@@ -217,6 +222,7 @@ Properties on Targets
    /prop_tgt/LINK_LIBRARIES
    /prop_tgt/LINK_SEARCH_END_STATIC
    /prop_tgt/LINK_SEARCH_START_STATIC
+   /prop_tgt/LINK_WHAT_YOU_USE
    /prop_tgt/LOCATION_CONFIG
    /prop_tgt/LOCATION
    /prop_tgt/MACOSX_BUNDLE_INFO_PLIST
@@ -274,6 +280,7 @@ Properties on Targets
    /prop_tgt/VS_SCC_LOCALPATH
    /prop_tgt/VS_SCC_PROJECTNAME
    /prop_tgt/VS_SCC_PROVIDER
+   /prop_tgt/VS_SDK_REFERENCES
    /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
    /prop_tgt/VS_WINRT_COMPONENT
    /prop_tgt/VS_WINRT_EXTENSIONS
@@ -297,6 +304,9 @@ Properties on Tests
    /prop_test/DEPENDS
    /prop_test/ENVIRONMENT
    /prop_test/FAIL_REGULAR_EXPRESSION
+   /prop_test/FIXTURES_CLEANUP
+   /prop_test/FIXTURES_REQUIRED
+   /prop_test/FIXTURES_SETUP
    /prop_test/LABELS
    /prop_test/MEASUREMENT
    /prop_test/PASS_REGULAR_EXPRESSION
@@ -341,9 +351,11 @@ Properties on Source Files
    /prop_sf/VS_SHADER_FLAGS
    /prop_sf/VS_SHADER_MODEL
    /prop_sf/VS_SHADER_TYPE
+   /prop_sf/VS_TOOL_OVERRIDE.rst
    /prop_sf/VS_XAML_TYPE
    /prop_sf/WRAP_EXCLUDE
    /prop_sf/XCODE_EXPLICIT_FILE_TYPE
+   /prop_sf/XCODE_FILE_ATTRIBUTES
    /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE
 
 .. _`Cache Entry Properties`:

Help/manual/cmake-qt.7.rst

@@ -29,7 +29,7 @@ Qt 4 and Qt 5 may be used together in the same
   set(CMAKE_AUTOMOC ON)
   set(CMAKE_INCLUDE_CURRENT_DIR ON)
 
-  find_package(Qt5Widgets REQUIRED)
+  find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
   add_executable(publisher publisher.cpp)
   target_link_libraries(publisher Qt5::Widgets Qt5::DBus)
 

Help/manual/cmake-server.7.rst

@@ -0,0 +1,672 @@
+.. cmake-manual-description: CMake Server
+
+cmake-server(7)
+***************
+
+.. only:: html
+
+   .. contents::
+
+Introduction
+============
+
+:manual:`cmake(1)` is capable of providing semantic information about
+CMake code it executes to generate a buildsystem.  If executed with
+the ``-E server`` command line options, it starts in a long running mode
+and allows a client to request the available information via a JSON protocol.
+
+The protocol is designed to be useful to IDEs, refactoring tools, and
+other tools which have a need to understand the buildsystem in entirety.
+
+A single :manual:`cmake-buildsystem(7)` may describe buildsystem contents
+and build properties which differ based on
+:manual:`generation-time context <cmake-generator-expressions(7)>`
+including:
+
+* The Platform (eg, Windows, APPLE, Linux).
+* The build configuration (eg, Debug, Release, Coverage).
+* The Compiler (eg, MSVC, GCC, Clang) and compiler version.
+* The language of the source files compiled.
+* Available compile features (eg CXX variadic templates).
+* CMake policies.
+
+The protocol aims to provide information to tooling to satisfy several
+needs:
+
+#. Provide a complete and easily parsed source of all information relevant
+   to the tooling as it relates to the source code.  There should be no need
+   for tooling to parse generated buildsystems to access include directories
+   or compile definitions for example.
+#. Semantic information about the CMake buildsystem itself.
+#. Provide a stable interface for reading the information in the CMake cache.
+#. Information for determining when cmake needs to be re-run as a result of
+   file changes.
+
+
+Operation
+=========
+
+Start :manual:`cmake(1)` in the server command mode, supplying the path to
+the build directory to process::
+
+  cmake -E server (--debug|--pipe <NAMED_PIPE>)
+
+The server will communicate using stdin/stdout (with the ``--debug`` parameter)
+or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter).
+
+When connecting to the server (via named pipe or by starting it in ``--debug``
+mode), the server will reply with a hello message::
+
+  [== "CMake Server" ==[
+  {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
+  ]== "CMake Server" ==]
+
+Messages sent to and from the process are wrapped in magic strings::
+
+  [== "CMake Server" ==[
+  {
+    ... some JSON message ...
+  }
+  ]== "CMake Server" ==]
+
+The server is now ready to accept further requests via the named pipe
+or stdin.
+
+
+Debugging
+=========
+
+CMake server mode can be asked to provide statistics on execution times, etc.
+or to dump a copy of the response into a file. This is done passing a "debug"
+JSON object as a child of the request.
+
+The debug object supports the "showStats" key, which takes a boolean and makes
+the server mode return a "zzzDebug" object with stats as part of its response.
+"dumpToFile" takes a string value and will cause the cmake server to copy
+the response into the given filename.
+
+This is a response from the cmake server with "showStats" set to true::
+
+  [== "CMake Server" ==[
+  {
+    "cookie":"",
+    "errorMessage":"Waiting for type \"handshake\".",
+    "inReplyTo":"unknown",
+   "type":"error",
+    "zzzDebug": {
+      "dumpFile":"/tmp/error.txt",
+      "jsonSerialization":0.011016,
+      "size":111,
+      "totalTime":0.025995
+    }
+  }
+  ]== "CMake Server" ==]
+
+The server has made a copy of this response into the file /tmp/error.txt and
+took 0.011 seconds to turn the JSON response into a string, and it took 0.025
+seconds to process the request in total. The reply has a size of 111 bytes.
+
+
+Protocol API
+============
+
+
+General Message Layout
+----------------------
+
+All messages need to have a "type" value, which identifies the type of
+message that is passed back or forth. E.g. the initial message sent by the
+server is of type "hello". Messages without a type will generate an response
+of type "error".
+
+All requests sent to the server may contain a "cookie" value. This value
+will he handed back unchanged in all responses triggered by the request.
+
+All responses will contain a value "inReplyTo", which may be empty in
+case of parse errors, but will contain the type of the request message
+in all other cases.
+
+
+Type "reply"
+^^^^^^^^^^^^
+
+This type is used by the server to reply to requests.
+
+The message may -- depending on the type of the original request --
+contain values.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
+  ]== "CMake Server" ==]
+
+
+Type "error"
+^^^^^^^^^^^^
+
+This type is used to return an error condition to the client. It will
+contain an "errorMessage".
+
+Example::
+
+  [== "CMake Server" ==[
+  {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
+  ]== "CMake Server" ==]
+
+
+Type "progress"
+^^^^^^^^^^^^^^^
+
+When the server is busy for a long time, it is polite to send back replies of
+type "progress" to the client. These will contain a "progressMessage" with a
+string describing the action currently taking place as well as
+"progressMinimum", "progressMaximum" and "progressCurrent" with integer values
+describing the range of progess.
+
+Messages of type "progress" will be followed by more "progress" messages or with
+a message of type "reply" or "error" that complete the request.
+
+"progress" messages may not be emitted after the "reply" or "error" message for
+the request that triggered the responses was delivered.
+
+
+Type "message"
+^^^^^^^^^^^^^^
+
+A message is triggered when the server processes a request and produces some
+form of output that should be displayed to the user. A Message has a "message"
+with the actual text to display as well as a "title" with a suggested dialog
+box title.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
+  ]== "CMake Server" ==]
+
+
+Type "signal"
+^^^^^^^^^^^^^
+
+The server can send signals when it detects changes in the system state. Signals
+are of type "signal", have an empty "cookie" and "inReplyTo" field and always
+have a "name" set to show which signal was sent.
+
+
+Specific Signals
+----------------
+
+The cmake server may sent signals with the following names:
+
+"dirty" Signal
+^^^^^^^^^^^^^^
+
+The "dirty" signal is sent whenever the server determines that the configuration
+of the project is no longer up-to-date. This happens when any of the files that have
+an influence on the build system is changed.
+
+The "dirty" signal may look like this::
+
+  [== "CMake Server" ==[
+  {
+    "cookie":"",
+    "inReplyTo":"",
+    "name":"dirty",
+    "type":"signal"}
+  ]== "CMake Server" ==]
+
+
+"fileChange" Signal
+^^^^^^^^^^^^^^^^^^^
+
+The "fileChange" signal is sent whenever a watched file is changed. It contains
+the "path" that has changed and a list of "properties" with the kind of change
+that was detected. Possible changes are "change" and "rename".
+
+The "fileChange" signal looks like this::
+
+  [== "CMake Server" ==[
+  {
+    "cookie":"",
+    "inReplyTo":"",
+    "name":"fileChange",
+    "path":"/absolute/CMakeLists.txt",
+    "properties":["change"],
+    "type":"signal"}
+  ]== "CMake Server" ==]
+
+
+Specific Message Types
+----------------------
+
+
+Type "hello"
+^^^^^^^^^^^^
+
+The initial message send by the cmake server on startup is of type "hello".
+This is the only message ever sent by the server that is not of type "reply",
+"progress" or "error".
+
+It will contain "supportedProtocolVersions" with an array of server protocol
+versions supported by the cmake server. These are JSON objects with "major" and
+"minor" keys containing non-negative integer values. Some versions may be marked
+as experimental. These will contain the "isExperimental" key set to true. Enabling
+these requires a special command line argument when starting the cmake server mode.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
+  ]== "CMake Server" ==]
+
+
+Type "handshake"
+^^^^^^^^^^^^^^^^
+
+The first request that the client may send to the server is of type "handshake".
+
+This request needs to pass one of the "supportedProtocolVersions" of the "hello"
+type response received earlier back to the server in the "protocolVersion" field.
+
+Each protocol version may request additional attributes to be present.
+
+Protocol version 1.0 requires the following attributes to be set:
+
+  * "sourceDirectory" with a path to the sources
+  * "buildDirectory" with a path to the build directory
+  * "generator" with the generator name
+  * "extraGenerator" (optional!) with the extra generator to be used
+  * "platform" with the generator platform (if supported by the generator)
+  * "toolset" with the generator toolset (if supported by the generator)
+
+Example::
+
+  [== "CMake Server" ==[
+  {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
+   "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
+   "generator":"Ninja"}
+  ]== "CMake Server" ==]
+
+which will result in a response type "reply"::
+
+  [== "CMake Server" ==[
+  {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
+  ]== "CMake Server" ==]
+
+indicating that the server is ready for action.
+
+
+Type "globalSettings"
+^^^^^^^^^^^^^^^^^^^^^
+
+This request can be sent after the initial handshake. It will return a
+JSON structure with information on cmake state.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"globalSettings"}
+  ]== "CMake Server" ==]
+
+which will result in a response type "reply"::
+
+  [== "CMake Server" ==[
+  {
+    "buildDirectory": "/tmp/test-build",
+    "capabilities": {
+      "generators": [
+        {
+          "extraGenerators": [],
+          "name": "Watcom WMake",
+          "platformSupport": false,
+          "toolsetSupport": false
+        },
+        <...>
+      ],
+      "serverMode": false,
+      "version": {
+        "isDirty": false,
+        "major": 3,
+        "minor": 6,
+        "patch": 20160830,
+        "string": "3.6.20160830-gd6abad",
+        "suffix": "gd6abad"
+      }
+    },
+    "checkSystemVars": false,
+    "cookie": "",
+    "extraGenerator": "",
+    "generator": "Ninja",
+    "debugOutput": false,
+    "inReplyTo": "globalSettings",
+    "sourceDirectory": "/home/code/cmake",
+    "trace": false,
+    "traceExpand": false,
+    "type": "reply",
+    "warnUninitialized": false,
+    "warnUnused": false,
+    "warnUnusedCli": true
+  }
+  ]== "CMake Server" ==]
+
+
+Type "setGlobalSettings"
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This request can be sent to change the global settings attributes. Unknown
+attributes are going to be ignored. Read-only attributes reported by
+"globalSettings" are all capabilities, buildDirectory, generator,
+extraGenerator and sourceDirectory. Any attempt to set these will be ignored,
+too.
+
+All other settings will be changed.
+
+The server will respond with an empty reply message or an error.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"setGlobalSettings","debugOutput":true}
+  ]== "CMake Server" ==]
+
+CMake will reply to this with::
+
+  [== "CMake Server" ==[
+  {"inReplyTo":"setGlobalSettings","type":"reply"}
+  ]== "CMake Server" ==]
+
+
+Type "configure"
+^^^^^^^^^^^^^^^^
+
+This request will configure a project for build.
+
+To configure a build directory already containing cmake files, it is enough to
+set "buildDirectory" via "setGlobalSettings". To create a fresh build directory
+you also need to set "currentGenerator" and "sourceDirectory" via "setGlobalSettings"
+in addition to "buildDirectory".
+
+You may a list of strings to "configure" via the "cacheArguments" key. These
+strings will be interpreted similar to command line arguments related to
+cache handling that are passed to the cmake command line client.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"configure", "cacheArguments":["-Dsomething=else"]}
+  ]== "CMake Server" ==]
+
+CMake will reply like this (after reporting progress for some time)::
+
+  [== "CMake Server" ==[
+  {"cookie":"","inReplyTo":"configure","type":"reply"}
+  ]== "CMake Server" ==]
+
+
+Type "compute"
+^^^^^^^^^^^^^^
+
+This request will generate build system files in the build directory and
+is only available after a project was successfully "configure"d.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"compute"}
+  ]== "CMake Server" ==]
+
+CMake will reply (after reporting progress information)::
+
+  [== "CMake Server" ==[
+  {"cookie":"","inReplyTo":"compute","type":"reply"}
+  ]== "CMake Server" ==]
+
+
+Type "codemodel"
+^^^^^^^^^^^^^^^^
+
+The "codemodel" request can be used after a project was "compute"d successfully.
+
+It will list the complete project structure as it is known to cmake.
+
+The reply will contain a key "configurations", which will contain a list of
+configuration objects. Configuration objects are used to destinquish between
+different configurations the build directory might have enabled. While most
+generators only support one configuration, others might support several.
+
+Each configuration object can have the following keys:
+
+"name"
+  contains the name of the configuration. The name may be empty.
+"projects"
+  contains a list of project objects, one for each build project.
+
+Project objects define one (sub-)project defined in the cmake build system.
+
+Each project object can have the following keys:
+
+"name"
+  contains the (sub-)projects name.
+"sourceDirectory"
+  contains the current source directory
+"buildDirectory"
+  contains the current build directory.
+"targets"
+  contains a list of build system target objects.
+
+Target objects define individual build targets for a certain configuration.
+
+Each target object can have the following keys:
+
+"name"
+  contains the name of the target.
+"type"
+  defines the type of build of the target. Possible values are
+  "STATIC_LIBRARY", "MODULE_LIBRARY", "SHARED_LIBRARY", "OBJECT_LIBRARY",
+  "EXECUTABLE", "UTILITY" and "INTERFACE_LIBRARY".
+"fullName"
+  contains the full name of the build result (incl. extensions, etc.).
+"sourceDirectory"
+  contains the current source directory.
+"buildDirectory"
+  contains the current build directory.
+"artifacts"
+  with a list of build artifacts. The list is sorted with the most
+  important artifacts first (e.g. a .DLL file is listed before a
+  .PDB file on windows).
+"linkerLanguage"
+  contains the language of the linker used to produce the artifact.
+"linkLibraries"
+  with a list of libraries to link to. This value is encoded in the
+  system's native shell format.
+"linkFlags"
+  with a list of flags to pass to the linker. This value is encoded in
+  the system's native shell format.
+"linkLanguageFlags"
+  with the flags for a compiler using the linkerLanguage. This value is
+  encoded in the system's native shell format.
+"frameworkPath"
+  with the framework path (on Apple computers). This value is encoded
+  in the system's native shell format.
+"linkPath"
+  with the link path. This value is encoded in the system's native shell
+  format.
+"sysroot"
+  with the sysroot path.
+"fileGroups"
+  contains the source files making up the target.
+
+FileGroups are used to group sources using similar settings together.
+
+Each fileGroup object may contain the following keys:
+
+"language"
+  contains the programming language used by all files in the group.
+"compileFlags"
+  with a string containing all the flags passed to the compiler
+  when building any of the files in this group. This value is encoded in
+  the system's native shell format.
+"includePath"
+  with a list of include paths. Each include path is an object
+  containing a "path" with the actual include path and "isSystem" with a bool
+  value informing whether this is a normal include or a system include. This
+  value is encoded in the system's native shell format.
+"defines"
+  with a list of defines in the form "SOMEVALUE" or "SOMEVALUE=42". This
+  value is encoded in the system's native shell format.
+"sources"
+  with a list of source files.
+
+All file paths in the fileGroup are either absolute or relative to the
+sourceDirectory of the target.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"codemodel"}
+  ]== "CMake Server" ==]
+
+CMake will reply::
+
+  [== "CMake Server" ==[
+  {
+    "configurations": [
+      {
+        "name": "",
+        "projects": [
+          {
+            "buildDirectory": "/tmp/build/Source/CursesDialog/form",
+            "name": "CMAKE_FORM",
+            "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
+            "targets": [
+              {
+                "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
+                "buildDirectory": "/tmp/build/Source/CursesDialog/form",
+                "fileGroups": [
+                  {
+                    "compileFlags": "  -std=gnu11",
+                    "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
+                    "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
+                    "isGenerated": false,
+                    "language": "C",
+                    "sources": [ "fld_arg.c", <...> ]
+                  }
+                ],
+                "fullName": "libcmForm.a",
+                "linkerLanguage": "C",
+                "name": "cmForm",
+                "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
+                "type": "STATIC_LIBRARY"
+              }
+            ]
+          },
+          <...>
+        ]
+      }
+    ],
+    "cookie": "",
+    "inReplyTo": "codemodel",
+    "type": "reply"
+  }
+  ]== "CMake Server" ==]
+
+
+Type "cmakeInputs"
+^^^^^^^^^^^^^^^^^^
+
+The "cmakeInputs" requests will report files used by CMake as part
+of the build system itself.
+
+This request is only available after a project was successfully
+"configure"d.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"cmakeInputs"}
+  ]== "CMake Server" ==]
+
+CMake will reply with the following information::
+
+  [== "CMake Server" ==[
+  {"buildFiles":
+    [
+      {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
+      {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
+      {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
+    ],
+    "cmakeRootDirectory":"/usr/lib/cmake",
+    "sourceDirectory":"/home/code/src/cmake",
+    "cookie":"",
+    "inReplyTo":"cmakeInputs",
+    "type":"reply"
+  }
+  ]== "CMake Server" ==]
+
+All file names are either relative to the top level source directory or
+absolute.
+
+The list of files which "isCMake" set to true are part of the cmake installation.
+
+The list of files witch "isTemporary" set to true are part of the build directory
+and will not survive the build directory getting cleaned out.
+
+
+Type "cache"
+^^^^^^^^^^^^
+
+The "cache" request can be used once a project is configured and will
+list the cached configuration values.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"cache"}
+  ]== "CMake Server" ==]
+
+CMake will respond with the following output::
+
+  [== "CMake Server" ==[
+  {
+    "cookie":"","inReplyTo":"cache","type":"reply",
+    "cache":
+    [
+      {
+        "key":"SOMEVALUE",
+        "properties":
+        {
+          "ADVANCED":"1",
+          "HELPSTRING":"This is not helpful"
+        }
+        "type":"STRING",
+        "value":"TEST"}
+    ]
+  }
+  ]== "CMake Server" ==]
+
+The output can be limited to a list of keys by passing an array of key names
+to the "keys" optional field of the "cache" request.
+
+
+Type "fileSystemWatchers"
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The server can watch the filesystem for changes. The "fileSystemWatchers"
+command will report on the files and directories watched.
+
+Example::
+
+  [== "CMake Server" ==[
+  {"type":"fileSystemWatchers"}
+  ]== "CMake Server" ==]
+
+CMake will respond with the following output::
+
+  [== "CMake Server" ==[
+  {
+    "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
+    "watchedFiles": [ "/absolute/path" ],
+    "watchedDirectories": [ "/absolute" ]
+  }
+  ]== "CMake Server" ==]

Help/manual/cmake-toolchains.7.rst

@@ -290,12 +290,206 @@ Windows Store may look like this:
   set(CMAKE_SYSTEM_NAME WindowsStore)
   set(CMAKE_SYSTEM_VERSION 8.1)
 
-Cross Compiling using NVIDIA Nsight Tegra
+.. _`Cross Compiling for Android`:
------------------------------------------
 
-A toolchain file to configure a Visual Studio generator to
+Cross Compiling for Android
-build using NVIDIA Nsight Tegra targeting Android may look
+---------------------------
-like this:
+
+A toolchain file may configure cross-compiling for Android by setting the
+:variable:`CMAKE_SYSTEM_NAME` variable to ``Android``.  Further configuration
+is specific to the Android development environment to be used.
+
+For :ref:`Visual Studio Generators`, CMake expects :ref:`NVIDIA Nsight Tegra
+Visual Studio Edition <Cross Compiling for Android with NVIDIA Nsight Tegra
+Visual Studio Edition>` to be installed.  See that section for further
+configuration details.
+
+For :ref:`Makefile Generators` and the :generator:`Ninja` generator,
+CMake expects one of these environments:
+
+* :ref:`NDK <Cross Compiling for Android with the NDK>`
+* :ref:`Standalone Toolchain <Cross Compiling for Android with a Standalone Toolchain>`
+
+CMake uses the following steps to select one of the environments:
+
+* If the :variable:`CMAKE_ANDROID_NDK` variable is set, the NDK at the
+  specified location will be used.
+
+* Else, if the :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` variable
+  is set, the Standalone Toolchain at the specified location will be used.
+
+* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory
+  of the form ``<ndk>/platforms/android-<api>/arch-<arch>``, the ``<ndk>``
+  part will be used as the value of :variable:`CMAKE_ANDROID_NDK` and the
+  NDK will be used.
+
+* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory of the
+  form ``<standalone-toolchain>/sysroot``, the ``<standalone-toolchain>`` part
+  will be used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`
+  and the Standalone Toolchain will be used.
+
+* Else, if a cmake variable ``ANDROID_NDK`` is set it will be used
+  as the value of :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used.
+
+* Else, if a cmake variable ``ANDROID_STANDALONE_TOOLCHAIN`` is set, it will be
+  used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the
+  Standalone Toolchain will be used.
+
+* Else, if an environment variable ``ANDROID_NDK_ROOT`` or
+  ``ANDROID_NDK`` is set, it will be used as the value of
+  :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used.
+
+* Else, if an environment variable ``ANDROID_STANDALONE_TOOLCHAIN`` is
+  set then it will be used as the value of
+  :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the Standalone
+  Toolchain will be used.
+
+* Else, an error diagnostic will be issued that neither the NDK or
+  Standalone Toolchain can be found.
+
+.. _`Cross Compiling for Android with the NDK`:
+
+Cross Compiling for Android with the NDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A toolchain file may configure :ref:`Makefile Generators` or the
+:generator:`Ninja` generator to target Android for cross-compiling.
+
+Configure use of an Android NDK with the following variables:
+
+:variable:`CMAKE_SYSTEM_NAME`
+  Set to ``Android``.  Must be specified to enable cross compiling
+  for Android.
+
+:variable:`CMAKE_SYSTEM_VERSION`
+  Set to the Android API level.  If not specified, the value is
+  determined as follows:
+
+  * If the :variable:`CMAKE_ANDROID_API` variable is set, its value
+    is used as the API level.
+  * If the :variable:`CMAKE_SYSROOT` variable is set, the API level is
+    detected from the NDK directory structure containing the sysroot.
+  * Otherwise, the latest API level available in the NDK is used.
+
+:variable:`CMAKE_ANDROID_ARCH_ABI`
+  Set to the Android ABI (architecture).  If not specified, this
+  variable will default to ``armeabi``.
+  The :variable:`CMAKE_ANDROID_ARCH` variable will be computed
+  from ``CMAKE_ANDROID_ARCH_ABI`` automatically.
+  Also see the :variable:`CMAKE_ANDROID_ARM_MODE` and
+  :variable:`CMAKE_ANDROID_ARM_NEON` variables.
+
+:variable:`CMAKE_ANDROID_NDK`
+  Set to the absolute path to the Android NDK root directory.
+  A ``${CMAKE_ANDROID_NDK}/platforms`` directory must exist.
+  If not specified, a default for this variable will be chosen
+  as specified :ref:`above <Cross Compiling for Android>`.
+
+:variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION`
+  Set to the version of the NDK toolchain to be selected as the compiler.
+  If not specified, the default will be the latest available GCC toolchain.
+
+:variable:`CMAKE_ANDROID_STL_TYPE`
+  Set to specify which C++ standard library to use.  If not specified,
+  a default will be selected as described in the variable documentation.
+
+The following variables will be computed and provided automatically:
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX`
+  The absolute path prefix to the binutils in the NDK toolchain.
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`
+  The host platform suffix of the binutils in the NDK toolchain.
+
+
+For example, a toolchain file might contain:
+
+.. code-block:: cmake
+
+  set(CMAKE_SYSTEM_NAME Android)
+  set(CMAKE_SYSTEM_VERSION 21) # API level
+  set(CMAKE_ANDROID_ARCH_ABI arm64-v8a)
+  set(CMAKE_ANDROID_NDK /path/to/android-ndk)
+  set(CMAKE_ANDROID_STL_TYPE gnustl_static)
+
+Alternatively one may specify the values without a toolchain file:
+
+.. code-block:: console
+
+  $ cmake ../src \
+    -DCMAKE_SYSTEM_NAME=Android \
+    -DCMAKE_SYSTEM_VERSION=21 \
+    -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
+    -DCMAKE_ANDROID_NDK=/path/to/android-ndk \
+    -DCMAKE_ANDROID_STL_TYPE=gnustl_static
+
+.. _`Cross Compiling for Android with a Standalone Toolchain`:
+
+Cross Compiling for Android with a Standalone Toolchain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A toolchain file may configure :ref:`Makefile Generators` or the
+:generator:`Ninja` generator to target Android for cross-compiling
+using a standalone toolchain.
+
+Configure use of an Android standalone toolchain with the following variables:
+
+:variable:`CMAKE_SYSTEM_NAME`
+  Set to ``Android``.  Must be specified to enable cross compiling
+  for Android.
+
+:variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`
+  Set to the absolute path to the standalone toolchain root directory.
+  A ``${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot`` directory
+  must exist.
+  If not specified, a default for this variable will be chosen
+  as specified :ref:`above <Cross Compiling for Android>`.
+
+:variable:`CMAKE_ANDROID_ARM_MODE`
+  When the standalone toolchain targets ARM, optionally set this to ``ON``
+  to target 32-bit ARM instead of 16-bit Thumb.
+  See variable documentation for details.
+
+:variable:`CMAKE_ANDROID_ARM_NEON`
+  When the standalone toolchain targets ARM v7, optionally set thisto ``ON``
+  to target ARM NEON devices.  See variable documentation for details.
+
+The following variables will be computed and provided automatically:
+
+:variable:`CMAKE_SYSTEM_VERSION`
+  The Android API level detected from the standalone toolchain.
+
+:variable:`CMAKE_ANDROID_ARCH_ABI`
+  The Android ABI detected from the standalone toolchain.
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX`
+  The absolute path prefix to the binutils in the standalone toolchain.
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`
+  The host platform suffix of the binutils in the standalone toolchain.
+
+For example, a toolchain file might contain:
+
+.. code-block:: cmake
+
+  set(CMAKE_SYSTEM_NAME Android)
+  set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)
+
+Alternatively one may specify the values without a toolchain file:
+
+.. code-block:: console
+
+  $ cmake ../src \
+    -DCMAKE_SYSTEM_NAME=Android \
+    -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain
+
+.. _`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition`:
+
+Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A toolchain file to configure one of the :ref:`Visual Studio Generators`
+to build using NVIDIA Nsight Tegra targeting Android may look like this:
 
 .. code-block:: cmake
 

Help/manual/cmake-variables.7.rst

@@ -38,6 +38,8 @@ Variables that Provide Information
    /variable/CMAKE_EXTRA_GENERATOR
    /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
    /variable/CMAKE_FIND_PACKAGE_NAME
+   /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION
+   /variable/CMAKE_FIND_PACKAGE_SORT_ORDER
    /variable/CMAKE_GENERATOR
    /variable/CMAKE_GENERATOR_PLATFORM
    /variable/CMAKE_GENERATOR_TOOLSET
@@ -110,6 +112,7 @@ Variables that Change Behavior
    /variable/CMAKE_AUTOMOC_RELAXED_MODE
    /variable/CMAKE_BACKWARDS_COMPATIBILITY
    /variable/CMAKE_BUILD_TYPE
+   /variable/CMAKE_CODELITE_USE_TARGETS
    /variable/CMAKE_COLOR_MAKEFILE
    /variable/CMAKE_CONFIGURATION_TYPES
    /variable/CMAKE_DEBUG_TARGET_PROPERTIES
@@ -145,6 +148,7 @@ Variables that Change Behavior
    /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
    /variable/CMAKE_INSTALL_MESSAGE
    /variable/CMAKE_INSTALL_PREFIX
+   /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
    /variable/CMAKE_LIBRARY_PATH
    /variable/CMAKE_MFC_FLAG
    /variable/CMAKE_MODULE_PATH
@@ -173,6 +177,7 @@ Variables that Describe the System
 .. toctree::
    :maxdepth: 1
 
+   /variable/ANDROID
    /variable/APPLE
    /variable/BORLAND
    /variable/CMAKE_CL_64
@@ -213,6 +218,7 @@ Variables that Describe the System
    /variable/WINCE
    /variable/WINDOWS_PHONE
    /variable/WINDOWS_STORE
+   /variable/XCODE
    /variable/XCODE_VERSION
 
 Variables that Control the Build
@@ -225,6 +231,9 @@ Variables that Control the Build
    /variable/CMAKE_ANDROID_API
    /variable/CMAKE_ANDROID_API_MIN
    /variable/CMAKE_ANDROID_ARCH
+   /variable/CMAKE_ANDROID_ARCH_ABI
+   /variable/CMAKE_ANDROID_ARM_MODE
+   /variable/CMAKE_ANDROID_ARM_NEON
    /variable/CMAKE_ANDROID_ASSETS_DIRECTORIES
    /variable/CMAKE_ANDROID_GUI
    /variable/CMAKE_ANDROID_JAR_DEPENDENCIES
@@ -232,11 +241,15 @@ Variables that Control the Build
    /variable/CMAKE_ANDROID_JAVA_SOURCE_DIR
    /variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
    /variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
+   /variable/CMAKE_ANDROID_NDK
+   /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
+   /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
    /variable/CMAKE_ANDROID_PROCESS_MAX
    /variable/CMAKE_ANDROID_PROGUARD
    /variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH
    /variable/CMAKE_ANDROID_SECURE_PROPS_PATH
    /variable/CMAKE_ANDROID_SKIP_ANT_STEP
+   /variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN
    /variable/CMAKE_ANDROID_STL_TYPE
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
@@ -253,7 +266,9 @@ Variables that Control the Build
    /variable/CMAKE_DEBUG_POSTFIX
    /variable/CMAKE_ENABLE_EXPORTS
    /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_EXE_LINKER_FLAGS
+   /variable/CMAKE_EXE_LINKER_FLAGS_INIT
    /variable/CMAKE_Fortran_FORMAT
    /variable/CMAKE_Fortran_MODULE_DIRECTORY
    /variable/CMAKE_GNUtoMS
@@ -275,11 +290,14 @@ Variables that Control the Build
    /variable/CMAKE_LINK_INTERFACE_LIBRARIES
    /variable/CMAKE_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LINK_LIBRARY_FLAG
+   /variable/CMAKE_LINK_WHAT_YOU_USE
    /variable/CMAKE_MACOSX_BUNDLE
    /variable/CMAKE_MACOSX_RPATH
    /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG
    /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_MODULE_LINKER_FLAGS
+   /variable/CMAKE_MODULE_LINKER_FLAGS_INIT
    /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
    /variable/CMAKE_NO_BUILTIN_CHRPATH
    /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED
@@ -292,11 +310,15 @@ Variables that Control the Build
    /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
    /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
    /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_SHARED_LINKER_FLAGS
+   /variable/CMAKE_SHARED_LINKER_FLAGS_INIT
    /variable/CMAKE_SKIP_BUILD_RPATH
    /variable/CMAKE_SKIP_INSTALL_RPATH
    /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG
+   /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_STATIC_LINKER_FLAGS
+   /variable/CMAKE_STATIC_LINKER_FLAGS_INIT
    /variable/CMAKE_TRY_COMPILE_CONFIGURATION
    /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
    /variable/CMAKE_TRY_COMPILE_TARGET_TYPE
@@ -315,7 +337,9 @@ Variables for Languages
 .. toctree::
    :maxdepth: 1
 
-   /variable/CMAKE_COMPILER_IS_GNULANG
+   /variable/CMAKE_COMPILER_IS_GNUCC
+   /variable/CMAKE_COMPILER_IS_GNUCXX
+   /variable/CMAKE_COMPILER_IS_GNUG77
    /variable/CMAKE_C_COMPILE_FEATURES
    /variable/CMAKE_C_EXTENSIONS
    /variable/CMAKE_C_STANDARD
@@ -328,6 +352,9 @@ Variables for Languages
    /variable/CMAKE_Fortran_MODDIR_FLAG
    /variable/CMAKE_Fortran_MODOUT_FLAG
    /variable/CMAKE_INTERNAL_PLATFORM_ABI
+   /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE
+   /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX
+   /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX
    /variable/CMAKE_LANG_ARCHIVE_APPEND
    /variable/CMAKE_LANG_ARCHIVE_CREATE
    /variable/CMAKE_LANG_ARCHIVE_FINISH
@@ -343,10 +370,15 @@ Variables for Languages
    /variable/CMAKE_LANG_CREATE_SHARED_MODULE
    /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY
    /variable/CMAKE_LANG_FLAGS_DEBUG
+   /variable/CMAKE_LANG_FLAGS_DEBUG_INIT
    /variable/CMAKE_LANG_FLAGS_MINSIZEREL
+   /variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT
    /variable/CMAKE_LANG_FLAGS_RELEASE
+   /variable/CMAKE_LANG_FLAGS_RELEASE_INIT
    /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
+   /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
    /variable/CMAKE_LANG_FLAGS
+   /variable/CMAKE_LANG_FLAGS_INIT
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL
    /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE
@@ -368,6 +400,7 @@ Variables for Languages
    /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS
    /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES
    /variable/CMAKE_LANG_STANDARD_LIBRARIES
+   /variable/CMAKE_Swift_LANGUAGE_VERSION
    /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG
 
 Variables for CTest

Help/manual/cmake.1.rst

@@ -108,6 +108,11 @@ Options
 
  Like ``--trace``, but with variables expanded.
 
+``--trace-source=<file>``
+ Put cmake in trace mode, but output only lines of a specified file.
+
+ Multiple options are allowed.
+
 ``--warn-uninitialized``
  Warn about uninitialized values.
 
@@ -175,6 +180,43 @@ CMake provides builtin command-line tools through the signature::
 Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
 Available commands are:
 
+``capabilities``
+  Report cmake capabilities in JSON format. The output is a JSON object
+  with the following keys:
+
+  ``version``
+    A JSON object with version information. Keys are:
+
+    ``string``
+      The full version string as displayed by cmake ``--version``.
+    ``major``
+      The major version number in integer form.
+    ``minor``
+      The minor version number in integer form.
+    ``patch``
+      The patch level in integer form.
+    ``suffix``
+      The cmake version suffix string.
+    ``isDirty``
+      A bool that is set if the cmake build is from a dirty tree.
+
+  ``generators``
+    A list available generators. Each generator is a JSON object with the
+    following keys:
+
+    ``name``
+      A string containing the name of the generator.
+    ``toolsetSupport``
+      ``true`` if the generator supports toolsets and ``false`` otherwise.
+    ``platformSupport``
+      ``true`` if the generator supports platforms and ``false`` otherwise.
+    ``extraGenerators``
+      A list of strings with all the extra generators compatible with
+      the generator.
+
+  ``serverMode``
+    ``true`` if cmake supports server-mode and ``false`` otherwise.
+
 ``chdir <dir> <cmd> [<arg>...]``
   Change the current working directory and run a command.
 
@@ -231,6 +273,9 @@ Available commands are:
 ``rename <oldname> <newname>``
   Rename a file or directory (on one volume).
 
+``server``
+  Launch :manual:`cmake-server(7)` mode.
+
 ``sleep <number>...``
   Sleep for given number of seconds.
 

Help/manual/ctest.1.rst

@@ -56,7 +56,7 @@ Options
  Enable failover.
 
  This option allows ctest to resume a test set execution that was
- previously interrupted.  If no interruption occurred, the -F option
+ previously interrupted.  If no interruption occurred, the ``-F`` option
  will have no effect.
 
 ``-j <jobs>, --parallel <jobs>``
@@ -77,12 +77,12 @@ Options
  Make ctest quiet.
 
  This option will suppress all the output.  The output log file will
- still be generated if the --output-log is specified.  Options such
+ still be generated if the ``--output-log`` is specified.  Options such
- as --verbose, --extra-verbose, and --debug are ignored if --quiet is
+ as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored
- specified.
+ if ``--quiet`` is specified.
 
 ``-O <file>, --output-log <file>``
- Output to log file
+ Output to log file.
 
  This option tells ctest to write all its output to a log file.
 
@@ -90,7 +90,7 @@ Options
  Disable actual execution of tests.
 
  This option tells ctest to list the tests that would be run but not
- actually run them.  Useful in conjunction with the -R and -E
+ actually run them.  Useful in conjunction with the ``-R`` and ``-E``
  options.
 
 ``-L <regex>, --label-regex <regex>``
@@ -118,7 +118,7 @@ Options
  given regular expression.
 
 ``-D <dashboard>, --dashboard <dashboard>``
- Execute dashboard test
+ Execute dashboard test.
 
  This option tells ctest to act as a CDash client and perform a
  dashboard test.  All tests are <Mode><Test>, where Mode can be
@@ -126,26 +126,27 @@ Options
  Update, Configure, Build, Test, Coverage, and Submit.
 
 ``-D <var>:<type>=<value>``
- Define a variable for script mode
+ Define a variable for script mode.
 
  Pass in variable values on the command line.  Use in conjunction
- with -S to pass variable values to a dashboard script.  Parsing -D
+ with ``-S`` to pass variable values to a dashboard script.  Parsing ``-D``
  arguments as variable values is only attempted if the value
- following -D does not match any of the known dashboard types.
+ following ``-D`` does not match any of the known dashboard types.
 
 ``-M <model>, --test-model <model>``
- Sets the model for a dashboard
+ Sets the model for a dashboard.
 
- This option tells ctest to act as a CDash client where the TestModel
+ This option tells ctest to act as a CDash client where the ``<model>``
- can be Experimental, Nightly, and Continuous.  Combining -M and -T
+ can be ``Experimental``, ``Nightly``, and ``Continuous``.
- is similar to -D
+ Combining ``-M`` and ``-T`` is similar to ``-D``.
 
 ``-T <action>, --test-action <action>``
- Sets the dashboard action to perform
+ Sets the dashboard action to perform.
 
  This option tells ctest to act as a CDash client and perform some
- action such as start, build, test etc.  Combining -M and -T is
+ action such as ``start``, ``build``, ``test`` etc. See
- similar to -D
+ `Dashboard Client Steps`_ for the full list of actions.
+ Combining ``-M`` and ``-T`` is similar to ``-D``.
 
 ``--track <track>``
  Specify the track to submit dashboard to
@@ -156,24 +157,24 @@ Options
  arbitrary.
 
 ``-S <script>, --script <script>``
- Execute a dashboard for a configuration
+ Execute a dashboard for a configuration.
 
  This option tells ctest to load in a configuration script which sets
  a number of parameters such as the binary and source directories.
  Then ctest will do what is required to create and run a dashboard.
- This option basically sets up a dashboard and then runs ctest -D
+ This option basically sets up a dashboard and then runs ``ctest -D``
  with the appropriate options.
 
 ``-SP <script>, --script-new-process <script>``
- Execute a dashboard for a configuration
+ Execute a dashboard for a configuration.
 
- This option does the same operations as -S but it will do them in a
+ This option does the same operations as ``-S`` but it will do them in a
  separate process.  This is primarily useful in cases where the
  script may modify the environment and you do not want the modified
- environment to impact other -S scripts.
+ environment to impact other ``-S`` scripts.
 
 ``-A <file>, --add-notes <file>``
- Add a notes file with submission
+ Add a notes file with submission.
 
  This option tells ctest to include a notes file when submitting
  dashboard.
@@ -188,19 +189,19 @@ Options
  contains the same syntax as the command line.
 
 ``-U, --union``
- Take the Union of -I and -R
+ Take the Union of ``-I`` and ``-R``.
 
- When both -R and -I are specified by default the intersection of
+ When both ``-R`` and ``-I`` are specified by default the intersection of
- tests are run.  By specifying -U the union of tests is run instead.
+ tests are run.  By specifying ``-U`` the union of tests is run instead.
 
 ``--rerun-failed``
- Run only the tests that failed previously
+ Run only the tests that failed previously.
 
  This option tells ctest to perform only the tests that failed during
  its previous run.  When this option is specified, ctest ignores all
- other options intended to modify the list of tests to run (-L, -R,
+ other options intended to modify the list of tests to run (``-L``, ``-R``,
- -E, -LE, -I, etc).  In the event that CTest runs and no tests fail,
+ ``-E``, ``-LE``, ``-I``, etc).  In the event that CTest runs and no tests
- subsequent calls to ctest with the --rerun-failed option will run
+ fail, subsequent calls to ctest with the ``--rerun-failed`` option will run
  the set of tests that most recently failed (if any).
 
 ``--repeat-until-fail <n>``
@@ -209,7 +210,7 @@ Options
  This is useful in finding sporadic failures in test cases.
 
 ``--max-width <width>``
- Set the max width for a test name to output
+ Set the max width for a test name to output.
 
  Set the maximum width for each test name to show in the output.
  This allows the user to widen the output to avoid clipping the test
@@ -232,26 +233,25 @@ Options
  label associated with the tests run.  If there are no labels on the
  tests, nothing extra is printed.
 
-``--build-and-test``
+``--build-and-test <path-to-source> <path-to-build>``
  Configure, build and run a test.
 
  This option tells ctest to configure (i.e.  run cmake on), build,
  and or execute a test.  The configure and test steps are optional.
  The arguments to this command line are the source and binary
- directories.  By default this will run CMake on the Source/Bin
+ directories.
- directories specified unless --build-nocmake is specified.
+ The ``--build-generator`` option *must* be provided to use
- The --build-generator option *must* be provided to use
+ ``--build-and-test``.  If ``--test-command`` is specified then that will be
- --build-and-test.  If --test-command is specified then that will be
  run after the build is complete.  Other options that affect this
- mode are --build-target --build-nocmake, --build-run-dir,
+ mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``,
- --build-two-config, --build-exe-dir,
+ ``--build-two-config``, ``--build-exe-dir``,
- --build-project,--build-noclean, --build-options
+ ``--build-project``, ``--build-noclean`` and ``--build-options``.
 
 ``--build-target``
  Specify a specific target to build.
 
- This option goes with the --build-and-test option, if left out the
+ This option goes with the ``--build-and-test`` option, if left out the
- all target is built.
+ ``all`` target is built.
 
 ``--build-nocmake``
  Run the build without running cmake first.
@@ -264,13 +264,13 @@ Options
  Directory where programs will be after it has been compiled.
 
 ``--build-two-config``
- Run CMake twice
+ Run CMake twice.
 
 ``--build-exe-dir``
  Specify the directory for the executable.
 
 ``--build-generator``
- Specify the generator to use.
+ Specify the generator to use. See the :manual:`cmake-generators(7)` manual.
 
 ``--build-generator-platform``
  Specify the generator-specific platform.
@@ -288,25 +288,23 @@ Options
  Skip the make clean step.
 
 ``--build-config-sample``
- A sample executable to use to determine the configuration
-
  A sample executable to use to determine the configuration that
- should be used.  e.g.  Debug/Release/etc
+ should be used.  e.g.  Debug/Release/etc.
 
 ``--build-options``
  Add extra options to the build step.
 
  This option must be the last option with the exception of
- --test-command
+ ``--test-command``
 
 ``--test-command``
- The test to run with the --build-and-test option.
+ The test to run with the ``--build-and-test`` option.
 
 ``--test-output-size-passed <size>``
- Limit the output for passed tests to <size> bytes.
+ Limit the output for passed tests to ``<size>`` bytes.
 
 ``--test-output-size-failed <size>``
- Limit the output for failed tests to <size> bytes.
+ Limit the output for failed tests to ``<size>`` bytes.
 
 ``--test-timeout``
  The time limit in seconds, internal use only.
@@ -335,14 +333,14 @@ Options
  This option will submit extra files to the dashboard.
 
 ``--force-new-ctest-process``
- Run child CTest instances as new processes
+ Run child CTest instances as new processes.
 
  By default CTest will run child CTest instances within the same
  process.  If this behavior is not desired, this argument will
  enforce new processes for child CTest processes.
 
 ``--schedule-random``
- Use a random order for scheduling tests
+ Use a random order for scheduling tests.
 
  This option will run the tests in a random order.  It is commonly
  used to detect implicit dependencies in a test suite.
@@ -361,7 +359,7 @@ Options
  Set a time at which all tests should stop running.
 
  Set a real time of day at which all tests should timeout.  Example:
- 7:00:00 -0400.  Any time format understood by the curl date parser
+ ``7:00:00 -0400``.  Any time format understood by the curl date parser
  is accepted.  Local time is assumed if no timezone is specified.
 
 ``--http1.0``

Help/module/AndroidTestUtilities.rst

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

Help/module/CPackProductBuild.rst

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

Help/module/FindICU.rst

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

Help/module/FindVulkan.rst

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

Help/policy/CMP0066.rst

@@ -0,0 +1,27 @@
+CMP0066
+-------
+
+Honor per-config flags in :command:`try_compile` source-file signature.
+
+The source file signature of the :command:`try_compile` command uses the value
+of the :variable:`CMAKE_<LANG>_FLAGS` variable in the test project so that the
+test compilation works as it would in the main project.  However, CMake 3.6 and
+below do not also honor config-specific compiler flags such as those in the
+:variable:`CMAKE_<LANG>_FLAGS_DEBUG` variable.  CMake 3.7 and above prefer to
+honor config-specific compiler flags too.  This policy provides compatibility
+for projects that do not expect config-specific compiler flags to be used.
+
+The ``OLD`` behavior of this policy is to ignore config-specific flag
+variables like :variable:`CMAKE_<LANG>_FLAGS_DEBUG` and only use CMake's
+built-in defaults for the current compiler and platform.
+
+The ``NEW`` behavior of this policy is to honor config-specific flag
+variabldes like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`.
+
+This policy was introduced in CMake version 3.7.  Unlike most policies,
+CMake version |release| does *not* warn by default when this policy
+is not set and simply uses OLD behavior.  See documentation of the
+:variable:`CMAKE_POLICY_WARNING_CMP0066 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/prop_dir/BINARY_DIR.rst

@@ -0,0 +1,5 @@
+BINARY_DIR
+----------
+
+This read-only directory property reports absolute path to the binary
+directory corresponding to the source on which it is read.

Help/prop_dir/BUILDSYSTEM_TARGETS.rst

@@ -0,0 +1,11 @@
+BUILDSYSTEM_TARGETS
+-------------------
+
+This read-only directory property contains a
+:ref:`;-list <CMake Language Lists>` of buildsystem targets added in the
+directory by calls to the :command:`add_library`, :command:`add_executable`,
+and :command:`add_custom_target` commands.  The list does not include any
+:ref:`Imported Targets` or :ref:`Alias Targets`, but does include
+:ref:`Interface Libraries`.  Each entry in the list is the logical name
+of a target, suitable to pass to the :command:`get_property` command
+``TARGET`` option.

Help/prop_dir/SOURCE_DIR.rst

@@ -0,0 +1,5 @@
+SOURCE_DIR
+----------
+
+This read-only directory property reports absolute path to the source
+directory on which it is read.

Help/prop_dir/SUBDIRECTORIES.rst

@@ -0,0 +1,15 @@
+SUBDIRECTORIES
+--------------
+
+This read-only directory property contains a
+:ref:`;-list <CMake Language Lists>` of subdirectories processed so far by
+the :command:`add_subdirectory` or :command:`subdirs` commands.  Each entry is
+the absolute path to the source directory (containing the ``CMakeLists.txt``
+file).  This is suitable to pass to the :command:`get_property` command
+``DIRECTORY`` option.
+
+.. note::
+
+  The :command:`subdirs` command does not process its arguments until
+  after the calling directory is fully processed.  Therefore looking
+  up this property in the current directory will not see them.

Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst

@@ -0,0 +1,10 @@
+FIND_LIBRARY_USE_LIB32_PATHS
+----------------------------
+
+Whether the :command:`find_library` command should automatically search
+``lib32`` directories.
+
+``FIND_LIBRARY_USE_LIB32_PATHS`` is a boolean specifying whether the
+:command:`find_library` command should automatically search the ``lib32``
+variant of directories called ``lib`` in the search path when building 32-bit
+binaries.

Help/prop_sf/VS_TOOL_OVERRIDE.rst

@@ -0,0 +1,5 @@
+VS_TOOL_OVERRIDE
+----------------
+
+Override the default Visual Studio tool that will be applied to the source file
+with a new tool not based on the extension of the file.

Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst

@@ -0,0 +1,11 @@
+XCODE_FILE_ATTRIBUTES
+---------------------
+
+Add values to the Xcode ``ATTRIBUTES`` setting on its reference to a
+source file.  Among other things, this can be used to set the role on
+a mig file::
+
+  set_source_files_properties(defs.mig
+      PROPERTIES
+          XCODE_FILE_ATTRIBUTES "Client;Server"
+  )

Help/prop_test/DEPENDS.rst

@@ -3,4 +3,8 @@ DEPENDS
 
 Specifies that this test should only be run after the specified list of tests.
 
-Set this to a list of tests that must finish before this test is run.
+Set this to a list of tests that must finish before this test is run. The
+results of those tests are not considered, the dependency relationship is
+purely for order of execution (i.e. it is really just a *run after*
+relationship). Consider using test fixtures with setup tests if a dependency
+with successful completion is required (see :prop_test:`FIXTURES_REQUIRED`).

Help/prop_test/FIXTURES_CLEANUP.rst

@@ -0,0 +1,46 @@
+FIXTURES_CLEANUP
+----------------
+
+Specifies a list of fixtures for which the test is to be treated as a cleanup
+test.
+
+Fixture cleanup tests are ordinary tests with all of the usual test
+functionality. Setting the ``FIXTURES_CLEANUP`` property for a test has two
+primary effects:
+
+- CTest will ensure the test executes after all other tests which list any of
+  the fixtures in its :prop_test:`FIXTURES_REQUIRED` property.
+
+- If CTest is asked to run only a subset of tests (e.g. using regular
+  expressions or the ``--rerun-failed`` option) and the cleanup test is not in
+  the set of tests to run, it will automatically be added if any tests in the
+  set require any fixture listed in ``FIXTURES_CLEANUP``.
+
+A cleanup test can have multiple fixtures listed in its ``FIXTURES_CLEANUP``
+property. It will execute only once for the whole CTest run, not once for each
+fixture. A fixture can also have more than one cleanup test defined. If there
+are multiple cleanup tests for a fixture, projects can control their order with
+the usual :prop_test:`DEPENDS` test property if necessary.
+
+A cleanup test is allowed to require other fixtures, but not any fixture listed
+in its ``FIXTURES_CLEANUP`` property. For example:
+
+.. code-block:: cmake
+
+  # Ok: Dependent fixture is different to cleanup
+  set_tests_properties(cleanupFoo PROPERTIES
+    FIXTURES_CLEANUP  Foo
+    FIXTURES_REQUIRED Bar
+  )
+
+  # Error: cannot require same fixture as cleanup
+  set_tests_properties(cleanupFoo PROPERTIES
+    FIXTURES_CLEANUP  Foo
+    FIXTURES_REQUIRED Foo
+  )
+
+Cleanup tests will execute even if setup or regular tests for that fixture fail
+or are skipped.
+
+See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use
+test fixtures.

Help/prop_test/FIXTURES_REQUIRED.rst

@@ -0,0 +1,94 @@
+FIXTURES_REQUIRED
+-----------------
+
+Specifies a list of fixtures the test requires. Fixture names are case
+sensitive.
+
+Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a
+test requires a given fixture, then all tests marked as setup tasks for that
+fixture will be executed first (once for the whole set of tests, not once per
+test requiring the fixture). After all tests requiring a particular fixture
+have completed, CTest will ensure all tests marked as cleanup tasks for that
+fixture are then executed. Tests are marked as setup tasks with the
+:prop_test:`FIXTURES_SETUP` property and as cleanup tasks with the
+:prop_test:`FIXTURES_CLEANUP` property. If any of a fixture's setup tests fail,
+all tests listing that fixture in their ``FIXTURES_REQUIRED`` property will not
+be executed. The cleanup tests for the fixture will always be executed, even if
+some setup tests fail.
+
+When CTest is asked to execute only a subset of tests (e.g. by the use of
+regular expressions or when run with the ``--rerun-failed`` command line
+option), it will automatically add any setup or cleanup tests for fixtures
+required by any of the tests that are in the execution set.
+
+Since setup and cleanup tasks are also tests, they can have an ordering
+specified by the :prop_test:`DEPENDS` test property just like any other tests.
+This can be exploited to implement setup or cleanup using multiple tests for a
+single fixture to modularise setup or cleanup logic.
+
+The concept of a fixture is different to that of a resource specified by
+:prop_test:`RESOURCE_LOCK`, but they may be used together. A fixture defines a
+set of tests which share setup and cleanup requirements, whereas a resource
+lock has the effect of ensuring a particular set of tests do not run in
+parallel. Some situations may need both, such as setting up a database,
+serialising test access to that database and deleting the database again at the
+end. For such cases, tests would populate both ``FIXTURES_REQUIRED`` and
+:prop_test:`RESOURCE_LOCK` to combine the two behaviours. Names used for
+:prop_test:`RESOURCE_LOCK` have no relationship with names of fixtures, so note
+that a resource lock does not imply a fixture and vice versa.
+
+Consider the following example which represents a database test scenario
+similar to that mentioned above:
+
+.. code-block:: cmake
+
+  add_test(NAME testsDone   COMMAND emailResults)
+  add_test(NAME fooOnly     COMMAND testFoo)
+  add_test(NAME dbOnly      COMMAND testDb)
+  add_test(NAME dbWithFoo   COMMAND testDbWithFoo)
+  add_test(NAME createDB    COMMAND initDB)
+  add_test(NAME setupUsers  COMMAND userCreation)
+  add_test(NAME cleanupDB   COMMAND deleteDB)
+  add_test(NAME cleanupFoo  COMMAND removeFoos)
+
+  set_tests_properties(setupUsers PROPERTIES DEPENDS createDB)
+
+  set_tests_properties(createDB   PROPERTIES FIXTURES_SETUP    DB)
+  set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP    DB)
+  set_tests_properties(cleanupDB  PROPERTIES FIXTURES_CLEANUP  DB)
+  set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP  Foo)
+  set_tests_properties(testsDone  PROPERTIES FIXTURES_CLEANUP  "DB;Foo")
+
+  set_tests_properties(fooOnly    PROPERTIES FIXTURES_REQUIRED Foo)
+  set_tests_properties(dbOnly     PROPERTIES FIXTURES_REQUIRED DB)
+  set_tests_properties(dbWithFoo  PROPERTIES FIXTURES_REQUIRED "DB;Foo")
+
+  set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB
+                       PROPERTIES RESOURCE_LOCK DbAccess)
+
+Key points from this example:
+
+- Two fixtures are defined: ``DB`` and ``Foo``. Tests can require a single
+  fixture as ``fooOnly`` and ``dbOnly`` do, or they can depend on multiple
+  fixtures like ``dbWithFoo`` does.
+
+- A ``DEPENDS`` relationship is set up to ensure ``setupUsers`` happens after
+  ``createDB``, both of which are setup tests for the ``DB`` fixture and will
+  therefore be executed before the ``dbOnly`` and ``dbWithFoo`` tests
+  automatically.
+
+- No explicit ``DEPENDS`` relationships were needed to make the setup tests run
+  before or the cleanup tests run after the regular tests.
+
+- The ``Foo`` fixture has no setup tests defined, only a single cleanup test.
+
+- ``testsDone`` is a cleanup test for both the ``DB`` and ``Foo`` fixtures.
+  Therefore, it will only execute once regular tests for both fixtures have
+  finished (i.e. after ``fooOnly``, ``dbOnly`` and ``dbWithFoo``). No
+  ``DEPENDS`` relationship was specified for ``testsDone``, so it is free to
+  run before, after or concurrently with other cleanup tests for either
+  fixture.
+
+- The setup and cleanup tests never list the fixtures they are for in their own
+  ``FIXTURES_REQUIRED`` property, as that would result in a dependency on
+  themselves and be considered an error.

Help/prop_test/FIXTURES_SETUP.rst

@@ -0,0 +1,47 @@
+FIXTURES_SETUP
+--------------
+
+Specifies a list of fixtures for which the test is to be treated as a setup
+test.
+
+Fixture setup tests are ordinary tests with all of the usual test
+functionality. Setting the ``FIXTURES_SETUP`` property for a test has two
+primary effects:
+
+- CTest will ensure the test executes before any other test which lists the
+  fixture(s) in its :prop_test:`FIXTURES_REQUIRED` property.
+
+- If CTest is asked to run only a subset of tests (e.g. using regular
+  expressions or the ``--rerun-failed`` option) and the setup test is not in
+  the set of tests to run, it will automatically be added if any tests in the
+  set require any fixture listed in ``FIXTURES_SETUP``.
+
+A setup test can have multiple fixtures listed in its ``FIXTURES_SETUP``
+property. It will execute only once for the whole CTest run, not once for each
+fixture. A fixture can also have more than one setup test defined. If there are
+multiple setup tests for a fixture, projects can control their order with the
+usual :prop_test:`DEPENDS` test property if necessary.
+
+A setup test is allowed to require other fixtures, but not any fixture listed
+in its ``FIXTURES_SETUP`` property. For example:
+
+.. code-block:: cmake
+
+  # Ok: dependent fixture is different to setup
+  set_tests_properties(setupFoo PROPERTIES
+    FIXTURES_SETUP    Foo
+    FIXTURES_REQUIRED Bar
+  )
+
+  # Error: cannot require same fixture as setup
+  set_tests_properties(setupFoo PROPERTIES
+    FIXTURES_SETUP    Foo
+    FIXTURES_REQUIRED Foo
+  )
+
+If any of a fixture's setup tests fail, none of the tests listing that fixture
+in its :prop_test:`FIXTURES_REQUIRED` property will be run. Cleanup tests will,
+however, still be executed.
+
+See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use
+test fixtures.

Help/prop_test/RESOURCE_LOCK.rst

@@ -5,3 +5,6 @@ Specify a list of resources that are locked by this test.
 
 If multiple tests specify the same resource lock, they are guaranteed
 not to run concurrently.
+
+See also :prop_test:`FIXTURES_REQUIRED` if the resource requires any setup or
+cleanup steps.

Help/prop_tgt/ANDROID_API.rst

@@ -1,7 +1,8 @@
 ANDROID_API
 -----------
 
-Set the Android Target API version (e.g. ``15``).  The version number
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
-must be a positive decimal integer.  This property is initialized by
+Edition`, this property sets the Android target API version (e.g. ``15``).
-the value of the :variable:`CMAKE_ANDROID_API` variable if it is set
+The version number must be a positive decimal integer.  This property is
-when a target is created.
+initialized by the value of the :variable:`CMAKE_ANDROID_API` variable if
+it is set when a target is created.

Help/prop_tgt/ANDROID_ARCH.rst

@@ -1,7 +1,8 @@
 ANDROID_ARCH
 ------------
 
-Set the Android target architecture.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this property sets the Android target architecture.
 
 This is a string property that could be set to the one of
 the following values:

Help/prop_tgt/ANDROID_GUI.rst

@@ -1,7 +1,9 @@
 ANDROID_GUI
 -----------
 
-Build an executable as an application package on Android.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this property specifies whether to build an executable as an
+application package on Android.
 
 When this property is set to true the executable when built for Android
 will be created as an application package.  This property is initialized

Help/prop_tgt/ANDROID_STL_TYPE.rst

@@ -1,15 +1,27 @@
 ANDROID_STL_TYPE
 ----------------
 
-Set the Android property that defines the type of STL support for the project.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this property specifies the type of STL support for the project.
 This is a string property that could set to the one of the following values:
-``none``           e.g. "No C++ Support"
+
-``system``         e.g. "Minimal C++ without STL"
+``none``
-``gabi++_static``  e.g. "GAbi++ Static"
+  No C++ Support
-``gabi++_shared``  e.g. "GAbi++ Shared"
+``system``
-``gnustl_static``  e.g. "GNU libstdc++ Static"
+  Minimal C++ without STL
-``gnustl_shared``  e.g. "GNU libstdc++ Shared"
+``gabi++_static``
-``stlport_static`` e.g. "STLport Static"
+  GAbi++ Static
-``stlport_shared`` e.g. "STLport Shared"
+``gabi++_shared``
+  GAbi++ Shared
+``gnustl_static``
+  GNU libstdc++ Static
+``gnustl_shared``
+  GNU libstdc++ Shared
+``stlport_static``
+  STLport Static
+``stlport_shared``
+  STLport Shared
+
 This property is initialized by the value of the
-variable:`CMAKE_ANDROID_STL_TYPE` variable if it is set when a target is created.
+:variable:`CMAKE_ANDROID_STL_TYPE` variable if it is set when a target is
+created.

Help/prop_tgt/AUTORCC.rst

@@ -19,5 +19,10 @@ Additional command line options for rcc can be set via the
 The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group
 the autorcc targets together in an IDE, e.g. in MSVS.
 
+When there are multiple ``.qrc`` files with the same name, CMake will
+generate unspecified unique names for ``rcc``.  Therefore if
+``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the
+``.qrc`` file name must be unique.
+
 See the :manual:`cmake-qt(7)` manual for more information on using CMake
 with Qt.

Help/prop_tgt/BUNDLE_EXTENSION.rst

@@ -1,7 +1,8 @@
 BUNDLE_EXTENSION
 ----------------
 
-The file extension used to name a :prop_tgt:`BUNDLE` target on the OS X and iOS.
+The file extension used to name a :prop_tgt:`BUNDLE`, a :prop_tgt:`FRAMEWORK`,
+or a :prop_tgt:`MACOSX_BUNDLE` target on the OS X and iOS.
 
-The default value is ``bundle`` - you can also use ``plugin`` or whatever
+The default value is ``bundle``, ``framework``, or ``app`` for the respective
-file extension is required by the host app for your bundle.
+target types.

Help/prop_tgt/LINK_WHAT_YOU_USE.rst

@@ -0,0 +1,15 @@
+LINK_WHAT_YOU_USE
+---------------------------
+
+This is a boolean option that when set to ``TRUE`` will automatically run
+``ldd -r -u`` on the target after it is linked. In addition, the linker flag
+``-Wl,--no-as-needed`` will be passed to the target with the link command so
+that all libraries specified on the command line will be linked into the
+target. This will result in the link producing a list of libraries that
+provide no symbols used by this target but are being linked to it.
+This is only applicable to executable and shared library targets and
+will only work when ld and ldd accept the flags used.
+
+This property is initialized by the value of
+the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set
+when a target is created.

Help/prop_tgt/VS_SDK_REFERENCES.rst

@@ -0,0 +1,7 @@
+VS_SDK_REFERENCES
+-----------------
+
+Visual Studio project SDK references.
+Specify a :ref:`;-list <CMake Language Lists>` of SDK references
+to be added to a generated Visual Studio project, e.g.
+``Microsoft.AdMediatorWindows81, Version=1.0``.

Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst

@@ -5,8 +5,9 @@ This property is implemented only for MS-compatible tools on Windows.
 
 Enable this boolean property to automatically create a module definition
 (``.def``) file with all global symbols found in the input ``.obj`` files
-for a ``SHARED`` library on Windows.  The module definition file will be
+for a ``SHARED`` library (or executable with :prop_tgt:`ENABLE_EXPORTS`)
-passed to the linker causing all symbols to be exported from the ``.dll``.
+on Windows.  The module definition file will be passed to the linker
+causing all symbols to be exported from the ``.dll``.
 For global *data* symbols, ``__declspec(dllimport)`` must still be used when
 compiling against the code in the ``.dll``.  All other function symbols will
 be automatically exported and imported by callers.  This simplifies porting

Help/release/3.7.rst

@@ -0,0 +1,320 @@
+CMake 3.7 Release Notes
+***********************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.6 include the following.
+
+New Features
+============
+
+Platforms
+---------
+
+* CMake now supports :ref:`Cross Compiling for Android` with simple
+  toolchain files.
+
+* The Clang compiler is now supported on AIX.
+
+Generators
+----------
+
+* The :generator:`Ninja` generator learned to conditionally support
+  Fortran when using a ``ninja`` tool that has the necessary features.
+  See generator documentation for details.
+
+* The :generator:`Ninja` generator learned to produce phony targets
+  of the form ``sub/dir/{test,install,package}`` to drive the build
+  of a subdirectory installation, test or packaging target.
+  This is equivalent to ``cd sub/dir; make {test,install,package}``
+  with :ref:`Makefile Generators`.
+
+* The :generator:`Visual Studio 15 2017` generator was added.  This is
+  experimental and based on "Visual Studio 2017 RC" because this version
+  of VS has not been released.
+
+* :ref:`Visual Studio Generators` for VS 2010 and above learned to
+  place ``.natvis`` source files into VS project files properly.
+
+* The :generator:`Xcode` generator's rudimentary Swift language support
+  learned to honor a new :variable:`CMAKE_Swift_LANGUAGE_VERSION` variable
+  to tell Xcode what version of Swift is used by the source.
+
+* The :generator:`CodeLite` generator gained a new
+  :variable:`CMAKE_CODELITE_USE_TARGETS` option
+  to change project creation from projects to targets.
+
+Commands
+--------
+
+* The :command:`add_custom_command` command gained a new ``DEPFILE``
+  option that works with the :generator:`Ninja` generator to provide
+  implicit dependency information to the build tool.
+
+* The :command:`cmake_parse_arguments` command gained a new ``PARSE_ARGV``
+  mode to read arguments directly from ``ARGC`` and ``ARGV#``
+  variables inside a :command:`function` body.
+
+* The :command:`export` command gained an ``ANDROID_MK`` option
+  to generate ``Android.mk`` files referencing CMake-built
+  libraries as prebuilts for the Android NDK build system.
+
+* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands gained
+  ``HTTPHEADER <HTTP-header>`` and ``USERPWD <username>:<password>`` options.
+
+* The :command:`find_library` and :command:`find_package` commands learned
+  to search in ``lib32/`` directories when the build targets a 32-bit
+  architecture.  See the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global
+  property.
+
+* The :command:`find_package` command gained the possibility of
+  sorting compatible libraries by ``NAME`` or by ``NATURAL`` sorting by
+  setting the two new variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
+  and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
+
+* The :command:`if` command gained new boolean comparison operations
+  ``LESS_EQUAL``, ``GREATER_EQUAL``, ``STRLESS_EQUAL``, ``STRGREATER_EQUAL``,
+  ``VERSION_LESS_EQUAL``, and ``VERSION_GREATER_EQUAL``.
+
+* The :command:`install` command gained an ``EXPORT_ANDROID_MK``
+  subcommand to install ``Android.mk`` files referencing installed
+  libraries as prebuilts for the Android NDK build system.
+
+* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)`
+  commands gained support for the ``%a`` and ``%b`` placeholders.
+  These are the abbreviated weekday and month names.
+
+* The :command:`try_compile` command source file signature now honors
+  configuration-specific flags (e.g. :variable:`CMAKE_<LANG>_FLAGS_DEBUG`)
+  in the generated test project.  Previously only the default such flags
+  for the current toolchain were used.  See policy :policy:`CMP0066`.
+
+Variables
+---------
+
+* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` was added to control
+  the sorting mode of the :command:`find_package` command.
+
+* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` was added to control
+  the sorting direction the :command:`find_package` command.
+
+* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set a
+  :variable:`CMAKE_<LANG>_FLAGS_INIT` variable to initialize the
+  :variable:`CMAKE_<LANG>_FLAGS` cache entry the first time a language is
+  enabled in a build tree.
+
+* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set
+  :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`,
+  :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and
+  :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT` variables to initialize the
+  :variable:`CMAKE_EXE_LINKER_FLAGS`,
+  :variable:`CMAKE_SHARED_LINKER_FLAGS`, and
+  :variable:`CMAKE_MODULE_LINKER_FLAGS` cache entries the first time
+  a language is enabled in a build tree.
+
+Properties
+----------
+
+* On Apple platforms the :prop_tgt:`BUNDLE_EXTENSION` target property
+  now also applies to Frameworks and App Bundles.
+
+* A :prop_dir:`BINARY_DIR` directory property was added to get the
+  absolute path to the binary directory corresponding to the source
+  directory on which the property is read.
+
+* A :prop_dir:`BUILDSYSTEM_TARGETS` directory property was added to
+  get the list of logical buildsystem target names added by the
+  project in a directory.
+
+* A :prop_tgt:`LINK_WHAT_YOU_USE` target property and supporting
+  :variable:`CMAKE_LINK_WHAT_YOU_USE` variable were introduced
+  to detect (on UNIX) shared libraries that are linked but not
+  needed by running ``ldd -r -u``.
+
+* A :prop_dir:`SOURCE_DIR` directory property was added to get the
+  absolute path to the source directory associated with a directory.
+
+* A :prop_dir:`SUBDIRECTORIES` directory property was added to
+  get the list of subdirectories added by a project in a directory.
+
+* A :prop_tgt:`VS_SDK_REFERENCES` target property was added to tell
+  :ref:`Visual Studio Generators` to reference the named SDKs.
+
+* A :prop_sf:`VS_TOOL_OVERRIDE` source file property was created to tell
+  :ref:`Visual Studio Generators` what tool to use for a source file.
+
+* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property now applies
+  to executable targets with the :prop_tgt:`ENABLE_EXPORTS` property set.
+
+* A :prop_sf:`XCODE_FILE_ATTRIBUTES` source file property was
+  added to tell the :generator:`Xcode` generator to generate
+  custom content in the Xcode project attributes for the file.
+
+Modules
+-------
+
+* An :module:`AndroidTestUtilities` module was added to manage transfer
+  of test data to an Android device.
+
+* The :module:`CheckFortranSourceCompiles` module macro
+  ``CHECK_Fortran_SOURCE_COMPILES`` gained a ``SRC_EXT`` option
+  to specify a custom test Fortran source file extension.
+
+* The :module:`ExternalProject` module gained ``HTTP_USERNAME`` and
+  ``HTTP_PASSWORD`` options to set http download credentials.
+
+* The :module:`ExternalProject` module gained a ``HTTP_HEADER``
+  option to add http download headers.
+
+* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new
+  ``REPORT_FILE`` option to specify the bison ``--report-file=`` option.
+
+* The :module:`FindBZip2` module now provides imported targets.
+
+* A :module:`FindICU` module was introduced to find the International
+  Components for Unicode (ICU) libraries and programs.
+
+* The :module:`FindMatlab` module learned to find the SIMULINK and MAT
+  components.
+
+* The :module:`FindMatlab` module :command:`matlab_add_mex` command learned
+  to add executables and modules.
+
+* The :module:`FindMatlab` module :command:`matlab_add_unit_test` command
+  learned to support inline Matlab test code.
+
+* The :module:`FindOpenCL` module now provides imported targets.
+
+* The :module:`FindOpenMP` module learned to detect the OpenMP
+  version (specification date) from the compiler.
+
+* A :module:`FindVulkan` module was added.
+
+* The :module:`GenerateExportHeader` module learned a new
+  ``CUSTOM_CONTENT_FROM_VARIABLE`` option to specify a variable
+  containing custom content for inclusion in the generated header.
+
+* The :module:`GNUInstallDirs` module gained a new
+  :command:`GNUInstallDirs_get_absolute_install_dir` command.
+
+* The :module:`UseJava` module gained APIs to "export" jar targets
+  for use by external CMake projects.  See the ``install_jar_exports``
+  and ``export_jars`` functions.
+
+CTest
+-----
+
+* CTest now supports test fixtures through the new :prop_test:`FIXTURES_SETUP`,
+  :prop_test:`FIXTURES_CLEANUP` and :prop_test:`FIXTURES_REQUIRED` test
+  properties. When using regular expressions or ``--rerun-failed`` to limit
+  the tests to be run, a fixture's setup and cleanup tests will automatically
+  be added to the execution set if any test requires that fixture.
+
+* The :command:`ctest_configure`, :command:`ctest_build`,
+  :command:`ctest_test`, :command:`ctest_coverage`, and :command:`ctest_upload`
+  commands gained a new ``CAPTURE_CMAKE_ERROR`` option to capture any errors
+  that occur as the commands run into a variable and avoid affecting the return
+  code of the :manual:`ctest(1)` process.
+
+CPack
+-----
+
+* CPack gained a ``productbuild`` generator on OS X, configured by
+  the :module:`CPackProductBuild` module.
+
+* CPack gained a new :variable:`CPACK_PACKAGE_CHECKSUM` variable to
+  enable generation of a checksum file for each package file.
+
+* The :module:`CPackDeb` module learned to support long file names
+  when archive format is set to GNU tar.
+  See :variable:`CPACK_DEBIAN_ARCHIVE_TYPE`
+
+* The :module:`CPackIFW` module gained a new
+  :command:`cpack_ifw_add_package_resources` command to include additional
+  resources in the installer binary.
+
+* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
+  :command:`cpack_ifw_configure_component_group` commands gained a new
+  ``USER_INTERFACES`` option to add a list of additonal pages to the IFW
+  installer.
+
+* The :module:`CPackRPM` module learned to generate debuginfo
+  packages on demand. See :variable:`CPACK_RPM_DEBUGINFO_PACKAGE`
+  and its per component version.
+
+* The :module:`CPackRPM` module learned to generate source rpm
+  (SRPM) packages on demand. See :variable:`CPACK_RPM_PACKAGE_SOURCES`,
+  :variable:`CPACK_RPM_SOURCE_PKG_BUILD_PARAMS` and
+  :variable:`CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX`.
+
+* The CPack NSIS generator now supports
+  :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`.
+  This can be used to set component specific installation directories.
+
+* The CPack WIX generator now supports
+  :variable:`CPACK_WIX_SKIP_PROGRAM_FOLDER` to allow specification
+  of a custom absolute installation prefix outside
+  of the ProgramFiles folders.
+
+* The CPack WIX generator now supports
+  :variable:`CPACK_COMPONENT_<compName>_DISABLED`.
+  This can be used to deselect a component from being installed by default.
+
+* The CPack WIX generator now supports :variable:`CPACK_WIX_PATCH_FILE`
+  fragments for Feature elements.
+
+* The CPack WIX generator now supports
+  :variable:`CPACK_WIX_ROOT_FEATURE_TITLE` and
+  :variable:`CPACK_WIX_ROOT_FEATURE_DESCRIPTION` to allow the specification
+  of a custom title and description for the root feature element.
+
+Other
+-----
+
+* :manual:`cmake(1)` gained a ``-E capabilities`` option to provide a
+  machine-readable (JSON) description of the capabilities of the
+  cmake tool (available generators, etc.).
+
+* A new :manual:`cmake-server(7)` mode was added to provide semantic
+  information about a CMake-generated buildsystem to clients through
+  a JSON protocol.  Currently all protocols are experimental and subject
+  to change.
+
+* The :manual:`cmake(1)` command learned a ``--trace-source=<file>`` option.
+
+* :manual:`ccmake(1)` learned to support vim-like navigation bindings.
+
+* :manual:`cmake-gui(1)` gained a button to open the generated project file
+  for :ref:`Visual Studio Generators` and the :generator:`Xcode` generator.
+
+Deprecated and Removed Features
+===============================
+
+* We no longer provide Linux i386 binaries for download from ``cmake.org``
+  for new versions of CMake.
+
+* Vim support files ``cmake-indent.vim``, ``cmake-syntax.vim``, and
+  ``cmake-help.vim`` have been removed in favor of the files now provided
+  from the `vim-cmake-syntax`_ project.
+
+* Support for building CMake itself with some compilers was dropped:
+
+  * Visual Studio 7.1 and 2005 -- superseded by VS 2008 and above
+  * MinGW.org mingw32 -- superseded by MSYS2 mingw32 and mingw64
+
+  CMake still supports generating build systems for other projects using
+  these compilers.
+
+Other Changes
+=============
+
+* The Fortran dependency scanner learned to support the syntax of
+  `Fortran Submodules`_.
+
+* Vim support files ``indent/cmake.vim`` and ``syntax/cmake.vim``
+  from the `vim-cmake-syntax`_ project are now distributed with CMake.
+
+.. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules
+.. _`vim-cmake-syntax`: https://github.com/pboettch/vim-cmake-syntax

Help/release/index.rst

@@ -11,6 +11,7 @@ Releases
 .. toctree::
    :maxdepth: 1
 
+   3.7 <3.7>
    3.6 <3.6>
    3.5 <3.5>
    3.4 <3.4>

Help/variable/ANDROID.rst

@@ -0,0 +1,5 @@
+ANDROID
+-------
+
+Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is
+``Android``.

Help/variable/CMAKE_ANDROID_API.rst

@@ -1,5 +1,11 @@
 CMAKE_ANDROID_API
 -----------------
 
-Default value for the :prop_tgt:`ANDROID_API` target property.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
-See that target property for additional information.
+Edition`, this variable may be set to specify the default value for the
+:prop_tgt:`ANDROID_API` target property.  See that target property for
+additional information.
+
+Otherwise, when :ref:`Cross Compiling for Android`, this variable provides
+the Android API version number targeted.  This will be the same value as
+the :variable:`CMAKE_SYSTEM_VERSION` variable for ``Android`` platforms.

Help/variable/CMAKE_ANDROID_ARCH.rst

@@ -1,5 +1,19 @@
 CMAKE_ANDROID_ARCH
 ------------------
 
-Default value for the :prop_tgt:`ANDROID_ARCH` target property.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
-See that target property for additional information.
+Edition`, this variable may be set to specify the default value for the
+:prop_tgt:`ANDROID_ARCH` target property.  See that target property for
+additional information.
+
+Otherwise, when :ref:`Cross Compiling for Android`, this variable provides
+the name of the Android architecture corresponding to the value of the
+:variable:`CMAKE_ANDROID_ARCH_ABI` variable.  The architecture name
+may be one of:
+
+* ``arm``
+* ``arm64``
+* ``mips``
+* ``mips64``
+* ``x86``
+* ``x86_64``

Help/variable/CMAKE_ANDROID_ARCH_ABI.rst

@@ -0,0 +1,17 @@
+CMAKE_ANDROID_ARCH_ABI
+----------------------
+
+When :ref:`Cross Compiling for Android`, this variable specifies the
+target architecture and ABI to be used.  Valid values are:
+
+* ``arm64-v8a``
+* ``armeabi-v7a``
+* ``armeabi-v6``
+* ``armeabi``
+* ``mips``
+* ``mips64``
+* ``x86``
+* ``x86_64``
+
+See also the :variable:`CMAKE_ANDROID_ARM_MODE` and
+:variable:`CMAKE_ANDROID_ARM_NEON` variables.

Help/variable/CMAKE_ANDROID_ARM_MODE.rst

@@ -0,0 +1,7 @@
+CMAKE_ANDROID_ARM_MODE
+----------------------
+
+When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI`
+is set to one of the ``armeabi`` architectures, set ``CMAKE_ANDROID_ARM_MODE``
+to ``ON`` to target 32-bit ARM processors (``-marm``).  Otherwise, the
+default is to target the 16-bit Thumb processors (``-mthumb``).

Help/variable/CMAKE_ANDROID_ARM_NEON.rst

@@ -0,0 +1,6 @@
+CMAKE_ANDROID_ARM_NEON
+----------------------
+
+When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI`
+is set to ``armeabi-v7a`` set ``CMAKE_ANDROID_ARM_NEON`` to ``ON`` to target
+ARM NEON devices.

Help/variable/CMAKE_ANDROID_NDK.rst

@@ -0,0 +1,7 @@
+CMAKE_ANDROID_NDK
+-----------------
+
+When :ref:`Cross Compiling for Android with the NDK`, this variable holds
+the absolute path to the root directory of the NDK.  The directory must
+contain a ``platforms`` subdirectory holding the ``android-<api>``
+directories.

Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG.rst

@@ -0,0 +1,6 @@
+CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
+------------------------------------
+
+When :ref:`Cross Compiling for Android with the NDK`, this variable
+provides the NDK's "host tag" used to construct the path to prebuilt
+toolchains that run on the host.

Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst

@@ -0,0 +1,16 @@
+CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
+-----------------------------------
+
+When :ref:`Cross Compiling for Android with the NDK`, this variable
+may be set to specify the version of the toolchain to be used
+as the compiler.  The variable must be set to one of these forms:
+
+* ``<major>.<minor>``: GCC of specified version
+* ``clang<major>.<minor>``: Clang of specified version
+* ``clang``: Clang of most recent available version
+
+A toolchain of the requested version will be selected automatically to
+match the ABI named in the :variable:`CMAKE_ANDROID_ARCH_ABI` variable.
+
+If not specified, the default will be a value that selects the latest
+available GCC toolchain.