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
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/beta1) 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 * `awk` (GNU awk is most tested, but other implementations should work)
35 * `nasm`
36 * `wget`
37 * `[un]zip`
38 * `xorriso`
39 * `mtools` (<https://gnu.org/software/mtools/intro.html>)
40 * `python3`
41 * case-sensitive file system
42
43Whether they are installed can be tested by running them in a shell with
44the `--version` parameter.
45
46The following libraries (and their respective headers) are required:
47 * `zlib`
48 * `zstd`
49
50### Haiku for ARM
51If you want to compile Haiku for ARM, you will also need:
52
53 * `mkimage` (<http://www.denx.de/wiki/U-Boot/WebHome>)
54
55### On macOS
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 * `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 &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://review.haiku-os.org/haiku.git
85git clone https://review.haiku-os.org/buildtools.git
86```
87
88If you have commit access:
89```
90git clone ssh://git.haiku-os.org/haiku
91git clone ssh://git.haiku-os.org/buildtools
92```
93
94Building Jam
95-------------------------------------------
96(*This step applies only to non-Haiku platforms. Haiku already ships with the correct version of Jam*)
97
98Change to the `buildtools` folder and run the following commands to
99generate and install `jam`:
100```
101cd buildtools/jam
102make
103sudo ./jam0 install
104```
105Or,  if you don't want to install `jam` systemwide:
106```
107./jam0 -sBINDIR=$HOME/bin install
108```
109
110Configuring the build
111-------------------------------------
112The `configure` script generates a file named `BuildConfig` in the
113`generated/build` directory. As long as `configure` is not modified (!) and the
114cross-compilation tools have not been updated, there is no need to call it again.
115For rebuilding, you only need to invoke `jam` (see below). If you don't
116update the source tree very frequently, you may want to execute `configure`
117after each update just to be on the safe side.
118
119Depending on your goal, there are several different ways to configure Haiku.
120The first way is to call configure from within your Haiku checkout's root. That
121will prepare a folder named 'generated', which will contain the compiled objects.
122Another option is to manually created one or more `generated.*` folders and run
123configure from within them. For example, imagine the following directory setup:
124```
125buildtools/
126haiku/
127haiku/generated.x86gcc2
128```
129
130### Configure an x86_64 (GCC 8) build
131```bash
132cd haiku/generated.x86_64
133../configure --cross-tools-source ../../buildtools --build-cross-tools x86_64
134```
135
136### Configure a 32-bit GCC 2.95/GCC 8 Hybrid, from a non-Haiku platform
137```bash
138cd haiku/generated.x86gcc2
139../configure \
140	--cross-tools-source ../../buildtools/ \
141	--build-cross-tools x86_gcc2 \
142	--build-cross-tools x86
143```
144
145### Configure a 32-bit GCC 2.95/GCC 8 Hybrid, from Haiku
146```bash
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 image (Nightly)
181```
182jam -q @nightly-anyboot
183```
184
185This generates an image file named `haiku-nightly-anyboot.iso` in your output
186directory under `generated/`.
187
188### Building a Haiku raw image (Nightly)
189```
190jam -q @nightly-raw
191```
192
193This generates an image file named `haiku.image` in your output directory under
194`generated/`.
195
196### Building a VMware image file
197```
198jam -q @nightly-vmware
199```
200
201This generates an image file named `haiku.vmdk` in your output
202directory under `generated/`.
203
204### Directory Installation
205```
206HAIKU_INSTALL_DIR=/Haiku jam -q @install
207```
208
209Installs all Haiku components into the volume mounted at "/Haiku" and
210automatically marks it as bootable. To create a partition in the first place
211use DriveSetup and initialize it to BFS.
212
213Note that installing Haiku in a directory only works as expected under Haiku,
214but it is not yet supported under Linux and other non-Haiku platforms.
215
216### Building individual components
217If you don't want to build the complete Haiku, but only a certain
218app/driver/etc. you can specify it as argument to jam, e.g.:
219```
220jam -q Debugger
221```
222Alternatively, you can `cd` to the directory of the component you want to
223build and run `jam` from there. **NOTE:** if your generated directory is named
224something other than `generated/`, you will need to tell `jam` where it is:
225```
226jam -q -sHAIKU_OUTPUT_DIR=<path to generated folder>
227```
228You can also force the rebuild of a component by using the `-a` parameter:
229```
230jam -qa Debugger
231```
232
233Bootstrap Build
234----------------
235New architectures (and occasionally existing ones) will require a bootstrap
236build to compile *build packages*. (Catch-22 software packages which are needed
237to compile Haiku, but need to be initially compiled under Haiku)
238
239### Pre-requirements
240  * All of the standard tools in the Required Software section above.
241  * The following repositories on disk in the same general location
242    * haiku (https://git.haiku-os.org/haiku)
243    * buildtools (https://git.haiku-os.org/buildtools)
244    * haikuporter (https://github.com/haikuports/haikuporter.git)
245    * haikuports.cross (https://github.com/haikuports/haikuports.cross.git)
246    * haikuports (https://github.com/haikuports/haikuports.git)
247
248### Setting Up a Bootstrap build
249Create a clean build directory under the haiku repo.
250```
251mkdir generated.myarch && cd generated.myarch
252```
253
254Configure Haiku's build system for a bootstrap build specifying the location
255of all of the repositories above.
256```
257../configure -j4 \
258  --build-cross-tools myarch --cross-tools-source ../../buildtools \
259  --bootstrap ../../haikuporter/haikuporter ../../haikuports.cross ../../haikuports
260```
261
262Once the build system is configured for bootstrap, we now can begin building
263the bootstrap image.
264
265```
266jam -q @bootstrap-raw
267```
268
269If you are bootstrapping for an architecture Haiku already boots on, the generated
270disk image can be used to compile *build packages* needed for the standard
271Haiku build.
272
273If you are bootstrapping for a new architecture which doesn't build yet, you will
274need to leverage the ```unbootstrap.sh``` script to hack the generated bootstrap
275packages into non-bootstrap packages which can be temporarily used as
276*build packages*.
277
278Running
279----------------
280Generally there are two ways of running Haiku: on real hardware using a
281partition, and on emulated hardware using an emulator (like VirtualBox, or QEMU).
282
283### On Real Hardware
284If you have installed Haiku to its own partition you can include this
285partition in your bootmanager and try to boot Haiku like any other OS you
286have installed. To include a new partition in the Haiku bootmanager, start
287the BootManager configurator by running:
288```
289BootManager
290```
291
292### On Emulated Hardware
293For emulated hardware you should build a disk image (see above). How to set up
294this image depends on your emulator. If you use QEMU, you can usually just
295provide the path to the image as command line argument to the `qemu`
296executable.
297