===================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.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 @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.Further hints:- Of course, as usual, "-j<number>" can be passed to the jam building thebootstrap Haiku. Building the bootstrap third-party packages, which is part ofthis process, will take quite some time anyway. Since those packages are builtsequentially, 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.