|
|
@@ -0,0 +1,157 @@
|
|
|
+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``.
|
|
|
+
|
|
|
+ ``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.7"``.
|
|
|
+
|
|
|
+``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 ``x86_64`` hosts::
|
|
|
+
|
|
|
+ .files[] | select((.os[] | . == "linux") and
|
|
|
+ (.architecture[] | . == "x86_64") and
|
|
|
+ (.class == "archive")) | .name
|
|
|
+
|
|
|
+* To select a macOS binary archive supporting ``x86_64`` hosts::
|
|
|
+
|
|
|
+ .files[] | select((.os[] | . == "macos") and
|
|
|
+ (.architecture[] | . == "x86_64") and
|
|
|
+ (.class == "archive")) | .name
|
|
|
+
|
|
|
+* To select a SHA-256 hash file::
|
|
|
+
|
|
|
+ .hashFiles[] | select(.algorithm[] | . == "SHA-256") | .name
|
Brad King