diff options
author | Brad King <brad.king@kitware.com> | 2021-03-30 07:52:36 -0400 |
---|---|---|
committer | Brad King <brad.king@kitware.com> | 2021-04-05 13:43:51 -0400 |
commit | 0237eba318b52720f07b69c3d5df0fcb90c75c66 (patch) | |
tree | 534cc3c97d1da870df96e1c01112de691e3e6177 /Utilities/Release/files-v1.rst | |
parent | fc9c1d83bf23852bfeb280aac2890b5b3fc94414 (diff) | |
download | cmake-0237eba318b52720f07b69c3d5df0fcb90c75c66.tar.gz |
Utilities/Release: Add script to generate a table of files
Fixes: #22002
Diffstat (limited to 'Utilities/Release/files-v1.rst')
-rw-r--r-- | Utilities/Release/files-v1.rst | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/Utilities/Release/files-v1.rst b/Utilities/Release/files-v1.rst new file mode 100644 index 0000000000..4ee50df007 --- /dev/null +++ b/Utilities/Release/files-v1.rst @@ -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 |