How to Cross-Compile Haiku from a Linux Host

Haiku’s documented Linux cross-build uses two source repositories, Haiku’s custom Jam, an out-of-tree generated directory, and architecture-specific cross-tools. The exact commands below target x86_64; x86 hybrid, ARM, ARM64, RISC-V, and other ports have separate official guides and image targets.

Prepare a supported Linux build host

Read the current prerequisites page for your distribution and target revision. Install its compiler/build essentials, Git, NASM, flex/bison, texinfo, Python, archive/compression tools, xorriso, zlib/zstd development files, and any listed target-specific packages. Package names change; do not paste an old distro command blindly.

Haiku requires its custom Jam extensions, not a generic distribution Jam. Build it from the official buildtools repository using the prerequisites guide. That guide offers a user-owned BINDIR installation, avoiding root for the build itself. Confirm the resulting jam is first on PATH and reports Haiku’s variant.

Use a case-sensitive filesystem with adequate free space. The official guide recommends proper extended-attribute support; XFS or btrfs are cited for Linux. Configure can emulate attributes where needed, but builds are slower. Do not force --no-xattr routinely: current configure autodetects support and its documentation says the override is not recommended.

Clone and record official sources

Clone buildtools and haiku using the official source guide:

git clone https://review.haiku-os.org/buildtools
git clone https://review.haiku-os.org/haiku

Keep them as siblings for the relative paths below. Record both commit hashes, host distribution, tool versions, and whether local changes exist:

git -C haiku rev-parse HEAD
git -C buildtools rev-parse HEAD
git -C haiku status --short

Update matching branches deliberately. A buildtools revision unsuitable for the Haiku branch can fail before any target code compiles.

Configure x86_64 cross-tools out of tree

From the Haiku source checkout, create a generated directory and run the current documented x86_64 configure command:

cd haiku
mkdir generated.x86_64
cd generated.x86_64
../configure --cross-tools-source ../../buildtools --build-cross-tools x86_64

Adjust paths only if your checkout layout differs. Save configure output. --build-cross-tools x86_64 builds the target toolchain; it is not the same as Haiku-host-only --target-arch.

If configuration fails, fix the first missing prerequisite or path error. Do not combine random configure flags from other architectures. ../configure --help and the official Configure Options page are the revision-relevant references.

Build a bootable image

In the same generated directory, build the standard live/USB ISO:

jam -q -j2 @nightly-anyboot

Choose -j according to available CPU/RAM. -q stops at the first build error, making the originating failure easier to see. The documented raw image alternative is:

jam -q -j2 @nightly-raw

Use the target appropriate to the planned VM/boot medium. Preserve the entire log and generated image name. A successful library target is not proof that its HPKG and final image were rebuilt; boot the artifact produced by the requested profile.

Do not run Jam with sudo. Root-owned generated files cause later failures, and raw-device profiles can be destructive. The normal nightly image targets write regular files in the generated tree.

Diagnose builds without erasing evidence

Read the first error, not the last parallel failure. Confirm disk space, file-system case/xattr behavior, downloaded package availability, compiler path, and exact source commits. Re-run with lower -j or Jam debug output when needed.

Do not immediately delete the generated directory. Jam’s dependency graph and logs can explain whether a target was considered current. Use -a only as the official Jam guide describes; a forced rebuild can hide a missing dependency rule.

For a clean reproducibility check, create a second generated directory with the recorded command rather than mutating the first. Compare image/package manifests and, when deterministic output is expected, checksums.

Boot and validate in a VM

Create a disposable VM configured for x86_64 and attach the anyboot ISO or raw disk according to the hypervisor. Do not write a raw image to a physical disk until it has been verified and the target device is unmistakable.

Boot the live desktop, confirm architecture/revision, inspect expected packages, start core applications, test storage/network, and reproduce the feature the build was meant to change. For boot/kernel work, capture serial or on-screen debug logs.

Keep VM firmware (BIOS/UEFI), virtual chipset/devices, RAM/CPU, host hypervisor version, source hashes, configure command, Jam target, and image checksum with the build report. A boot in one VM proves that artifact/configuration, not every physical machine.

Update safely

Before pulling new source, save local patches and record hashes. Fetch/rebase according to project workflow, rerun configure with --update only as documented for the existing generated tree, and rebuild the full affected artifact. Toolchain updates may require rebuilding cross-tools.

The reproducible workflow is: official matching sources, documented host dependencies, Haiku Jam, automatic xattr handling, explicit configure options, named image target, and real boot verification. That evidence makes a cross-build useful for development rather than merely “Jam returned zero.”

Related:

Sources: