===================Bootstrapping Haiku===================Even a very basic Haiku requires a set of third-party packages (ICU, zlib,...),a Haiku sufficiently complete to build software even more(binutils, gcc, make,...). So, whenever something fundamental in Haiku(the architecture ABI, the ABI of libroot) changes in a binary incompatible way,or when Haiku is ported to a new architecture, it is necessary to bootstrapHaiku and a basic set of required third-party packages. This document describeshow this process works.Prerequisites=============- So far the bootstrap build has only been tested on Linux. It will probablyalso work on FreeBSD and other Unixes. Haiku is not yet supported as a buildplatform.- A required prerequisite for the bootstrap build is a checkout of thehaikuporter, the haikuports, and the haikuports.cross repositories from the`Github HaikuPorts site`_... _Github HaikuPorts site: https://github.com/haikuports/- Additional build tools are required for the build platform:- autoconf- automake- cmake (For compiling python_bootstrap)- ncurses_development (For compiling texinfo_bootstrap)- All the usual prerequisites for building Haiku.The process is not extremely well tested, and may fail in unexpected ways dueto minor differences in the host machine configuration. Until all these issuesare discovered and resolved, here is a list of systems where the bootstrappingis known to mostly work:- x86_64, Debian 12 host.Configuring and Building========================1. Configure the Haiku build with all usual parameters, but add the``--bootstrap`` option with its three parameters, the paths to the checkedout haikuporter *script* (eg. ``../haikuporter/haikuporter``),haikuports.cross, and haikuports repositories folders::.../configure ... --bootstrap path/to/haikuporter path/to/haikuports.cross path/to/haikuportsIt is important that you build outside the tree, as otherwise the build willfail!#. Build a bootstrap Haiku image::jam -q -sHAIKU_PORTER_CONCURRENT_JOBS=4 @bootstrap-raw#. Boot the bootstrap Haiku (e.g. in a virtual machine), edit the file"/boot/home/haikuports/haikuports.config" -- entering your email address inthe "PACKAGER" field -- and finally open a Terminal and build the third-partypackages::cd haikuportshaikuporter --do-bootstrapIn the "packages" subdirectory the built packages are collected. This is theinitial set of packages for the HaikuPorts packages repository, plus the sourcepackages the Haiku build system put in your generated directory under"objects/haiku/<arch>/packaging/repositories/HaikuPorts-sources-build/packages"(ignore the "rigged" source packages). With these packages a HaikuPorts packagerepository can be built and in turn a regular Haiku can be built using it.Further packages can then be built on the regular Haiku.Known problems:- Running the configure script inside of the Haiku source directory is notsupported for bootstrap builds. Use an out-of tree generated directory instead.- When running jam for bootstrap, the -j option is broken. It will result instarting multiple instances of Haikuporter that will all try to generate thepackage infos files from the repository at the same file, and will confuseeach other. You can either run a single-process build, or re-run jam if thereis a build failure to see if it will go further.- Using mksh as your shell will not work when doing a bootstrap build. The mostwell tested shell is bash, other shells may or may not work.Further hints:- The jam variable "HAIKU_PORTER_CONCURRENT_JOBS" can be definedto the number of jobs that shall be used to build a package.- Instead of "bootstrap-raw" the build profile "bootstrap-vmware" can be used aswell. You can also define your own build profile, e.g. for building to apartition. As long as its name starts with "bootstrap-" that will result in abootstrap Haiku.- ``haikuporter`` also supports the "-j<number>" option to specify the number ofjobs to use. Even on real hardware this step will nevertheless take a longtime.- The jam variable HAIKU_PORTER_EXTRA_OPTIONS can be defined to any options thatshould be passed to ``haikuporter`` (``--debug`` is handy for showing pythonstrack traces, for instance).How it works============Building the bootstrap Haiku image is in principle quite similar to building aregular Haiku image, save for the following differences:- Some parts of a regular Haiku that aren't needed for building packages areomitted (e.g. the Demos, MediaPlayer, the OpenGL API,...).- Certain third-party packages that aren't needed for building packages areomitted as well.- The third-party packages are not downloaded from some package repository.Instead for each package a bootstrap version is built from the sources using``haikuporter`` and the respective build recipe from haikuports.cross.- ``haikuporter`` itself and ready-to-build ("rigged") source packages for allneeded final third-party packages are copied to the image.Obviously the last two points are the juicy parts. Building a bootstrapthird-party package -- unless it is a pure data package -- requires certainparts of Haiku; usually the headers, libroot and other libraries, and the gluecode. For some Haiku libraries we do already need certain third-party packages.So there's a bit of ping pong going on:- Initially the build system builds a package"haiku_cross_devel_sysroot_stage1_<arch>.hpkg". It contains the essentials forcross-compiling bootstrap third-party packages, but nothing that itselfdepends on a third-party package.- Once all third-party packages required for it have been built, a more complete"haiku_cross_devel_sysroot_<arch>.hpkg" is built. It is used to cross-compilethe remaining third-party packages.The rigged source packages (and regular source packages) are built via``haikuporter`` from the regular haikuports repository checkout. haikuportscontains build recipes for a lot of software. Which source packages should bebuilt is determined by the build system by checking what packages are needed forthe target build profile used by the bootstrap process. This defaults to"minimum-raw", but it can be changed by setting the jam variable"HAIKU_BOOTSTRAP_SOURCES_PROFILE"(i.e. ``jam -sHAIKU_BOOTSTRAP_SOURCES_PROFILE=@release-raw -q @bootstrap-raw``will include source packages for all packages needed by release image).Format of hpkg Source Repository================================For Haikuporter to use source or "rigged" packages instead of requestingpackages from a remote url (essential during bootstrap when patch, git,curl, etc are unavailable), haikuporter works on an empty haikuports repositorywith the following layout:- haikuports/input-source-packagesContains all input source (or source_rigged) hpkgs- haikuports/FormatVersionsContains ``RecipeFormatVersion=1`` so haikuporter can identify the haikuportsrepositoryAfter ``haikuporter`` is given this directory structure, it will parse thesource or "rigged" packages, and allow you to build them internally replacingthe SOURCE_URI with ``pkg:input-source-packages/``This process is generally automated during the generation of the bootstrapimage, but manual setup may be needed if the bootstrap image is non-functionalon your target platform.Haiku Architecture Ports========================When preparing a new Haiku architecture port for the bootstrap build thefollowing things need to be considered:- There need to be repository definitions"build/jam/repositories/HaikuPorts/<arch>" and"build/jam/repositories/HaikuPortsCross/<arch>". The former lists the packagesavailable for a regular Haiku, i.e. it must include at least the packagesneeded for a basic Haiku image that can build third-party packages. The latterlists the available bootstrap third-party packages.- There needs to be "src/data/package_infos/<arch>/haiku", a package info forthe Haiku system package (currently also used for the bootstrap package).- In the haikuports.cross repository all build recipes need to support thearchitecture (the architecture must be listed in the "ARCHITECTURES"variable). Some software may need to be patched for cross-building to work forthe architecture.- In the haikuports repository all build recipes for required software need tosupport the architecture.If the Haiku architecture port doesn't support a working userland yet, theprocess obviously cannot go further than building the bootstrap Haiku image.In this case, it is possible to use the "unbootstrap" script to convert thebootstrap packages into regular ones, to generate a first version of the binarypackage repository. This allows to work on the bringup of the new architectureusing non-bootstrap builds, which are better documented and tested. Once thearchitecture is in a bootable state, bootstrapping can be completed fully, andthe properly built packages will then replace the initial set.Rules for updating haikuports.cross===================================The bootstrapping process being complex and having a lot of moving parts, it'seasy to accidentally break one architecture while working on another. If youneed to make changes to haikuports.cross, for example to update one package,be sure to only do so for the architectures you are testing with (that is,avoid using the "all" architecture or adding architectures to your new recipethat you have not actually tested).Once your new recipe is merged, other architectures can be added to it as theyare tested.Try to keep changes to a minimum: it's not really needed to use the very latestversion of everything. Having something that is tested and working is moreimportant. Once you have the bootstrap image booting, you will be able to use itto build more up to date versions of packages. If you want to make updates tohaikuports.cross to run newer versions of software, try to do it so that allarchitectures are following each other, to avoid having to maintain a differentversion of each recipe for each architecture.