{"id":18635766,"url":"https://github.com/xpack-dev-tools/xbb-bootstrap-xpack","last_synced_at":"2026-07-12T21:03:45.056Z","repository":{"id":59404813,"uuid":"536228699","full_name":"xpack-dev-tools/xbb-bootstrap-xpack","owner":"xpack-dev-tools","description":"A binary xPack with tools to bootstrap XBB","archived":false,"fork":false,"pushed_at":"2022-12-24T07:40:15.000Z","size":253,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"xpack","last_synced_at":"2025-10-14T01:36:21.741Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xpack-dev-tools.png","metadata":{"files":{"readme":"README-BUILD.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-13T17:05:52.000Z","updated_at":"2022-10-01T12:23:57.000Z","dependencies_parsed_at":"2023-01-30T20:30:54.413Z","dependency_job_id":null,"html_url":"https://github.com/xpack-dev-tools/xbb-bootstrap-xpack","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/xpack-dev-tools/xbb-bootstrap-xpack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpack-dev-tools%2Fxbb-bootstrap-xpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpack-dev-tools%2Fxbb-bootstrap-xpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpack-dev-tools%2Fxbb-bootstrap-xpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpack-dev-tools%2Fxbb-bootstrap-xpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xpack-dev-tools","download_url":"https://codeload.github.com/xpack-dev-tools/xbb-bootstrap-xpack/tar.gz/refs/heads/xpack","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpack-dev-tools%2Fxbb-bootstrap-xpack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35402753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T05:26:32.238Z","updated_at":"2026-07-12T21:03:45.031Z","avatar_url":"https://github.com/xpack-dev-tools.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# How to build the xPack XBB Bootstrap binaries\n\n## Introduction\n\nThis project also includes the scripts and additional files required to\nbuild and publish the\n[xPack XBB Bootstrap](https://github.com/xpack-dev-tools/xbb-bootstrap-xpack) binaries.\n\nThe build scripts use the\n[xPack Build Box (XBB)](https://xpack.github.io/xbb/),\na set of elaborate build environments based on recent GCC versions\n(Docker containers\nfor GNU/Linux or a custom folder for MacOS).\n\nThere are two types of builds:\n\n- **local/native builds**, which use the tools available on the\n  host machine; generally the binaries do not run on a different system\n  distribution/version; intended mostly for development purposes;\n- **distribution builds**, which create the archives distributed as\n  binaries; expected to run on most modern systems.\n\nThis page documents the distribution builds.\n\nFor native builds, see the `build-native.sh` script.\n\n## Repositories\n\n- \u003chttps://github.com/xpack-dev-tools/xbb-bootstrap-xpack.git\u003e -\n  the URL of the xPack build scripts repository\n- \u003chttps://github.com/xpack-dev-tools/build-helper\u003e - the URL of the\n  xPack build helper, used as the `scripts/helper` submodule.\n- \u003chttps://github.com/xpack-dev-tools/xbb-bootstrap.git\u003e - the URL of the\n  [xPack XBB Bootstrap fork](https://github.com/xpack-dev-tools/xbb-bootstrap)\n\nThe build scripts use the first repo.\n\n### Branches\n\n- `xpack` - the updated content, used during builds\n- `xpack-develop` - the updated content, used during development\n- `master` - empty\n\n## Prerequisites\n\nThe prerequisites are common to all binary builds. Please follow the\ninstructions in the separate\n[Prerequisites for building binaries](https://xpack.github.io/xbb/prerequisites/)\npage and return when ready.\n\nNote: Building the Arm binaries requires an Arm machine.\n\n## Download the build scripts\n\nThe build scripts are available in the `scripts` folder of the\n[`xpack-dev-tools/xbb-bootstrap-xpack`](https://github.com/xpack-dev-tools/xbb-bootstrap-xpack)\nGit repo.\n\nTo download them, issue the following commands:\n\n```sh\nrm -rf ${HOME}/Work/xbb-bootstrap-xpack.git; \\\ngit clone https://github.com/xpack-dev-tools/xbb-bootstrap-xpack.git \\\n  ${HOME}/Work/xbb-bootstrap-xpack.git; \\\ngit -C ${HOME}/Work/xbb-bootstrap-xpack.git submodule update --init --recursive\n```\n\n\u003e Note: the repository uses submodules; for a successful build it is\n\u003e mandatory to recurse the submodules.\n\nFor development purposes, clone the `xpack-develop` branch:\n\n```sh\nrm -rf ${HOME}/Work/xbb-bootstrap-xpack.git; \\\ngit clone \\\n  --branch xpack-develop \\\n  https://github.com/xpack-dev-tools/xbb-bootstrap-xpack.git \\\n  ${HOME}/Work/xbb-bootstrap-xpack.git; \\\ngit -C ${HOME}/Work/xbb-bootstrap-xpack.git submodule update --init --recursive\n```\n\n## The `Work` folder\n\nThe scripts create a temporary build `Work/xbb-bootstrap-${version}` folder in\nthe user home. Although not recommended, if for any reasons you need to\nchange the location of the `Work` folder,\nyou can redefine `WORK_FOLDER_PATH` variable before invoking the script.\n\n## Spaces in folder names\n\nDue to the limitations of `make`, builds started in folders with\nspaces in names are known to fail.\n\nIf on your system the work folder is in such a location, redefine it in a\nfolder without spaces and set the `WORK_FOLDER_PATH` variable before invoking\nthe script.\n\n## Customizations\n\nThere are many other settings that can be redefined via\nenvironment variables. If necessary,\nplace them in a file and pass it via `--env-file`. This file is\neither passed to Docker or sourced to shell. The Docker syntax\n**is not** identical to shell, so some files may\nnot be accepted by bash.\n\n## Versioning\n\nThe version string is semver.\n\n## How to build local/native binaries\n\n### README-DEVELOP.md\n\nThe details on how to prepare the development environment for XBB Bootstrap are in the\n[`README-DEVELOP.md`](https://github.com/xpack-dev-tools/xbb-bootstrap-xpack/blob/xpack/README-DEVELOP.md)\nfile.\n\n## How to build distributions\n\n## Build\n\nThe builds currently run on 5 dedicated machines (Intel GNU/Linux,\nArm 32 GNU/Linux, Arm 64 GNU/Linux, Intel macOS and Arm macOS.\n\n### Build the Intel GNU/Linux and Windows binaries\n\nThe current platform for GNU/Linux and Windows production builds is a\nDebian 11, running on an AMD 5600G PC with 16 GB of RAM\nand 512 GB of fast M.2 SSD. The machine name is `xbbmli`.\n\n```sh\ncaffeinate ssh xbbmli\n```\n\nBefore starting a build, check if Docker is started:\n\n```sh\ndocker info\n```\n\nBefore running a build for the first time, it is recommended to preload the\ndocker images.\n\n```sh\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh preload-images\n```\n\nThe result should look similar to:\n\n```console\n$ docker images\nREPOSITORY       TAG                    IMAGE ID       CREATED         SIZE\nilegeul/ubuntu   amd64-18.04-xbb-v3.4   ace5ae2e98e5   4 weeks ago     5.11GB\n```\n\nIt is also recommended to Remove unused Docker space. This is mostly useful\nafter failed builds, during development, when dangling images may be left\nby Docker.\n\nTo check the content of a Docker image:\n\n```sh\ndocker run --interactive --tty ilegeul/ubuntu:amd64-18.04-xbb-v3.4\n```\n\nTo remove unused files:\n\n```sh\ndocker system prune --force\n```\n\nSince the build takes a while, use `screen` to isolate the build session\nfrom unexpected events, like a broken\nnetwork connection or a computer entering sleep.\n\n```sh\nscreen -S xbb-bootstrap\n\nsudo rm -rf ~/Work/xbb-bootstrap-*-*\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --develop --linux64\n```\n\nor, for development builds:\n\n```sh\nsudo rm -rf ~/Work/xbb-bootstrap-*-*\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --develop --without-html --disable-tests --linux64\n```\n\nTo detach from the session, use `Ctrl-a` `Ctrl-d`; to reattach use\n`screen -r xbb-bootstrap`; to kill the session use `Ctrl-a` `Ctrl-k` and confirm.\n\nAbout 20 minutes later, the output of the build script is a set of 4\narchives and their SHA signatures, created in the `deploy` folder:\n\n```console\n$ ls -l ~/Work/xbb-bootstrap-*-*/deploy\ntotal 13248\n-rw-rw-rw- 1 ilg ilg 3601358 Jun 10 13:45 xpack-xbb-bootstrap-4.0.0-linux-x64.tar.gz\n-rw-rw-rw- 1 ilg ilg     107 Jun 10 13:45 xpack-xbb-bootstrap-4.0.0-linux-x64.tar.gz.sha\n```\n\n### Build the Arm GNU/Linux binaries\n\nThe supported Arm architectures are:\n\n- `armhf` for 32-bit devices\n- `aarch64` for 64-bit devices\n\nThe current platform for Arm GNU/Linux production builds is Raspberry Pi OS,\nrunning on a pair of Raspberry Pi4s, for separate 64/32 binaries.\nThe machine names are `xbbla64` and `xbbla32`.\n\n```sh\ncaffeinate ssh xbbmla\n```\n\nBefore starting a build, check if Docker is started:\n\n```sh\ndocker info\n```\n\nBefore running a build for the first time, it is recommended to preload the\ndocker images.\n\n```sh\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh preload-images\n```\n\nThe result should look similar to:\n\n```console\n$ docker images\nREPOSITORY       TAG                      IMAGE ID       CREATED          SIZE\nhello-world      latest                   46331d942d63   6 weeks ago     9.14kB\nilegeul/ubuntu   arm64v8-18.04-xbb-v3.4   4e7f14f6c886   4 months ago    3.29GB\nilegeul/ubuntu   arm32v7-18.04-xbb-v3.4   a3718a8e6d0f   4 months ago    2.92GB\n```\n\nSince the build takes a while, use `screen` to isolate the build session\nfrom unexpected events, like a broken\nnetwork connection or a computer entering sleep.\n\n```sh\nscreen -S xbb-bootstrap\n\nsudo rm -rf ~/Work/xbb-bootstrap-*-*\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --develop --arm64 --arm32\n```\n\nor, for development builds:\n\n```sh\nsudo rm -rf ~/Work/xbb-bootstrap-*-*\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --develop --without-html --disable-tests --arm64 --arm32\n```\n\nTo detach from the session, use `Ctrl-a` `Ctrl-d`; to reattach use\n`screen -r xbb-bootstrap`; to kill the session use `Ctrl-a` `Ctrl-k` and confirm.\n\nAbout 50 minutes later, the output of the build script is a set of 2\narchives and their SHA signatures, created in the `deploy` folder:\n\n```console\n$ ls -l ~/Work/xbb-bootstrap-*-*/deploy\ntotal 7120\n-rw-rw-rw- 1 ilg ilg 3632743 Mar 26 15:25 xpack-xbb-bootstrap-4.0.0-linux-arm64.tar.gz\n-rw-rw-rw- 1 ilg ilg     109 Mar 26 15:25 xpack-xbb-bootstrap-4.0.0-linux-arm64.tar.gz.sha\n-rw-rw-rw- 1 ilg ilg 3646739 Mar 26 15:50 xpack-xbb-bootstrap-4.0.0-linux-arm.tar.gz\n-rw-rw-rw- 1 ilg ilg     107 Mar 26 15:50 xpack-xbb-bootstrap-4.0.0-linux-arm.tar.gz.sha\n```\n\n### Build the macOS binaries\n\nThe current platforms for macOS production builds are:\n\n- a macOS 10.13.6 running on a MacBook Pro 2011 with 32 GB of RAM and\n  a fast SSD; the machine name is `xbbmi`\n- a macOS 11.6.1 running on a Mac Mini M1 2020 with 16 GB of RAM;\n  the machine name is `xbbma`\n\n```sh\ncaffeinate ssh xbbmi\ncaffeinate ssh xbbma\n```\n\nTo build the latest macOS version:\n\n```sh\nscreen -S xbb-bootstrap\n\nrm -rf ~/Work/xbb-bootstrap-*-*\ncaffeinate bash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --develop --macos\n```\n\nor, for development builds:\n\n```sh\nrm -rf ~/Work/xbb-bootstrap-arm-*-*\ncaffeinate bash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --develop --without-html --disable-tests --macos\n```\n\nTo detach from the session, use `Ctrl-a` `Ctrl-d`; to reattach use\n`screen -r xbb-bootstrap`; to kill the session use `Ctrl-a` `Ctrl-\\` or\n`Ctrl-a` `Ctrl-k` and confirm.\n\nSeveral minutes later, the output of the build script is a compressed\narchive and its SHA signature, created in the `deploy` folder:\n\n```console\n$ ls -l ~/Work/xbb-bootstrap-*-*/deploy\ntotal 5536\n-rw-r--r--  1 ilg  staff  2828202 Jun 10 17:44 xpack-xbb-bootstrap-4.0.0-darwin-x64.tar.gz\n-rw-r--r--  1 ilg  staff      108 Jun 10 17:44 xpack-xbb-bootstrap-4.0.0-darwin-x64.tar.gz.sha\n```\n\n## Subsequent runs\n\n### Separate platform specific builds\n\nInstead of `--all`, you can use any combination of:\n\n```console\n--linux64\n```\n\nOn Arm, instead of `--all`, you can use any combination of:\n\n```console\n--arm64 --arm32\n```\n\n### `clean`\n\nTo remove most build temporary files, use:\n\n```sh\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --all clean\n```\n\nTo also remove the library build temporary files, use:\n\n```sh\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --all cleanlibs\n```\n\nTo remove all temporary files, use:\n\n```sh\nbash ${HOME}/Work/xbb-bootstrap-xpack.git/scripts/helper/build.sh --all cleanall\n```\n\nInstead of `--all`, any combination of `--linux64`\nwill remove the more specific folders.\n\nFor production builds it is recommended to **completely remove the build folder**:\n\n```sh\nrm -rf ~/Work/xbb-bootstrap-*-*\n```\n\n### `--develop`\n\nFor performance reasons, the actual build folders are internal to each\nDocker run, and are not persistent. This gives the best speed, but has\nthe disadvantage that interrupted builds cannot be resumed.\n\nFor development builds, it is possible to define the build folders in\nthe host file system, and resume an interrupted build.\n\nIn addition, the builds are more verbose.\n\n### `--debug`\n\nFor development builds, it is also possible to create everything with\n`-g -O0` and be able to run debug sessions.\n\n### --jobs\n\nBy default, the build steps use all available cores. If, for any reason,\nparallel builds fail, it is possible to reduce the load.\n\n### Interrupted builds\n\nThe Docker scripts may run with root privileges. This is generally not a\nproblem, since at the end of the script the output files are reassigned\nto the actual user.\n\nHowever, for an interrupted build, this step is skipped, and files in\nthe install folder will remain owned by root. Thus, before removing\nthe build folder, it might be necessary to run a recursive `chown`.\n\n## Testing\n\nA simple test is performed by the script at the end, by launching the\nexecutables to check if all shared/dynamic libraries are correctly used.\n\nFor a true test you need to unpack the archive in a temporary location\n(like `~/Downloads`) and then run the\nprogram from there. For example on macOS the output should\nlook like:\n\n```console\n$ .../xpack-xbb-bootstrap-4.0.0/bin/xxx\n...\n```\n\n## Installed folders\n\nAfter install, the package should create a structure like this (macOS files;\nonly the first two depth levels are shown):\n\n```console\n$ tree -L 2 /Users/ilg/Library/xPacks/\\@xpack-dev-tools/xbb-bootstrap/4.0.0/.content/\n/Users/ilg/Library/xPacks/\\@xpack-dev-tools/xbb-bootstrap/4.0.0/.content/\n...\n```\n\nNo other files are installed in any system folders or other locations.\n\n## Uninstall\n\nThe binaries are distributed as portable archives; thus they do not need\nto run a setup and do not require an uninstall; simply removing the\nfolder is enough.\n\n## Files cache\n\nThe XBB build scripts use a local cache such that files are downloaded only\nduring the first run, later runs being able to use the cached files.\n\nHowever, occasionally some servers may not be available, and the builds\nmay fail.\n\nThe workaround is to manually download the files from an alternate\nlocation (like\n\u003chttps://github.com/xpack-dev-tools/files-cache/tree/master/libs\u003e),\nplace them in the XBB cache (`Work/cache`) and restart the build.\n\n## More build details\n\nThe build process is split into several scripts. The build starts on\nthe host, with `build.sh`, which runs `container-build.sh` several\ntimes, once for each target, in one of the two docker containers.\nBoth scripts include several other helper scripts. The entire process\nis quite complex, and an attempt to explain its functionality in a few\nwords would not be realistic. Thus, the authoritative source of details\nremains the source code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpack-dev-tools%2Fxbb-bootstrap-xpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxpack-dev-tools%2Fxbb-bootstrap-xpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpack-dev-tools%2Fxbb-bootstrap-xpack/lists"}