1=================== 2Bootstrapping Haiku 3=================== 4 5Even a very basic Haiku requires a set of third-party packages (ICU, zlib,...), 6a Haiku sufficiently complete to build software even more 7(binutils, gcc, make,...). So whenever something fundamental in Haiku 8(the architecture ABI, the ABI of libroot) changes in a binary incompatible way, 9or when Haiku is ported to a new architecture, it is necessary to bootstrap 10Haiku and a basic set of required third-party packages. This document describes 11how this process works. 12 13Prerequisites 14============= 15 16- So far the bootstrap build has only been tested on Linux. It will probably 17 also work on FreeBSD and other Unixes. Haiku is not yet supported as a build 18 platform. 19- A required prerequisite for the bootstrap build is a checkout of the 20 haikuporter, the haikuports, and the haikuports.cross repositories from the 21 `Github HaikuPorts site`_. 22 23 .. _Github HaikuPorts site: https://github.com/haikuports/ 24 25- Additional build tools are required for the build platform: 26 27 - autoconf 28 - automake 29 - cmake (For compiling python_bootstrap) 30 - ncurses_development (For compiling texinfo_bootstrap) 31 32- All the usual prerequisites for building Haiku. 33 34Configuring and Building 35======================== 36 371. Configure the Haiku build with all usual parameters, but add the 38 ``--bootstrap`` option with its three parameters, the paths to the checked 39 out haikuporter *script* (eg. ``../haikuporter/haikuporter``), 40 haikuports.cross, and haikuports repositories folders:: 41 42 .../configure ... --bootstrap path/to/haikuporter path/to/haikuports.cross path/to/haikuports 43 44 It is important that you build outside the tree, as otherwise the build will 45 fail! 46#. Build a bootstrap Haiku image:: 47 48 jam -q @bootstrap-raw 49 50#. Boot the bootstrap Haiku (e.g. in a virtual machine), edit the file 51 "/boot/home/haikuports/haikuports.config" -- entering your email address in 52 the "PACKAGER" field -- and finally open a Terminal and build the third-party 53 packages:: 54 55 cd haikuports 56 haikuporter --do-bootstrap 57 58In the "packages" subdirectory the built packages are collected. This is the 59initial set of packages for the HaikuPorts packages repository, plus the source 60packages the Haiku build system put in your generated directory under 61"objects/haiku/<arch>/packaging/repositories/HaikuPorts-sources-build/packages" 62(ignore the "rigged" source packages). With these packages a HaikuPorts package 63repository can be built and in turn a regular Haiku can be built using it. 64Further packages can then be built on the regular Haiku. 65 66Further hints: 67 68- Of course, as usual, "-j<number>" can be passed to the jam building the 69 bootstrap Haiku. Building the bootstrap third-party packages, which is part of 70 this process, will take quite some time anyway. Since those packages are built 71 sequentially, the jam variable "HAIKU_PORTER_CONCURRENT_JOBS" can be defined 72 to the number of jobs that shall be used to build a package. 73- Instead of "bootstrap-raw" the build profile "bootstrap-vmware" can be used as 74 well. You can also define your own build profile, e.g. for building to a 75 partition. As long as its name starts with "bootstrap-" that will result in a 76 bootstrap Haiku. 77- ``haikuporter`` also supports the "-j<number>" option to specify the number of 78 jobs to use. Even on real hardware this step will nevertheless take a long 79 time. 80- The jam variable HAIKU_PORTER_EXTRA_OPTIONS can be defined to any options that 81 should be passed to ``haikuporter`` (``--debug`` is handy for showing python 82 strack traces, for instance). 83 84How it works 85============ 86Building the bootstrap Haiku image is in principle quite similar to building a 87regular Haiku image, save for the following differences: 88 89- Some parts of a regular Haiku that aren't needed for building packages are 90 omitted (e.g. the Demos, MediaPlayer, the OpenGL API,...). 91- Certain third-party packages that aren't needed for building packages are 92 omitted as well. 93- The third-party packages are not downloaded from some package repository. 94 Instead for each package a bootstrap version is built from the sources using 95 ``haikuporter`` and the respective build recipe from haikuports.cross. 96- ``haikuporter`` itself and ready-to-build ("rigged") source packages for all 97 needed final third-party packages are copied to the image. 98 99Obviously the last two points are the juicy parts. Building a bootstrap 100third-party package -- unless it is a pure data package -- requires certain 101parts of Haiku; usually the headers, libroot and other libraries, and the glue 102code. For some Haiku libraries we do already need certain third-party packages. 103So there's a bit of ping pong going on: 104 105- Initially the build system builds a package 106 "haiku_cross_devel_sysroot_stage1_<arch>.hpkg". It contains the essentials for 107 cross-compiling bootstrap third-party packages, but nothing that itself 108 depends on a third-party package. 109- Once all third-party packages required for it have been built, a more complete 110 "haiku_cross_devel_sysroot_<arch>.hpkg" is built. It is used to cross-compile 111 the remaining third-party packages. 112 113The rigged source packages (and regular source packages) are built via 114``haikuporter`` from the regular haikuports repository checkout. haikuports 115contains build recipes for a lot of software. Which source packages should be 116built is determined by the build system by checking what packages are needed for 117the target build profile used by the bootstrap process. This defaults to 118"minimum-raw", but it can be changed by setting the jam variable 119"HAIKU_BOOTSTRAP_SOURCES_PROFILE" 120(i.e. ``jam -sHAIKU_BOOTSTRAP_SOURCES_PROFILE=@release-raw -q @bootstrap-raw`` 121will include source packages for all packages needed by release image). 122 123Format of hpkg Source Repository 124================================ 125 126For Haikuporter to use source or "rigged" packages instead of requesting 127packages from a remote url (essential during bootstrap when patch, git, 128curl, etc are unavailable), haikuporter works on an empty haikuports repository 129with the following layout: 130 131- haikuports/input-source-packages 132 Contains all input source (or source_rigged) hpkgs 133- haikuports/FormatVersions 134 Contains ``RecipeFormatVersion=1`` so haikuporter can identify the haikuports 135 repository 136 137After ``haikuporter`` is given this directory structure, it will parse the 138source or "rigged" packages, and allow you to build them internally replacing 139the SOURCE_URI with ``pkg:input-source-packages/`` 140 141This process is generally automated during the generation of the bootstrap 142image, but manual setup may be needed if the bootstrap image is non-functional 143on your target platform. 144 145Haiku Architecture Ports 146======================== 147 148When preparing a new Haiku architecture port for the bootstrap build the 149following things need to be considered: 150 151- There need to be repository definitions 152 "build/jam/repositories/HaikuPorts/<arch>" and 153 "build/jam/repositories/HaikuPortsCross/<arch>". The former lists the packages 154 available for a regular Haiku, i.e. it must include at least the packages 155 needed for a basic Haiku image that can build third-party packages. The latter 156 lists the available bootstrap third-party packages. 157- There needs to be "src/data/package_infos/<arch>/haiku", a package info for 158 the Haiku system package (currently also used for the bootstrap package). 159- In the haikuports.cross repository all build recipes need to support the 160 architecture (the architecture must be listed in the "ARCHITECTURES" 161 variable). Some software may need to be patched for cross-building to work for 162 the architecture. 163- In the haikuports repository all build recipes for required software need to 164 support the architecture. 165 166If the Haiku architecture port doesn't support a working userland yet, the 167process obviously cannot go further than building the bootstrap Haiku image. 168