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