CMake/Utilities/Release/files-v1.rst

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