ReadMe.Compiling.md

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