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 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/beta1) 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 * `xorriso` 39 * `mtools` (<https://gnu.org/software/mtools/intro.html>) 40 * case-sensitive file system 41 42Whether they are installed can be tested by running them in a shell with 43the `--version` parameter. 44 45The following libraries (and their respective headers) are required: 46 * `zlib` 47 48### Haiku for ARM 49If you want to compile Haiku for ARM, you will also need: 50 51 * `mkimage` (<http://www.denx.de/wiki/U-Boot/WebHome>) 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://review.haiku-os.org/haiku.git 83git clone https://review.haiku-os.org/buildtools.git 84``` 85 86If you have commit access: 87``` 88git clone ssh://git.haiku-os.org/haiku 89git clone ssh://git.haiku-os.org/buildtools 90``` 91 92Building Jam 93------------------------------------------- 94(*This step applies only to non-Haiku platforms. Haiku already ships with the correct version of Jam*) 95 96Change to the `buildtools` folder and run the following commands to 97generate and install `jam`: 98``` 99cd buildtools/jam 100make 101sudo ./jam0 install 102``` 103Or, if you don't want to install `jam` systemwide: 104``` 105./jam0 -sBINDIR=$HOME/bin install 106``` 107 108Configuring the build 109------------------------------------- 110The `configure` script generates a file named `BuildConfig` in the 111`generated/build` directory. As long as `configure` is not modified (!) and the 112cross-compilation tools have not been updated, there is no need to call it again. 113For rebuilding, you only need to invoke `jam` (see below). If you don't 114update the source tree very frequently, you may want to execute `configure` 115after each update just to be on the safe side. 116 117Depending on your goal, there are several different ways to configure Haiku. 118The first way is to call configure from within your Haiku checkout's root. That 119will prepare a folder named 'generated', which will contain the compiled objects. 120Another option is to manually created one or more `generated.*` folders and run 121configure from within them. For example, imagine the following directory setup: 122``` 123buildtools/ 124haiku/ 125haiku/generated.x86gcc2 126``` 127 128### Configure an x86_64 (GCC 8) build 129```bash 130cd haiku/generated.x86_64 131../configure --build-cross-tools x86_64 ../../buildtools/ 132``` 133 134### Configure a 32-bit GCC 2.95/GCC 8 Hybrid, from a non-Haiku platform 135```bash 136cd haiku/generated.x86gcc2 137../configure \ 138 --build-cross-tools x86_gcc2 ../../buildtools/ \ 139 --build-cross-tools x86 140``` 141 142### Configure a 32-bit GCC 2.95/GCC 8 Hybrid, from Haiku 143```bash 144cd haiku/generated.x86gcc2 145../configure --target-arch x86_gcc2 --target-arch x86 146``` 147 148Additional information about GCC Hybrids can be found on the website, 149<https://www.haiku-os.org/guides/building/gcc-hybrid>. 150 151### Configure options 152The various runtime options for configure are documented in its onscreen help 153```bash 154./configure --help 155``` 156 157Building via Jam 158---------------------------- 159 160Haiku can be built in either of two ways, as disk image file (e.g. for use 161with emulators, to be written directly to a usb stick, burned as a compact 162disc) or as installation in a directory. 163 164### Running Jam 165 166There are various ways in which you can run `jam`: 167 168 * If you have a single generated folder, you can run 'jam' from the top level of Haiku's trunk. 169 * If you have one or more generated folders, (e.g. generated.x86gcc2), 170 you can `cd` into that directory and run `jam`. 171 * In either case, you can `cd` into a certain folder in the source tree (e.g. 172 src/apps/debugger) and run jam -sHAIKU_OUTPUT_DIR=<path to generated folder> 173 174Be sure to read `build/jam/UserBuildConfig.ReadMe` and `UserBuildConfig.sample`, 175as they contain information on customizing your build of Haiku. 176 177### Building a Haiku anyboot file 178``` 179jam -q @anyboot-image 180``` 181 182This generates an image file named `haiku-anyboot.image` in your output 183directory under `generated/`. 184 185### Building a VMware image file 186``` 187jam -q @vmware-image 188``` 189This generates an image file named `haiku.vmdk` in your output 190directory under `generated/`. 191 192### Directory Installation 193``` 194HAIKU_INSTALL_DIR=/Haiku jam -q @install 195``` 196 197Installs all Haiku components into the volume mounted at "/Haiku" and 198automatically marks it as bootable. To create a partition in the first place 199use DriveSetup and initialize it to BFS. 200 201Note that installing Haiku in a directory only works as expected under Haiku, 202but it is not yet supported under Linux and other non-Haiku platforms. 203 204### Building individual components 205If you don't want to build the complete Haiku, but only a certain 206app/driver/etc. you can specify it as argument to jam, e.g.: 207``` 208jam -q Debugger 209``` 210Alternatively, you can `cd` to the directory of the component you want to 211build and run `jam` from there. **NOTE:** if your generated directory is named 212something other than `generated/`, you will need to tell `jam` where it is: 213``` 214jam -q -sHAIKU_OUTPUT_DIR=<path to generated folder> 215``` 216You can also force the rebuild of a component by using the `-a` parameter: 217``` 218jam -qa Debugger 219``` 220 221Bootstrap Build 222---------------- 223New architectures (and occasionally existing ones) will require a bootstrap 224build to compile *build packages*. (Catch-22 software packages which are needed 225to compile Haiku, but need to be initially compiled under Haiku) 226 227### Pre-requirements 228 * All of the standard tools in the Required Software section above. 229 * The following repositories on disk in the same general location 230 * haiku (https://git.haiku-os.org/haiku) 231 * buildtools (https://git.haiku-os.org/buildtools) 232 * haikuporter (https://github.com/haikuports/haikuporter.git) 233 * haikuports.cross (https://github.com/haikuports/haikuports.cross.git) 234 * haikuports (https://github.com/haikuports/haikuports.git) 235 236### Setting Up a Bootstrap build 237Create a clean build directory under the haiku repo. 238``` 239mkdir generated.myarch && cd generated.myarch 240``` 241 242Configure Haiku's build system for a bootstrap build specifying the location 243of all of the repositories above. 244``` 245../configure -j4 \ 246 --build-cross-tools myarch ../../buildtools \ 247 --bootstrap ../../haikuporter/haikuporter ../../haikuports.cross ../../haikuports 248``` 249 250Once the build system is configured for bootstrap, we now can begin building 251the bootstrap image. 252 253``` 254jam -q @bootstrap-raw 255``` 256 257If you are bootstrapping for an architecture Haiku already boots on, the generated 258disk image can be used to compile *build packages* needed for the standard 259Haiku build. 260 261If you are bootstrapping for a new architecture which doesn't build yet, you will 262need to leverage the ```unbootstrap.sh``` script to hack the generated bootstrap 263packages into non-bootstrap packages which can be temporarily used as 264*build packages*. 265 266Running 267---------------- 268Generally there are two ways of running Haiku: on real hardware using a 269partition, and on emulated hardware using an emulator (like VirtualBox, or QEMU). 270 271### On Real Hardware 272If you have installed Haiku to its own partition you can include this 273partition in your bootmanager and try to boot Haiku like any other OS you 274have installed. To include a new partition in the Haiku bootmanager, start 275the BootManager configurator by running: 276``` 277BootManager 278``` 279 280### On Emulated Hardware 281For emulated hardware you should build a disk image (see above). How to set up 282this image depends on your emulator. If you use QEMU, you can usually just 283provide the path to the image as command line argument to the `qemu` 284executable. 285