Merge branch 'backport-3.19-rel-file-table' into rel-file-table

10 files changed, 453 insertions, 0 deletions

diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index 5ee0612..f33e4af 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -224,6 +224,7 @@ if(UNIX AND "${CMAKE_GENERATOR}" MATCHES "Unix Makefiles|Ninja")
   add_RunCMake_test(Byproducts)
 endif()
 add_RunCMake_test(CMakeRoleGlobalProperty)
+add_RunCMake_test(CMakeRelease -DCMake_TEST_JQ=${CMake_TEST_JQ})
 if(UNIX AND "${CMAKE_GENERATOR}" MATCHES "Unix Makefiles|Ninja")
   add_RunCMake_test(CompilerChange)
 endif()
diff --git a/Tests/RunCMake/CMakeRelease/FileTable-stdout.txt b/Tests/RunCMake/CMakeRelease/FileTable-stdout.txt
new file mode 100644
index 0000000..011673f
--- /dev/null
+++ b/Tests/RunCMake/CMakeRelease/FileTable-stdout.txt
@@ -0,0 +1,44 @@
+^-- query: \.version \| \.major , \.minor , \.patch , \.suffix, \.string
+1
+2
+3
+"rc4"
+"@version@"
+-- query: \.files\[\]\.name
+"cmake-@version@-Linux-aarch64\.sh"
+"cmake-@version@-Linux-aarch64\.tar\.gz"
+"cmake-@version@-Linux-x86_64\.sh"
+"cmake-@version@-Linux-x86_64\.tar\.gz"
+"cmake-@version@-macos-universal\.dmg"
+"cmake-@version@-macos-universal\.tar\.gz"
+"cmake-@version@-macos10\.10-universal\.dmg"
+"cmake-@version@-macos10\.10-universal\.tar\.gz"
+"cmake-@version@-win32-x86\.msi"
+"cmake-@version@-win32-x86\.zip"
+"cmake-@version@-win64-x64\.msi"
+"cmake-@version@-win64-x64\.zip"
+"cmake-@version@\.tar\.gz"
+"cmake-@version@\.zip"
+-- query: \.files\[\] \| select\(\.os\[\] \| \. == "source"\) \| \.name
+"cmake-@version@\.tar\.gz"
+"cmake-@version@\.zip"
+-- query: \.files\[\] \| select\(\(\.os\[\] \| \. == "macOS"\) and \(\.class == "volume"\)\) \| \.name
+"cmake-@version@-macos-universal\.dmg"
+-- query: \.files\[\] \| select\(\(\.os\[\] \| \. == "macos10\.10"\) and \(\.class == "archive"\)\) \| \.name
+"cmake-@version@-macos10\.10-universal\.tar\.gz"
+-- query: \.files\[\] \| select\(\(\.os\[\] \| \. == "windows"\) and \(\.architecture\[\] \| \. == "i386"\) and \(\.class == "installer"\)\) \| \.name
+"cmake-@version@-win32-x86\.msi"
+-- query: \.files\[\] \| select\(\.architecture\[\] \| \. == "x86_64"\) \| \.name
+"cmake-@version@-Linux-x86_64\.sh"
+"cmake-@version@-Linux-x86_64\.tar\.gz"
+"cmake-@version@-macos-universal\.dmg"
+"cmake-@version@-macos-universal\.tar\.gz"
+"cmake-@version@-macos10\.10-universal\.dmg"
+"cmake-@version@-macos10\.10-universal\.tar\.gz"
+"cmake-@version@-win64-x64\.msi"
+"cmake-@version@-win64-x64\.zip"
+-- query: \.files\[\] \| select\(\[\.macOSmin\] \| inside\(\["10\.10", "10\.11", "10\.12"\]\)\) \| \.name
+"cmake-@version@-macos10\.10-universal\.dmg"
+"cmake-@version@-macos10\.10-universal\.tar\.gz"
+-- query: \.hashFiles\[\] \| select\(\.algorithm\[\] \| \. == "SHA-256"\) \| \.name
+"cmake-@version@-SHA-256\.txt"$
diff --git a/Tests/RunCMake/CMakeRelease/FileTable.cmake b/Tests/RunCMake/CMakeRelease/FileTable.cmake
new file mode 100644
index 0000000..f46535c
--- /dev/null
+++ b/Tests/RunCMake/CMakeRelease/FileTable.cmake
@@ -0,0 +1,21 @@
+set(version "@version@")
+set(version_major "1")
+set(version_minor "2")
+set(version_patch "3")
+set(maybe_version_suffix "\"suffix\": \"rc4\",")
+configure_file("${CMAKE_CURRENT_LIST_DIR}/../../../Utilities/Release/files-v1.json.in" "files-v1.json" @ONLY)
+
+foreach(query
+    ".version | .major , .minor , .patch , .suffix, .string"
+    ".files[].name"
+    ".files[] | select(.os[] | . == \"source\") | .name"
+    ".files[] | select((.os[] | . == \"macOS\") and (.class == \"volume\")) | .name"
+    ".files[] | select((.os[] | . == \"macos10.10\") and (.class == \"archive\")) | .name"
+    ".files[] | select((.os[] | . == \"windows\") and (.architecture[] | . == \"i386\") and (.class == \"installer\")) | .name"
+    ".files[] | select(.architecture[] | . == \"x86_64\") | .name"
+    ".files[] | select([.macOSmin] | inside([\"10.10\", \"10.11\", \"10.12\"])) | .name"
+    ".hashFiles[] | select(.algorithm[] | . == \"SHA-256\") | .name"
+    )
+  message(STATUS "query: ${query}")
+  execute_process(COMMAND ${JQ} "${query}" files-v1.json)
+endforeach()
diff --git a/Tests/RunCMake/CMakeRelease/RunCMakeTest.cmake b/Tests/RunCMake/CMakeRelease/RunCMakeTest.cmake
new file mode 100644
index 0000000..9a08ff3
--- /dev/null
+++ b/Tests/RunCMake/CMakeRelease/RunCMakeTest.cmake
@@ -0,0 +1,10 @@
+include(RunCMake)
+
+if(CMake_TEST_JQ)
+  set(JQ "${CMake_TEST_JQ}")
+else()
+  find_program(JQ NAMES jq)
+endif()
+if(JQ)
+  run_cmake_script(FileTable -DJQ=${JQ})
+endif()
diff --git a/Tests/RunCMake/RunCMake.cmake b/Tests/RunCMake/RunCMake.cmake
index 494f87f..ea94a5b 100644
--- a/Tests/RunCMake/RunCMake.cmake
+++ b/Tests/RunCMake/RunCMake.cmake
@@ -215,6 +215,11 @@ function(run_cmake_command test)
   run_cmake(${test})
 endfunction()
 
