Utilities/Release/files-v1.rst

   1 File Table v1
   2 *************
   3
   4 The set of package files distributed on ``cmake.org`` varies by CMake version.
   5 One file, named ``cmake-<ver>-files-v1.json``, contains a table of the package
   6 files available for a given version.  Clients may use this to find other files.
   7
   8 Format
   9 ------
  10
  11 The format is a JSON object:
  12
  13 .. code-block:: json
  14
  15   {
  16     "version": {
  17       "major": 3, "minor": 20, "patch": 0,
  18       "string": "3.20.0"
  19     },
  20     "files": [
  21       {
  22         "os": ["...", "..."],
  23         "architecture": ["...", "..."],
  24         "class": "...",
  25         "name": "..."
  26       }
  27     ],
  28     "hashFiles": [
  29       {
  30         "algorithm": ["...", "..."],
  31         "name": "cmake-<version>-<algo>.txt",
  32         "signature": ["cmake-<version>-<algo>.txt.asc"]
  33       }
  34     ]
  35   }
  36
  37 The members are:
  38
  39 ``version``
  40   A JSON object specifying the version of CMake with members:
  41
  42   ``major``, ``minor``, ``patch``
  43     Integer values specifying the major, minor, and patch version components.
  44
  45   ``suffix``
  46     A string specifying the version suffix, if any, e.g. ``rc1``.
  47
  48   ``string``
  49     A string specifying the full version in the format
  50     ``<major>.<minor>.<patch>[-<suffix>]``.
  51
  52 ``files``
  53   A JSON array of entries corresponding to available package files.
  54   Each entry is a JSON object containing members:
  55
  56   ``os``
  57     A JSON array of strings naming the operating system for which the
  58     package file is built, possibly using multiple alternative spellings.
  59     Possible names include:
  60
  61     ``source``
  62       Source packages.
  63
  64     ``Linux``, ``linux``
  65       Linux packages.
  66
  67     ``macOS``, ``macos``
  68       macOS packages.
  69
  70     ``Windows``, ``windows``
  71       Windows packages.
  72
  73   ``architecture``
  74     A JSON array of strings naming the architecture(s) for which the
  75     package file is built, possibly using multiple alternative spellings.
  76     Source packages have an empty list of architectures (``[]``).
  77     Binary packages have a non-empty list of architectures, with at least
  78     one name matching the output of ``uname -m`` on corresponding hosts.
  79     On Windows, architecture names include ``x86_64``, ``i386``, and ``arm64``.
  80     On macOS, universal binary packages list all architectures,
  81     e.g. ``["arm64","x86_64"]``.
  82
  83   ``class``
  84     A JSON string naming the class of package.  The value is one of:
  85
  86     ``archive``
  87       A tarball or zip archive.
  88       The extension, such as ``.tar.gz`` or ``.zip``, indicates the format.
  89       The rest of the file name matches the top-level directory in the archive.
  90
  91     ``installer``
  92       An interactive installer.
  93
  94     ``volume``
  95       A disk image (``.dmg`` on macOS).
  96
  97   ``name``
  98     A JSON string specifying the name of the package file.
  99
 100   ``macOSmin``
 101     Optional member that is present on package files for macOS.
 102     The value is a JSON string specifying the minimum version of macOS
 103     required to run the binary, e.g. ``"10.13"``.
 104
 105   ``deprecated``
 106     Optional member that is present when the package file is deprecated
 107     and may be removed from the set of package files in later versions.
 108     The value is a string containing a deprecation message.
 109     Clients should check this field to warn users when they are using
 110     a deprecated package file.
 111
 112 ``hashFiles``
 113   A JSON array of entries corresponding to files containing cryptographic
 114   hashes of the package file contents.  Each entry is a JSON object
 115   containing members:
 116
 117   ``algorithm``
 118     A JSON array of strings naming a cryptographic hash algorithm, possibly
 119     using multiple alternative spellings, e.g. ``["sha256", "SHA-256"]``.
 120
 121   ``name``
 122     A JSON string specifying the name of the file containing hashes,
 123     e.g. ``"cmake-<version>-SHA-256.txt"``.
 124
 125   ``signature``
 126     A JSON array of strings naming files containing a cryptographic
 127     signature of the hash file specified by ``name``, e.g.
 128     ``["cmake-<version>-SHA-256.txt.asc"]``.
 129
 130   ``deprecated``
 131     Optional member that is present when the hash algorithm is deprecated
 132     and may be removed from the set of hash files in later versions.
 133     The value is a string containing a deprecation message.
 134     Clients that rely on a specific hash algorithm should check this
 135     field to determine whether an update is needed.
 136
 137 ``deprecated``
 138   Optional member that is present when `File Table v1`_ has been
 139   deprecated in favor of a newer alternative.  The value is a string
 140   containing a deprecation message.  Clients should check this field
 141   to determine whether they need an update to use a newer alternative.
 142
 143 The table and hash files are generated by `files.bash`_ from
 144 the `files-v1.json.in`_ template and the package files themselves.
 145
 146 .. _`files.bash`: files.bash
 147 .. _`files-v1.json.in`: files-v1.json.in
 148
 149 Queries
 150 -------
 151
 152 Clients may download the `File Table v1`_ file ``cmake-<ver>-files-v1.json``
 153 and query it to get the name(s) of specific package files adjacent to it.
 154 Make queries as specific as possible in order to account for additional
 155 alternative binaries in future CMake versions.
 156
 157 For example, one may use ``jq`` queries:
 158
 159 * To select a Windows binary archive supporting ``x86_64`` hosts::
 160
 161     .files[] | select((.os[] | . == "windows") and
 162                       (.architecture[] | . == "x86_64") and
 163                       (.class == "archive")) | .name
 164
 165 * To select a Linux binary archive supporting ``aarch64`` hosts::
 166
 167     .files[] | select((.os[] | . == "linux") and
 168                       (.architecture[] | . == "aarch64") and
 169                       (.class == "archive")) | .name
 170
 171 * To select a macOS binary archive supporting ``arm64`` hosts::
 172
 173     .files[] | select((.os[] | . == "macos") and
 174                       (.architecture[] | . == "arm64") and
 175                       (.class == "archive")) | .name
 176
 177 * To select a macOS binary archive supporting macOS 10.12 on ``x86_64`` hosts::
 178
 179     .files[] | select((.os[] | contains("macOS")) and
 180                       (.architecture[] | . == "x86_64") and
 181                       ([.macOSmin] | inside(["10.10", "10.11", "10.12"]))
 182                       ) | .name
 183
 184 * To select a SHA-256 hash file::
 185
 186     .hashFiles[] | select(.algorithm[] | . == "SHA-256") | .name