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