1Building Haiku
2==========================
3This is a overview into the process of building HAIKU from source.
4An online version is available at <https://haiku-os.org/guides/building/>.
5
6Official releases of Haiku are at <https://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 * Mac OS X
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 * `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
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 * `curl`
47 * `zlib`
48
49### Haiku for ARM
50If 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
57Disk Utility can create a case-sensitive disk image of at least 3 GiB in size.
58The 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
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 &mdash; 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.
121You can either call configure from within your Haiku trunk folder. That will
122prepare 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-trunk/
127haiku-trunk/
128haiku-trunk/generated.x86gcc2
129```
130
131### Configure a GCC 2.95 Hybrid, from a non-Haiku platform
132```bash
133cd 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```
141cd haiku-trunk/generated.x86gcc2
142../configure --target-arch x86_gcc2 --target-arch x86
143```
144
145Additional information about GCC Hybrids can be found on the website,
146<https://haiku-os.org/guides/building/gcc-hybrid>.
147
148### Configure options
149The various runtime options for configure are documented in its onscreen help
150```bash
151./configure --help
152```
153
154Building via Jam
155----------------------------
156
157Haiku can be built in either of two ways, as disk image file (e.g. for use
158with emulators, to be written directly to a usb stick, burned as a compact
159disc) or as installation in a directory.
160
161### Running Jam
162
163There 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
171Be sure to read `build/jam/UserBuildConfig.ReadMe` and `UserBuildConfig.sample`,
172as they contain information on customizing your build of Haiku.
173
174### Building a Haiku anyboot file
175```
176jam -q @anyboot-image
177```
178
179This generates an image file named `haiku-anyboot.image` in your output
180directory under `generated/`.
181
182### Building a VMware image file
183```
184jam -q @vmware-image
185```
186This generates an image file named `haiku.vmdk` in your output
187directory under `generated/`.
188
189### Directory Installation
190```
191HAIKU_INSTALL_DIR=/Haiku jam -q @install
192```
193
194Installs all Haiku components into the volume mounted at "/Haiku" and
195automatically marks it as bootable. To create a partition in the first place
196use DriveSetup and initialize it to BFS.
197
198Note that installing Haiku in a directory only works as expected under Haiku,
199but it is not yet supported under Linux and other non-Haiku platforms.
200
201### Building individual components
202If you don't want to build the complete Haiku, but only a certain
203app/driver/etc. you can specify it as argument to jam, e.g.:
204```
205jam -q Debugger
206```
207Alternatively, you can `cd` to the directory of the component you want to
208build and run `jam` from there. **NOTE:** if your generated directory is named
209something other than `generated/`, you will need to tell `jam` where it is:
210```
211jam -q -sHAIKU_OUTPUT_DIR=<path to generated folder>
212```
213You can also force the rebuild of a component by using the `-a` parameter:
214```
215jam -qa Debugger
216```
217
218Running
219----------------
220Generally there are two ways of running Haiku: on real hardware using a
221partition, and on emulated hardware using an emulator (like VirtualBox, or QEMU).
222
223### On Real Hardware
224If you have installed Haiku to its own partition you can include this
225partition in your bootmanager and try to boot Haiku like any other OS you
226have installed. To include a new partition in the Haiku bootmanager, start
227the BootManager configurator by running:
228```
229BootManager
230```
231
232### On Emulated Hardware
233For emulated hardware you should build disk image (see above). How to set up
234this image depends on your emulator. If you use QEMU, you can usually just
235provide the path to the image as command line argument to the `qemu`
236executable.
237