Skip to main content

The binaries definitions

Purpose​

Define the URLs where the binary archives are stored.

Syntax​

{
    ...
    "binaries": {
        "destination": "<relative folder>",
        "baseUrl": "<folder URL>",
        "skip": <number>,
        "platforms": {
            ...
            "<platform name>": {
              "baseUrl": "<folder URL>",
              "fileName": "<full archive name>",
              "sha256": "<sum>"
            },
            ...
        }
    }
}

Description​

To keep packages small, binary xpm packages do not include the platform specific binaries; instead they include only links to the binary archives, and checksums to validate the downloads.

The files are downloaded from <baseUrl>/<fileName>. The common use case is to have all files published in the same folder; in this case it is enough to define baseUrl once. However it is also possible to download files from different folders/servers, by defining it for each platform.

The archives are unpacked in the destination folder, defined as relative to the package root folder (usually ./.content).

To allow the archives to be manually expanded, the build scripts add an initial folder with the package name and version (like xpack-arm-none-eabi-gcc-13.3.1-1.1).

To shorten the paths of extracted files, xpm can skip this folder, or any number of initial levels of folders in the archive, using the skip definition.

Properties​

destination​

The value of the destination property is a string with a path relative to the project top folder.

The path is used in the executables definitions to refer to the applications provided by the package.

The default value is ./.content. However, for readability reasons, it is recommended to explicitly define it with this value.

note

All xPack Development Tools also use ./.content.

baseUrl​

The value of the baseUrl property is a string with the base part of the full URLs. It needs not have a trailing slash.

This value and the fileName are used to determine the full URL.

The baseUrl property can be use either in the top binaries object, when it is used for all platforms, or in any platform object.

skip​

The value of the skip property is an integer, with the number of folders that must be skipped when extracting the files from the archive.

platforms​

The platforms map has members that define the locations of platform specific archives.

The platforms names

The platform names are exactly those defined by Node.js, as process.platform and process.arch:

  • darwin-arm64 - macOS arm64
  • darwin-x64 - macOS x64
  • linux-arm - GNU/Linux Arm 32-bit (since 0.6.0)
  • linux-arm64 - GNU/Linux Arm 64-bit (since 0.6.0)
  • linux-x86 (deprecated)
  • linux-x32 (deprecated)
  • linux-ia32 - GNU/Linux x86 (since 0.6.0; deprecated)
  • linux-x64 - GNU/Linux x64
  • win32-x86 (deprecated)
  • win32-x32 (deprecated)
  • win32-ia32 - Windows x86 (since 0.6.0; deprecated)
  • win32-x64 - Windows x64

(win32 is not very inspired, but we have to live with it.)

fileName​

The value of the fileName property is a string with the name of the archive.

The supported archive extensions are:

  • .tar.gz to be used on macOS and GNU/Linux
  • .zip to be used on Windows

sha256​

The value of the sha256 property is a string containing the SHA hash of the archive.

For security reasons, after downloading the archives, xpm verifies this value and refuses to install the archive if the check fails.

Example​

{
    ...
    "xpack": {
        "minimumXpmRequired": "0.16.3",
        "binaries": {
            "destination": "./.content",
            "baseUrl": "https://github.com/xpack-dev-tools/cmake-xpack/releases/download/v3.28.6-1",
            "skip": 1,
            "platforms": {
                "darwin-arm64": {
                    "fileName": "xpack-cmake-3.28.6-1-darwin-arm64.tar.gz",
                    "sha256": "a2f4f7d4963a3ee41ed3ef80a6dfed1e161b0b33b519fe2c4f11f4d9d310c36e"
                },
                "darwin-x64": {
                    "fileName": "xpack-cmake-3.28.6-1-darwin-x64.tar.gz",
                    "sha256": "bafce78a57bab8c82268b32c0849ab875b437b90bed9bec83aad4c82af320103"
                },
                "linux-arm": {
                    "fileName": "xpack-cmake-3.28.6-1-linux-arm.tar.gz",
                    "sha256": "d73889f852b310f974e20246775eb16b272384dbf6fdc236583395af40bf7b54"
                },
                "linux-arm64": {
                    "fileName": "xpack-cmake-3.28.6-1-linux-arm64.tar.gz",
                    "sha256": "c80bd91b0e2b473d57b0ff30ea6ffc28480576946d6e69b65204f9d26dadfa52"
                },
                "linux-x64": {
                    "fileName": "xpack-cmake-3.28.6-1-linux-x64.tar.gz",
                    "sha256": "b05343bda081b988b2c91896133b56ce286a8269c8550d986cc2e71a243684e1"
                },
                "win32-x64": {
                    "fileName": "xpack-cmake-3.28.6-1-win32-x64.zip",
                    "sha256": "c1c07b1b51e0352e1fb1c9e6d87b743e975484df29f2a72c26d7385ad23fb679"
                }
            }
        },
        ...
    }
}