Merge topic 'rel-file-table'

e17006c497 Utilities/Release: Add deprecation fields to File Table v1
89ab613248 Utilities/Release: Update file table for 3.20.0
c5777e5421 Merge branch 'backport-3.19-rel-file-table' into rel-file-table
f9f59fb0b2 Merge branch 'release-3.19' into backport-3.19-rel-file-table
30959aec8f Utilities/Release: Update file table for 3.19.3
d206c8f1ec Merge tag 'v3.19.3' into backport-3.19-rel-file-table
004dbbaddd Utilities/Release: Update file table for 3.19.2
1e3301a28c Merge tag 'v3.19.2' into backport-3.19-rel-file-table
...

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Reviewed-by: Craig Scott <craig.scott@crascit.com>
Merge-request: !5961

5 files changed, 392 insertions, 0 deletions

diff --git a/Utilities/Release/README.rst b/Utilities/Release/README.rst
index 5d8e3181e7..dfaf831705 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 0000000000..414859dad6
--- /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 0000000000..aa6b15d900
--- /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@-windows-i386.msi"
+    },
+    {
+      "os": ["windows", "Windows"],
+      "architecture": ["i386"],
+      "class": "archive",
+      "name": "cmake-@version@-windows-i386.zip"
+    },
+    {
+      "os": ["windows", "Windows"],
+      "architecture": ["x86_64"],
+      "class": "installer",
+      "name": "cmake-@version@-windows-x86_64.msi"
+    },
+    {
+      "os": ["windows", "Windows"],
+      "architecture": ["x86_64"],
+      "class": "archive",
+      "name": "cmake-@version@-windows-x86_64.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 0000000000..ceebeccaf0
--- /dev/null
+++ b/Utilities/Release/files-v1.rst
@@ -0,0 +1,186 @@
+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": 20, "patch": 0,
+      "string": "3.20.0"
+    },
+    "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"``.
+
+  ``deprecated``
+    Optional member that is present when the package file is deprecated
+    and may be removed from the set of package files in later versions.
+    The value is a string containing a deprecation message.
+    Clients should check this field to warn users when they are using
+    a deprecated package file.
+
+``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"]``.
+
+  ``deprecated``
+    Optional member that is present when the hash algorithm is deprecated
+    and may be removed from the set of hash files in later versions.
+    The value is a string containing a deprecation message.
+    Clients that rely on a specific hash algorithm should check this
+    field to determine whether an update is needed.
+
+``deprecated``
+  Optional member that is present when `File Table v1`_ has been
+  deprecated in favor of a newer alternative.  The value is a string
+  containing a deprecation message.  Clients should check this field
+  to determine whether they need an update to use a newer alternative.
+
+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 0000000000..28ca8f1b06
--- /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