1Building Haiku 2========================== 3This is a overview into the process of building HAIKU from source. 4An online version is available at <https://www.haiku-os.org/guides/building/>. 5 6Official releases of Haiku are at <https://www.haiku-os.org/get-haiku>. 7The (unstable) nightly builds are available at <https://download.haiku-os.org/>. 8 9We currently support the following platforms: 10 * Haiku 11 * Linux 12 * FreeBSD 13 * macOS 14 15Required Software 16---------------------------- 17Tools provided within Haiku's repositories: 18 * `jam` (Jam 2.5-haiku-20111222) 19 * Haiku's cross-compiler (needed only for non-Haiku platforms) 20 21The tools to compile Haiku will vary, depending on the platform that you are 22using to build Haiku. When building from Haiku, all of the necessary 23development tools are included in official releases (e.g. R1/alpha4) and in the 24nightly builds. 25 26 * `git` 27 * `gcc`/`g++` and binutils (`as`, `ld`, etc., required by GCC) 28 * (GNU) `make` 29 * `bison` (2.4 or better) 30 * `flex` and `lex` (usually a mini shell script invoking `flex`) 31 * `makeinfo` (part of `texinfo`, only needed for building GCC 4) 32 * `autoheader` (part of `autoconf`, needed for building GCC) 33 * `automake` (needed for building GCC) 34 * `gawk` 35 * `nasm` 36 * `wget` 37 * `[un]zip` 38 * `cdrtools` (preferred) or `genisoimage` 39 * case-sensitive file system 40 41Whether they are installed can be tested by running them in a shell with 42the `--version` parameter. 43 44The following libraries (and their respective headers) are required: 45 * `zlib` 46 47### Haiku for ARM 48If you want to compile Haiku for ARM, you will also need: 49 50 * `mkimage` (<http://www.denx.de/wiki/U-Boot/WebHome>) 51 * Mtools (<https://gnu.org/software/mtools/intro.html>) 52 53### On macOS 54 55Disk Utility can create a case-sensitive disk image of at least 3 GiB in size. 56The following ports need to be installed: 57 * `expat` 58 * `gawk` 59 * `gettext` 60 * `libiconv` 61 * `gsed` 62 * `cdrtools` 63 * `nasm` 64 * `wget` 65 * `less` 66 * `mpfr` 67 * `gmp` 68 * `libmpc` 69 * `bison` (updated to the latest version) 70 71More information about individual distributions of Linux and BSD can be found 72at <https://haiku-os.org/guides/building/pre-reqs>. 73 74Downloading Haiku's sources 75-------------------------------------------------- 76There are two parts to Haiku's sources — the code for Haiku itself and a set 77of build tools for compiling Haiku on an operating system other than Haiku. 78The buildtools are needed only for non-Haiku platforms. 79 80Anonymous checkout: 81``` 82git clone https://git.haiku-os.org/haiku 83git clone https://git.haiku-os.org/buildtools 84``` 85(You can also use the `git://` protocol, but it is not secure). 86 87If you have commit access: 88``` 89git clone ssh://git.haiku-os.org/haiku 90git clone ssh://git.haiku-os.org/buildtools 91``` 92 93Building Jam 94------------------------------------------- 95(*This step applies only to non-Haiku platforms.*) 96 97Change to the `buildtools` folder and run the following commands to 98generate and install `jam`: 99``` 100cd buildtools/jam 101make 102sudo ./jam0 install 103``` 104Or, if you don't want to install `jam` systemwide: 105``` 106./jam0 -sBINDIR=$HOME/bin install 107``` 108 109Configuring the build 110------------------------------------- 111The `configure` script generates a file named `BuildConfig` in the 112`generated/build` directory. As long as `configure` is not modified (!) and the 113cross-compilation tools have not been updated, there is no need to call it again. 114For rebuilding, you only need to invoke `jam` (see below). If you don't 115update the source tree very frequently, you may want to execute `configure` 116after each update just to be on the safe side. 117 118Depending on your goal, there are several different ways to configure Haiku. 119The first way is to call configure from within your Haiku checkout's root. That 120will prepare a folder named 'generated', which will contain the compiled objects. 121Another option is to manually created one or more `generated.*` folders and run 122configure from within them. For example, imagine the following directory setup: 123``` 124buildtools/ 125haiku/ 126haiku/generated.x86gcc2 127``` 128 129### Configure a GCC 2.95/GCC 5 Hybrid, from a non-Haiku platform 130```bash 131cd haiku/generated.x86gcc2 132../configure \ 133 --build-cross-tools x86_gcc2 ../../buildtools/ \ 134 --build-cross-tools x86 135``` 136 137### Configure an x86_64 (GCC 5) build, from a non-Haiku platform 138``` 139cd haiku/generated.x86_64 140../configure --build-cross-tools x86_64 ../../buildtools/ 141``` 142 143### Configure a GCC 2.95/GCC 5 Hybrid, from Haiku 144``` 145cd haiku/generated.x86gcc2 146../configure --target-arch x86_gcc2 --target-arch x86 147``` 148 149Additional information about GCC Hybrids can be found on the website, 150<https://www.haiku-os.org/guides/building/gcc-hybrid>. 151 152### Configure options 153The various runtime options for configure are documented in its onscreen help 154```bash 155./configure --help 156``` 157 158Building via Jam 159---------------------------- 160 161Haiku can be built in either of two ways, as disk image file (e.g. for use 162with emulators, to be written directly to a usb stick, burned as a compact 163disc) or as installation in a directory. 164 165### Running Jam 166 167There are various ways in which you can run `jam`: 168 169 * If you have a single generated folder, you can run 'jam' from the top level of Haiku's trunk. 170 * If you have one or more generated folders, (e.g. generated.x86gcc2), 171 you can `cd` into that directory and run `jam`. 172 * In either case, you can `cd` into a certain folder in the source tree (e.g. 173 src/apps/debugger) and run jam -sHAIKU_OUTPUT_DIR=<path to generated folder> 174 175Be sure to read `build/jam/UserBuildConfig.ReadMe` and `UserBuildConfig.sample`, 176as they contain information on customizing your build of Haiku. 177 178### Building a Haiku anyboot file 179``` 180jam -q @anyboot-image 181``` 182 183This generates an image file named `haiku-anyboot.image` in your output 184directory under `generated/`. 185 186### Building a VMware image file 187``` 188jam -q @vmware-image 189``` 190This generates an image file named `haiku.vmdk` in your output 191directory under `generated/`. 192 193### Directory Installation 194``` 195HAIKU_INSTALL_DIR=/Haiku jam -q @install 196``` 197 198Installs all Haiku components into the volume mounted at "/Haiku" and 199automatically marks it as bootable. To create a partition in the first place 200use DriveSetup and initialize it to BFS. 201 202Note that installing Haiku in a directory only works as expected under Haiku, 203but it is not yet supported under Linux and other non-Haiku platforms. 204 205### Building individual components 206If you don't want to build the complete Haiku, but only a certain 207app/driver/etc. you can specify it as argument to jam, e.g.: 208``` 209jam -q Debugger 210``` 211Alternatively, you can `cd` to the directory of the component you want to 212build and run `jam` from there. **NOTE:** if your generated directory is named 213something other than `generated/`, you will need to tell `jam` where it is: 214``` 215jam -q -sHAIKU_OUTPUT_DIR=<path to generated folder> 216``` 217You can also force the rebuild of a component by using the `-a` parameter: 218``` 219jam -qa Debugger 220``` 221 222Bootstrap Build 223---------------- 224New architectures (and occasionally existing ones) will require a bootstrap 225build to compile *build packages*. (Catch-22 software packages which are needed 226to compile Haiku, but need to be initially compiled under Haiku) 227 228### Pre-requirements 229 * All of the standard tools in the Required Software section above. 230 * The following repositories on disk in the same general location 231 * haiku (https://git.haiku-os.org/haiku) 232 * buildtools (https://git.haiku-os.org/buildtools) 233 * haikuporter (https://github.com/haikuports/haikuporter.git) 234 * haikuports.cross (https://github.com/haikuports/haikuports.cross.git) 235 * haikuports (https://github.com/haikuports/haikuports.git) 236 237### Setting Up a Bootstrap build 238Create a clean build directory under the haiku repo. 239``` 240mkdir generated.myarch && cd generated.myarch 241``` 242 243Configure Haiku's build system for a bootstrap build specifying the location 244of all of the repositories above. 245``` 246../configure -j4 \ 247 --build-cross-tools myarch ../../buildtools \ 248 --bootstrap ../../haikuporter/haikuporter ../../haikuports.cross ../../haikuports 249``` 250 251Once the build system is configured for bootstrap, we now can begin building 252the bootstrap image. 253 254``` 255jam -q @bootstrap-raw 256``` 257 258If you are bootstrapping for an architecture Haiku already boots on, the generated 259disk image can be used to compile *build packages* needed for the standard 260Haiku build. 261 262If you are bootstrapping for a new architecture which doesn't build yet, you will 263need to leverage the ```unbootstrap.sh``` script to hack the generated bootstrap 264packages into non-bootstrap packages which can be temporarily used as 265*build packages*. 266 267Running 268---------------- 269Generally there are two ways of running Haiku: on real hardware using a 270partition, and on emulated hardware using an emulator (like VirtualBox, or QEMU). 271 272### On Real Hardware 273If you have installed Haiku to its own partition you can include this 274partition in your bootmanager and try to boot Haiku like any other OS you 275have installed. To include a new partition in the Haiku bootmanager, start 276the BootManager configurator by running: 277``` 278BootManager 279``` 280 281### On Emulated Hardware 282For emulated hardware you should build a disk image (see above). How to set up 283this image depends on your emulator. If you use QEMU, you can usually just 284provide the path to the image as command line argument to the `qemu` 285executable. 286