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` (**not** `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
  73 More information about individual distributions of Linux and BSD can be found
  74 at <https://haiku-os.org/guides/building/pre-reqs>.
  75
  76 Downloading Haiku's sources
  77 --------------------------------------------------
  78 There are two parts to Haiku's sources &mdash; the code for Haiku itself and a set
  79 of build tools for compiling Haiku on an operating system other than Haiku.
  80 The buildtools are needed only for non-Haiku platforms.
  81
  82 Anonymous checkout:
  83 ```
  84 git clone https://git.haiku-os.org/haiku
  85 git clone https://git.haiku-os.org/buildtools
  86 ```
  87 (You can also use the `git://` protocol, but it is not secure).
  88
  89 If you have commit access:
  90 ```
  91 git clone ssh://git.haiku-os.org/haiku
  92 git clone ssh://git.haiku-os.org/buildtools
  93 ```
  94
  95 Building Jam
  96 -------------------------------------------
  97 (*This step applies only to non-Haiku platforms.*)
  98
  99 Change to the `buildtools` folder and run the following commands to
 100 generate and install `jam`:
 101 ```
 102 cd buildtools/jam
 103 make
 104 sudo ./jam0 install
 105 ```
 106 Or,  if you don't want to install `jam` systemwide:
 107 ```
 108 ./jam0 -sBINDIR=$HOME/bin install
 109 ```
 110
 111 Configuring the build
 112 -------------------------------------
 113 The `configure` script generates a file named `BuildConfig` in the
 114 `generated/build` directory. As long as `configure` is not modified (!) and the
 115 cross-compilation tools have not been updated, there is no need to call it again.
 116 For rebuilding, you only need to invoke `jam` (see below). If you don't
 117 update the source tree very frequently, you may want to execute `configure`
 118 after each update just to be on the safe side.
 119
 120 Depending on your goal, there are several different ways to configure Haiku.
 121 You can either call configure from within your Haiku trunk folder. That will
 122 prepare a folder named 'generated', which will contain the compiled objects.
 123 Another option is to manually created one or more `generated.*` folders and run
 124 configure from within them. For example, imagine the following directory setup:
 125 ```
 126 buildtools-trunk/
 127 haiku-trunk/
 128 haiku-trunk/generated.x86gcc2
 129 ```
 130
 131 ### Configure a GCC 2.95 Hybrid, from a non-Haiku platform
 132 ```bash
 133 cd haiku-trunk/generated.x86gcc2
 134 ../configure --use-xattr-ref \
 135         --build-cross-tools x86_gcc2 ../../buildtools/ \
 136         --build-cross-tools x86
 137 ```
 138
 139 ### Configure a GCC 2.95 Hybrid, from Haiku
 140 ```
 141 cd haiku-trunk/generated.x86gcc2
 142 ../configure --target-arch x86_gcc2 --target-arch x86
 143 ```
 144
 145 Additional information about GCC Hybrids can be found on the website,
 146 <https://haiku-os.org/guides/building/gcc-hybrid>.
 147
 148 ### Configure options
 149 The various runtime options for configure are documented in its onscreen help
 150 ```bash
 151 ./configure --help
 152 ```
 153
 154 Building via Jam
 155 ----------------------------
 156
 157 Haiku can be built in either of two ways, as disk image file (e.g. for use
 158 with emulators, to be written directly to a usb stick, burned as a compact
 159 disc) or as installation in a directory.
 160
 161 ### Running Jam
 162
 163 There are various ways in which you can run `jam`:
 164
 165  * If you have a single generated folder, you can run 'jam' from the top level of Haiku's trunk.
 166  * If you have one or more generated folders, (e.g. generated.x86gcc2),
 167    you can `cd` into that directory and run `jam`.
 168  * In either case, you can `cd` into a certain folder in the source tree (e.g.
 169    src/apps/debugger) and run jam -sHAIKU_OUTPUT_DIR=<path to generated folder>
 170
 171 Be sure to read `build/jam/UserBuildConfig.ReadMe` and `UserBuildConfig.sample`,
 172 as they contain information on customizing your build of Haiku.
 173
 174 ### Building a Haiku anyboot file
 175 ```
 176 jam -q @anyboot-image
 177 ```
 178
 179 This generates an image file named `haiku-anyboot.image` in your output
 180 directory under `generated/`.
 181
 182 ### Building a VMware image file
 183 ```
 184 jam -q @vmware-image
 185 ```
 186 This generates an image file named `haiku.vmdk` in your output
 187 directory under `generated/`.
 188
 189 ### Directory Installation
 190 ```
 191 HAIKU_INSTALL_DIR=/Haiku jam -q @install
 192 ```
 193
 194 Installs all Haiku components into the volume mounted at "/Haiku" and
 195 automatically marks it as bootable. To create a partition in the first place
 196 use DriveSetup and initialize it to BFS.
 197
 198 Note that installing Haiku in a directory only works as expected under Haiku,
 199 but it is not yet supported under Linux and other non-Haiku platforms.
 200
 201 ### Building individual components
 202 If you don't want to build the complete Haiku, but only a certain
 203 app/driver/etc. you can specify it as argument to jam, e.g.:
 204 ```
 205 jam -q Debugger
 206 ```
 207 Alternatively, you can `cd` to the directory of the component you want to
 208 build and run `jam` from there. **NOTE:** if your generated directory is named
 209 something other than `generated/`, you will need to tell `jam` where it is:
 210 ```
 211 jam -q -sHAIKU_OUTPUT_DIR=<path to generated folder>
 212 ```
 213 You can also force the rebuild of a component by using the `-a` parameter:
 214 ```
 215 jam -qa Debugger
 216 ```
 217
 218 Running
 219 ----------------
 220 Generally there are two ways of running Haiku: on real hardware using a
 221 partition, and on emulated hardware using an emulator (like VirtualBox, or QEMU).
 222
 223 ### On Real Hardware
 224 If you have installed Haiku to its own partition you can include this
 225 partition in your bootmanager and try to boot Haiku like any other OS you
 226 have installed. To include a new partition in the Haiku bootmanager, start
 227 the BootManager configurator by running:
 228 ```
 229 BootManager
 230 ```
 231
 232 ### On Emulated Hardware
 233 For emulated hardware you should build disk image (see above). How to set up
 234 this image depends on your emulator. If you use QEMU, you can usually just
 235 provide the path to the image as command line argument to the `qemu`
 236 executable.