Update cross compiler instructions to build for i686
[akaros.git] / GETTING_STARTED
1 GETTING_STARTED
2 Barret Rhoden
3
4 Last thorough update: 2013-02-07
5
6
7 1. Overview
8 ---------------------
9 In this document, I outline what steps I go through to set up my development
10 environment.  Some devs use other setups, and they can put sections farther
11 down in this document describing their steps.
12
13 Due to the nature of different workflows and different Linux distros, you'll
14 need to do some configuration of your environment.  Things won't magically work
15 out of the box.
16
17
18 2. Need help?
19 ---------------------
20 First off, if you get stuck, email someone.  You can join our mailing list by
21 sending an email to akaros-request@lists.eecs.berkeley.edu.  Send your messages
22 to akaros@lists.eecs.berkeley.edu.  Or just email me (brho@cs), though the
23 mailing list is a more scalable method in the long run.
24
25 Alternatively, you can poke your head in #akaros on irc.freenode.net.  I'm
26 usually idling in there (alone), and if I'm at my computer, I'll respond.
27
28
29 3. From Download to Hello World
30 ---------------------
31 I'll describe how to get x86 working.  RISCV is similar.
32
33 The first step is to configure the kernel.  config, menuconfig, and some of the
34 other KBuild targets work.  Defconfig gives you a default configuration.  For
35 example, to config for 32 bit x86:
36
37 $ make ARCH=x86 defconfig
38
39 Alternatively, you can run menuconfig to customize what settings you want:
40
41 $ make ARCH=x86 menuconfig
42
43 There are a lot of settings in here, which you should browse through to decide
44 what you want to enable/disable.
45
46 Most everyone wants KFS turned on (Filesystems --> KFS filesystem).  This is
47 the in-memory filesystem that the kernel uses.  The kernel build scripts will
48 look at the "KFS/Initramfs paths" string and take any of those directories and
49 add them to a CPIO archive that will eventually become the root filesystem when
50 Akaros runs. These settings are set by default when you do a 'make defconfig'.
51
52 There are also settings for ext2.  If you turn on ext2 support, you need to
53 point to an img file that has been formatted with ext2 and has files in it.  If
54 you aren't messing with filesystems at all, feel free to ignore this.  It's an
55 in-memory filesystem, like KFS (linked to the end of the kernel), so you won't
56 gain much by using it for now.
57
58 3.1 Cross compiler (and glibc)
59 ----------
60 The second step is to build the cross compiler, which lives in
61 tools/compilers/gcc-glibc
62
63 $ cd tools/compilers/gcc-glibc
64
65 In this directory, you first need to set up your Makelocal file.  There is a
66 template to work from.
67
68 $ cp Makelocal.template Makelocal
69
70 You need to set your INSTDIRS to some place where you want the cross compiler
71 installed.  I have a directory named ros-gcc-glibc for this.
72
73 You also need to add bin directories to your PATH where the cross compiler will
74 be installed.  This will vary based on your value for INSTDIRS.  For instance,
75 my path contains:
76
77 /home/brho/classes/ros/ros-gcc-glibc/install-i386-ros-gcc/bin
78
79 You can also set up MAKE_JOBS, so you don't over or under load your system when
80 building.  I have a 2 core laptop, so I use MAKE_JOBS := 3
81
82 At this point, you can build:
83
84 $ make i686
85
86 This might take a while (10-20 minutes for me on a 2007 era laptop).
87
88 Just to double check everything installed correctly, you should be able to run
89 i686-ros-gcc from your shell.
90
91 Now, you have a cross compiler ready, and you can start to build Akaros.
92
93 3.2 Kernel
94 ----------
95 cd back into the repo root.
96
97 Like the cross compiler, the kernel has its own Makelocal.
98
99 $ cp Makelocal.template Makelocal
100
101 This file is used to set up custom make targets that are not part of the
102 default Makefile, but fit nicely into your personal workflow. This file is not
103 under version control and can me made to contain just about anything.
104
105 Now you're ready to build the kernel:
106
107 $ make
108
109 So the kernel built, but you can't do much with it, and you probably have no
110 programs.
111
112 Notice that we didn't have to set the ARCH variable this time.  The make system
113 knows what architecture we are set up for and will always build for that
114 architecture until a new ARCh is selected (i.e. via 'make ARCH=xxx defconfig'
115 etc.)
116
117 3.3 Userspace
118 ---------
119 To build userspace and test programs:
120
121 $ make tests
122
123 You now have programs and libraries, and need to put them in KFS.  To do this,
124 we provide a 'fill-kfs' make target. 
125
126 $ make fill-kfs
127
128 The 'fill-kfs' target copies your cross compiler's shared libraries and all
129 test binaries into the first "KFS/Initramfs path" you set during configuration
130 (or kern/kfs/lib if you just kept the default).
131
132 Now that you've changed the contents of KFS's source, remake the kernel.  You
133 should see something like
134         Building initramfs:
135                 Adding kern/kfs to initramfs...
136 before the kernel links.  If you don't see this, then you probably didn't
137 actually fill KFS properly.
138
139 3.4 Busybox
140 ---------
141 If you don't care about busybox or just want to get started immediately, skip
142 this section.
143
144 Other userspace programs, like busybox need to be compiled with the cross
145 compiler and then have their binaries copied to kern/kfs/bin (I do this
146 manually).
147
148 I'm running busybox 1.17.3, and the config file I use is in tools/patches.
149 Copy that to your busybox directory (once you download and untar it, etc) and
150 name it ".config".  You can get busybox from http://www.busybox.net/downloads/.
151 Eventually I'll upgrade, though it hasn't been a big deal yet.
152
153 $ cd BUSYBOXDIR/..
154 $ wget http://www.busybox.net/downloads/busybox-1.17.3.tar.bz2
155 $ tar -jxvf busybox-1.17.3.tar.bz2
156 $ cd AKAROS-ROOT
157 $ cp tools/patches/busybox-1.17.3.config BUSYBOXDIR/.config
158
159 $ cd BUSYBOXDIR ; make
160
161 Then I copy the unstripped binary to KFS.
162
163 $ cp busybox_unstripped AKAROS-ROOT/kern/kfs/bin/busybox
164
165 Note I change the name to busybox (dropping the unstripped).  I want the
166 unstripped binary for debugging reasons.
167
168 Busybox can do core commands like ls and rm, as well as run a shell (ash), all
169 from within one binary.  It can tell which command it should execute based on
170 the name of the binary (or symlink to it).  I have a bunch of symlinks for
171 whatever 'busybox' programs I want to run inside kern/kfs/bin.
172
173 For instance, from my AKAROS-ROOT:
174 $ ls -l kern/kfs/bin/ | grep busybox
175 lrwxrwxrwx 1 brho brho      7 Aug 24  2010 ash -> busybox
176 -rwxr-xr-x 1 brho brho 337917 Dec 19 17:39 busybox
177 lrwxrwxrwx 1 brho brho      7 Sep 29  2010 cat -> busybox
178 lrwxrwxrwx 1 brho brho      7 Sep  1  2010 cp -> busybox
179 lrwxrwxrwx 1 brho brho      7 Oct 18 13:12 kill -> busybox
180 lrwxrwxrwx 1 brho brho      7 Sep  5  2010 ln -> busybox
181 lrwxrwxrwx 1 brho brho      7 Aug 23  2010 ls -> busybox
182 lrwxrwxrwx 1 brho brho      7 Sep  5  2010 mkdir -> busybox
183 lrwxrwxrwx 1 brho brho      7 Sep  5  2010 rmdir -> busybox
184 lrwxrwxrwx 1 brho brho      7 Apr  9  2012 stty -> busybox
185 lrwxrwxrwx 1 brho brho      7 Apr  9  2012 tty -> busybox
186
187 Note I don't need to update the symlinks (almost ever...).  I just recopy the
188 busybox binary whenever I update it.
189
190 I think some of the other devs build busybox so that it spits out the links
191 into an install directory.  Feel free to do whatever.  I'll probably just add a
192 bunch of symlinks to the repos default KFS contents one of these days.
193 Incidentally, kern/kfs/* is ignored by git.
194
195 Now that you've changed KFS, don't forget to remake the kernel.
196
197 3.5 Building and Loading a Virtual Machine Image
198 ---------
199 At this point, you probably have a runnable kernel with programs in KFS.  It
200 should be sitting at obj/kernel/kernel.  However, you need a place to run it.
201
202 I run my kernels either in KVM (Qemu) or off a bootable USB stick.
203
204 You'll need an image file that looks like a hard disk to boot qemu off of.  I
205 put one similar to mine at: http://akaros.cs.berkeley.edu/files/hdd268mb.img
206
207 It's around 268MB (256MiB, or whatever).  If you want to make your own, check
208 out Documentation/howtos/make-bootable-grub-hdd.txt.  That's actually the
209 original document I made back when I first figured it out back in 2009, which
210 has been updated again in 2013.    In between, I wrote it up online at
211 http://www.omninerd.com/articles/Installing_GRUB_on_a_Hard_Disk_Image_File,
212 which has some other tidbits in the comments.  Both methods still use grub1.
213
214 Anyway, I put that img in AKAROS-ROOT/mnt/, and make a folder next to it:
215 AKAROS-ROOT/mnt/hdd.  mnt/hdd is the mount point where I mount hdd.img (Note I
216 don't call it hdd64mb.img on my dev machine).
217
218 Personally, I always have hdd.img mounted.  Some of the other devs have make
219 targets that mount and umount it.  Whenever I reboot my development machine, I
220 run a script (as root) that mounts the image file and sets up a few things for
221 networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll likely
222 want to copy it to the directory *above* the akaros root directory and edit it
223 accordingly. Feel free to comment out the networking stuff.  That's for using
224 networking in qemu.
225
226 Now that your image file is mounted at mnt/hdd, you'll want to copy your
227 freshly built kernel to the root of the image.  I have a make target in my
228 makelocal for this, so that whenever I do a make kvm, it builds the kernel and
229 copies it to my hdd.img.
230
231 I added edited versions of my KVM (and USB) make targets to the
232 Makelocal.template.  Uncomment the KVM one (at least).
233
234 Incidentally, I also have the following in my Makelocal, so that make (and make
235 all) also make kvm:
236
237 all: kvm
238
239 Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
240 -l and check the timestamp).
241
242 3.6 Running Qemu
243 ---------
244 Here is the command I use to run qemu/kvm.  It's evolved over the years, and it
245 will vary based on your linux distribution.  Don't run it just yet:
246
247 $ qemu-system-i386 -s -enable-kvm -cpu coreduo -smp 8 -m 1024 -nographic -monitor /dev/pts/3 -net nic,model=e1000 -net tap,ifname=tap0,script=no mnt/hdd.img
248
249 The -monitor is the qemu monitor, which is a CLI for qemu.  Pick a
250 tab/terminal/pty in Linux that you will only use for qemu monitoring, and enter
251 'tty'.  Whatever it tells you, put in place of /dev/pts/3.  I've been using the
252 same tab for about 4 years now.  In that tab, enter 'sleep 999999999'.  Qemu
253 will still access it, but you won't have to worry about bash trying to handle
254 your inputs.
255
256 -nographic allows qemu to work in the terminal you run qemu from, instead of
257 spawning off a fake cpu crt/monitor.
258
259 If you don't have networking set up (including the tun/tap stuff from
260 kvm-up.sh), remove the -net commands/options.
261
262 Fell free to pick different values for the number of cpus and RAM (8 and 1024
263 in the example).
264
265 Once you finally run it, you can stop the VM by entering 'q' to the qemu
266 monitor (or just killing the process)..  Other help commands from the monitor
267 include 'info cpus', 'info registers', 'x', and 'help'.
268
269
270 3.7 Running on Hardware
271 ---------
272 I have a few bootable USB sticks with grub set up to run Akaros.  The make usb
273 target (example in Makelocal.template) will copy freshly made kernels to your
274 USB device.  You'll need to adjust those paths according to your distro.  My
275 usb sticks are usually /dev/sdc, for instance (some odd USB device in the last
276 couple of years has taken over /dev/sdb.  Probably something to do with udev
277 changing over the years).
278
279 Anyway, you'll need to mess around a bit to get that working.  Or I can dd one
280 for you (I have 4GB disks in my office that I use).  If you make your own, the
281 critical part is getting grub to pick the right device (from what I remember),
282 and its fairly similar to installing grub on any old hard drive (since it's
283 just a bloc device).  Much easier than a hard disk image file.
284
285
286 3.8 Hello World
287 ---------
288 So now you can run the kernel.  It's time to edit a program (or make your own).
289 In this, I'll go through my workflow for making changes.
290
291 $ vi tests/hello.c
292 (edit, save)
293
294 $ make tests
295 (new version in obj/tests/hello)
296
297 $ make fill-kfs
298 (updates kfs)
299
300 $ make
301 (rebuilds kernel with the new KFS)
302
303 $ qemu...
304
305 (following commands are in Akaros)
306 Shift-G (to get to the kernel monitor)
307
308 ROS(Core 0)> bb (to run busybox)
309
310 / $ hello
311 (Should print your message)
312
313
314 3.9 Other Dev Workflow stuff
315 ---------
316 One thing to note is that while we use dynamic linking for libc, parlib
317 libraries are statically linked with applications.  In fact, nowadays *all*
318 Akaros programs need to be linked againt parlib (used to be that single-core
319 processes (SCPs) didn't need it).
320
321 The makefiles won't notice if you change a file in parlib and then remake a
322 binary.  So if you edit user/parlib/uthread.c for example, tests/pthread_test
323 won't get rebuilt.  Here's what I do:
324
325 $ vi user/parlib/uthread.c (make awesome change)
326
327 $ touch tests/pthread_test.c ; make tests
328
329 This will force the rebuild of pthread_test.  Older, untouched binaries (e.g.
330 block_test), won't get rebuilt.  I actually want this in some cases (different
331 versions of parlib when I'm running certain tests).  Anyway, just pay attention
332 to what you're building.  There's not much output in the console, so you should
333 be able to see what's going on all the time.  (unlike when building glibc...).
334
335 Oh, and don't forget to:
336
337 $ make fill-kfs
338
339 to make sure you run the new pthread_test. 
340
341 Early on as a dev, there are lots of times where you accidentally don't run the
342 right program (or kernel) and won't understand why your change isn't happening.
343 A few printk("WTF\n")'s later, you realize you didn't have the hdd.img mounted,
344 or you didn't fill KFS, or you didn't relink your binaries, or you forgot to
345 save all files in vi (and not just the current buffer).  But after doing a
346 couple hello worlds, you're set. 
347
348 Alternatively, you could have a make target to run qemu, which also touches all
349 binaries (or otherwise enforces a rebuild), auto-fills KFS, remakes the kernel,
350 and mounts/copies/unmounts your hdd.img.  Kevin's sim repo has stuff like this,
351 so check it out if that's what you're into.  (I think it is at
352 http://akaros.cs.berkeley.edu/ros-sim.tar.gz).  Personally, I'm not that into
353 it, since I like to keep track of what is going on under the hood, esp if I
354 want to do something a little differently (like with testing ext2, having
355 different versions of parlib with some binaries, or being picky about my
356 mount/umounts).
357
358
359 4. RISCV
360 ---------------------
361 TODO.
362
363 For now, you need a 64 bit distro to build the RISCV stuff, so I don't do it
364 very often.  I'll eventually sync up with Andrew and we'll get this part sorted
365 out.
366
367
368 5. Other Developer's Stuff
369 ---------------------