| 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 |