+function(run_cmake_script test)
+  set(RunCMake_TEST_COMMAND ${CMAKE_COMMAND} ${ARGN} -P ${RunCMake_SOURCE_DIR}/${test}.cmake)
+  run_cmake(${test})
+endfunction()
+
 function(run_cmake_with_options test)
   set(RunCMake_TEST_OPTIONS "${ARGN}")
   run_cmake(${test})
diff --git a/Utilities/Release/README.rst b/Utilities/Release/README.rst
index 5d8e318..dfaf831 100644
--- a/Utilities/Release/README.rst
+++ b/Utilities/Release/README.rst
@@ -6,6 +6,17 @@ on ``cmake.org``.  See also the `CMake Source Code Guide`_.
 
 .. _`CMake Source Code Guide`: ../../Help/dev/source.rst
 
+File Table
+----------
+
+The set of package files distributed on ``cmake.org`` varies by CMake version.
+Clients providing automatic download functionality may query the set of
+package files available using a special file that lists them:
+
+* `File Table v1`_ Documentation
+
+.. _`File Table v1`: files-v1.rst
+
 Docker
 ------
 
diff --git a/Utilities/Release/files-sign.bash b/Utilities/Release/files-sign.bash
new file mode 100755
index 0000000..414859d
--- /dev/null
+++ b/Utilities/Release/files-sign.bash
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -e
+
+gpg --armor --detach-sign cmake-*-SHA-256.txt
diff --git a/Utilities/Release/files-v1.json.in b/Utilities/Release/files-v1.json.in
new file mode 100644
index 0000000..6bafa69
--- /dev/null
+++ b/Utilities/Release/files-v1.json.in
@@ -0,0 +1,106 @@
+{
+  "version": {
+    "major": @version_major@,
+    "minor": @version_minor@,
+    "patch": @version_patch@,
+    @maybe_version_suffix@
+    "string": "@version@"
+  },
+  "files": [
+    {
+      "os": ["linux", "Linux"],
+      "architecture": ["aarch64"],
+      "class": "installer",
+      "name": "cmake-@version@-Linux-aarch64.sh"
+    },
+    {
+      "os": ["linux", "Linux"],
+      "architecture": ["aarch64"],
+      "class": "archive",
+      "name": "cmake-@version@-Linux-aarch64.tar.gz"
+    },
+    {
+      "os": ["linux", "Linux"],
+      "architecture": ["x86_64"],
+      "class": "installer",
+      "name": "cmake-@version@-Linux-x86_64.sh"
+    },
+    {
+      "os": ["linux", "Linux"],
+      "architecture": ["x86_64"],
+      "class": "archive",
+      "name": "cmake-@version@-Linux-x86_64.tar.gz"
+    },
+    {
+      "os": ["macos", "macOS"],
+      "architecture": ["arm64", "x86_64"],
+      "class": "volume",
+      "name": "cmake-@version@-macos-universal.dmg",
+      "macOSmin": "10.13"
+    },
+    {
+      "os": ["macos", "macOS"],
+      "architecture": ["arm64", "x86_64"],
+      "class": "archive",
+      "name": "cmake-@version@-macos-universal.tar.gz",
+      "macOSmin": "10.13"
+    },
+    {
+      "os": ["macos10.10", "macOS10.10"],
+      "architecture": ["arm64", "x86_64"],
+      "class": "volume",
+      "name": "cmake-@version@-macos10.10-universal.dmg",
+      "macOSmin": "10.10"
+    },
+    {
+      "os": ["macos10.10", "macOS10.10"],
+      "architecture": ["arm64", "x86_64"],
+      "class": "archive",
+      "name": "cmake-@version@-macos10.10-universal.tar.gz",
+      "macOSmin": "10.10"
+    },
+    {
+      "os": ["windows", "Windows"],
+      "architecture": ["i386"],
+      "class": "installer",
+      "name": "cmake-@version@-win32-x86.msi"
+    },
+    {
+      "os": ["windows", "Windows"],
+      "architecture": ["i386"],
+      "class": "archive",
+      "name": "cmake-@version@-win32-x86.zip"
+    },
+    {
+      "os": ["windows", "Windows"],
+      "architecture": ["x86_64"],
+      "class": "installer",
+      "name": "cmake-@version@-win64-x64.msi"
+    },
+    {
+      "os": ["windows", "Windows"],
+      "architecture": ["x86_64"],
+      "class": "archive",
+      "name": "cmake-@version@-win64-x64.zip"
+    },
+    {
+      "os": ["source"],
+      "architecture": [],
+      "class": "archive",
+      "name": "cmake-@version@.tar.gz"
+    },
+    {
+      "os": ["source"],
+      "architecture": [],
+      "class": "archive",
+      "name": "cmake-@version@.zip"
+    }
+  ],
+  "hashFiles": [
+    {
+      "algorithm": ["sha256", "SHA-256"],
+      "name": "cmake-@version@-SHA-256.txt",
+      "signature": ["cmake-@version@-SHA-256.txt.asc"]
+    }
+  ]
+}
diff --git a/Utilities/Release/files-v1.rst b/Utilities/Release/files-v1.rst
new file mode 100644
index 0000000..3b916d4
--- /dev/null
+++ b/Utilities/Release/files-v1.rst
@@ -0,0 +1,166 @@
+File Table v1
+*************
+
+The set of package files distributed on ``cmake.org`` varies by CMake version.
+One file, named ``cmake-<ver>-files-v1.json``, contains a table of the package
+files available for a given version.  Clients may use this to find other files.
+
+Format
+------
+
+The format is a JSON object:
+
+.. code-block:: json
+
+  {
+    "version": {
+      "major": 3, "minor": 18, "patch": 6,
+      "string": "3.18.6"
+    },
+    "files": [
+      {
+        "os": ["...", "..."],
+        "architecture": ["...", "..."],
+        "class": "...",
+        "name": "..."
+      }
+    ],
+    "hashFiles": [
+      {
+        "algorithm": ["...", "..."],
+        "name": "cmake-<version>-<algo>.txt",
+        "signature": ["cmake-<version>-<algo>.txt.asc"]
+      }
+    ]
+  }
+
+The members are:
+
+``version``
+  A JSON object specifying the version of CMake with members:
+
+  ``major``, ``minor``, ``patch``
+    Integer values specifying the major, minor, and patch version components.
+
+  ``suffix``
+    A string specifying the version suffix, if any, e.g. ``rc1``.
+
+  ``string``
+    A string specifying the full version in the format
+    ``<major>.<minor>.<patch>[-<suffix>]``.
+
+``files``
+  A JSON array of entries corresponding to available package files.
+  Each entry is a JSON object containing members:
+
+  ``os``
+    A JSON array of strings naming the operating system for which the
+    package file is built, possibly using multiple alternative spellings.
+    Possible names include:
+
+    ``source``
+      Source packages.
+
+    ``Linux``, ``linux``
+      Linux packages.
+
+    ``macOS``, ``macos``
+      macOS packages.
+
+    ``Windows``, ``windows``
+      Windows packages.
+
+  ``architecture``
+    A JSON array of strings naming the architecture(s) for which the
+    package file is built, possibly using multiple alternative spellings.
+    Source packages have an empty list of architectures (``[]``).
+    Binary packages have a non-empty list of architectures, with at least
+    one name matching the output of ``uname -m`` on corresponding hosts.
+    On Windows, architecture names include ``x86_64`` and ``i386``.
+    On macOS, universal binary packages list all architectures,
+    e.g. ``["arm64","x86_64"]``.
+
+  ``class``
+    A JSON string naming the class of package.  The value is one of:
+
+    ``archive``
+      A tarball or zip archive.
+      The extension, such as ``.tar.gz`` or ``.zip``, indicates the format.
+      The rest of the file name matches the top-level directory in the archive.
+
+    ``installer``
+      An interactive installer.
+
+    ``volume``
+      A disk image (``.dmg`` on macOS).
+
+  ``name``
+    A JSON string specifying the name of the package file.
+
+  ``macOSmin``
+    Optional member that is present on package files for macOS.
+    The value is a JSON string specifying the minimum version of macOS
+    required to run the binary, e.g. ``"10.13"``.
+
+``hashFiles``
+  A JSON array of entries corresponding to files containing cryptographic
+  hashes of the package file contents.  Each entry is a JSON object
+  containing members:
+
+  ``algorithm``
+    A JSON array of strings naming a cryptographic hash algorithm, possibly
+    using multiple alternative spellings, e.g. ``["sha256", "SHA-256"]``.
+
+  ``name``
+    A JSON string specifying the name of the file containing hashes,
+    e.g. ``"cmake-<version>-SHA-256.txt"``.
+
+  ``signature``
+    A JSON array of strings naming files containing a cryptographic
+    signature of the hash file specified by ``name``, e.g.
+    ``["cmake-<version>-SHA-256.txt.asc"]``.
+
+The table and hash files are generated by `files.bash`_ from
+the `files-v1.json.in`_ template and the package files themselves.
+
+.. _`files.bash`: files.bash
+.. _`files-v1.json.in`: files-v1.json.in
+
+Queries
+-------
+
+Clients may download the `File Table v1`_ file ``cmake-<ver>-files-v1.json``
+and query it to get the name(s) of specific package files adjacent to it.
+Make queries as specific as possible in order to account for additional
+alternative binaries in future CMake versions.
+
+For example, one may use ``jq`` queries:
+
+* To select a Windows binary archive supporting ``x86_64`` hosts::
+
+    .files[] | select((.os[] | . == "windows") and
+                      (.architecture[] | . == "x86_64") and
+                      (.class == "archive")) | .name
+
+* To select a Linux binary archive supporting ``aarch64`` hosts::
+
+    .files[] | select((.os[] | . == "linux") and
+                      (.architecture[] | . == "aarch64") and
+                      (.class == "archive")) | .name
+
+* To select a macOS binary archive supporting ``arm64`` hosts::
+
+    .files[] | select((.os[] | . == "macos") and
+                      (.architecture[] | . == "arm64") and
+                      (.class == "archive")) | .name
+
+* To select a macOS binary archive supporting macOS 10.12 on ``x86_64`` hosts::
+
+    .files[] | select((.os[] | contains("macOS")) and
+                      (.architecture[] | . == "x86_64") and
+                      ([.macOSmin] | inside(["10.10", "10.11", "10.12"]))
+                      ) | .name
+
+* To select a SHA-256 hash file::
+
+    .hashFiles[] | select(.algorithm[] | . == "SHA-256") | .name
diff --git a/Utilities/Release/files.bash b/Utilities/Release/files.bash
new file mode 100755
index 0000000..28ca8f1
--- /dev/null
+++ b/Utilities/Release/files.bash
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+
+set -e
+
+usage='usage: files.bash [<options>] [--]
+
+Options:
+
+    --version <ver>            CMake <major>.<minor> version number to push.
+                               Defaults to version of source tree.
+'
+
+die() {
+    echo "$@" 1>&2; exit 1
+}
+
+readonly cmake_source_dir="${BASH_SOURCE%/*}/../.."
+
+cmake_version_component()
+{
+  sed -n "
+/^set(CMake_VERSION_${1}/ {s/set(CMake_VERSION_${1} *\([0-9]*\))/\1/;p;}
+" "${cmake_source_dir}/Source/CMakeVersion.cmake"
+}
+
+
+version=''
+while test "$#" != 0; do
+    case "$1" in
+    --version) shift; version="$1" ;;
+    --) shift ; break ;;
+    -*) die "$usage" ;;
+    *) break ;;
+    esac
+    shift
+done
+test "$#" = 0 || die "$usage"
+
+if test -z "$version"; then
+    cmake_version_major="$(cmake_version_component MAJOR)"
+    cmake_version_minor="$(cmake_version_component MINOR)"
+    cmake_version_patch="$(cmake_version_component PATCH)"
+    cmake_version_rc="$(cmake_version_component RC)"
+    version="${cmake_version_major}.${cmake_version_minor}.${cmake_version_patch}"
+    if test -n "$cmake_version_rc"; then
+      version="$version-rc$cmake_version_rc"
+    fi
+fi
+readonly version
+
+IFS='.-' read version_major version_minor version_patch version_suffix <<< "$version"
+readonly version_major
+readonly version_minor
+readonly version_patch
+readonly version_suffix
+
+if test -n "$version_suffix"; then
+  maybe_version_suffix='"suffix": "'"$version_suffix"'",'
+else
+  maybe_version_suffix=''
+fi
+readonly maybe_version_suffix
+
+readonly files_v1_in="${BASH_SOURCE%/*}/files-v1.json.in"
+sed "
+  s/@version@/$version/g
+  s/@version_major@/$version_major/g
+  s/@version_minor@/$version_minor/g
+  s/@version_patch@/$version_patch/g
+  s/@maybe_version_suffix@/$maybe_version_suffix/g
+" "$files_v1_in" \
+  | jq . \
+  > "cmake-$version-files-v1.json"
+
+readonly algos='
+  256
+'
+for algo in $algos; do
+  shasum -a $algo \
+    "cmake-$version-files-v1.json" \
+    $(jq -r '.files[].name' "cmake-$version-files-v1.json") \
+  | LC_ALL=C sort -k 2 \
+  > "cmake-$version-SHA-$algo.txt"
+done