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