diff options
Diffstat (limited to 'Utilities/Release/files-v1.rst')
| -rw-r--r-- | Utilities/Release/files-v1.rst | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/Utilities/Release/files-v1.rst b/Utilities/Release/files-v1.rst new file mode 100644 index 0000000000..f0064e8d21 --- /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``, ``i386``, and ``arm64``. + 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 |