cleanup: remove redundant includes left over from script.
[akaros.git] / GETTING_STARTED
index 588c1bb..9704d46 100644 (file)
@@ -32,9 +32,31 @@ I'll describe how to get x86 working.  RISCV is similar.
 
 The first step is to configure the kernel.  config, menuconfig, and some of the
 other KBuild targets work.  Defconfig gives you a default configuration.  For
 
 The first step is to configure the kernel.  config, menuconfig, and some of the
 other KBuild targets work.  Defconfig gives you a default configuration.  For
-example, to config for 32 bit x86:
+example, to config for 64-bit x86:
 
 
-$ make ARCH=i686 defconfig
+$ make ARCH=x86 defconfig
+
+Alternatively, you can run menuconfig to customize what settings you want:
+
+$ make ARCH=x86 menuconfig
+
+For x86, you can choose between 32 and 64 bit when you make menuconfig.  This
+selection must match your cross compiler make command.  The default is 64 bit.
+
+There are a lot of other settings when you make config, and you should browse
+through to decide what you want to enable/disable.
+
+Most everyone wants KFS turned on (Filesystems --> KFS filesystem).  This is
+the in-memory filesystem that the kernel uses.  The kernel build scripts will
+look at the "KFS/Initramfs paths" string and take any of those directories and
+add them to a CPIO archive that will eventually become the root filesystem when
+Akaros runs. These settings are set by default when you do a 'make defconfig'.
+
+There are also settings for ext2.  If you turn on ext2 support, you need to
+point to an img file that has been formatted with ext2 and has files in it.  If
+you aren't messing with filesystems at all, feel free to ignore this.  It's an
+in-memory filesystem, like KFS (linked to the end of the kernel), so you won't
+gain much by using it for now.
 
 3.1 Cross compiler (and glibc)
 ----------
 
 3.1 Cross compiler (and glibc)
 ----------
@@ -51,25 +73,30 @@ $ cp Makelocal.template Makelocal
 You need to set your INSTDIRS to some place where you want the cross compiler
 installed.  I have a directory named ros-gcc-glibc for this.
 
 You need to set your INSTDIRS to some place where you want the cross compiler
 installed.  I have a directory named ros-gcc-glibc for this.
 
+You also need to add bin directories to your PATH where the cross compiler will
+be installed.  This will vary based on your value for INSTDIRS.  For instance,
+my path contains:
+
+/home/brho/classes/ros/ros-gcc-glibc/install-x86_64-ros-gcc/bin
+
+       and
+
+/home/brho/classes/ros/ros-gcc-glibc/install-i686-ros-gcc/bin
+
 You can also set up MAKE_JOBS, so you don't over or under load your system when
 building.  I have a 2 core laptop, so I use MAKE_JOBS := 3
 
 You can also set up MAKE_JOBS, so you don't over or under load your system when
 building.  I have a 2 core laptop, so I use MAKE_JOBS := 3
 
-At this point, you can build:
+At this point, you can build (for example):
 
 
-$ make x86
+$ make x86_64
 
 This might take a while (10-20 minutes for me on a 2007 era laptop).
 
 
 This might take a while (10-20 minutes for me on a 2007 era laptop).
 
-Finally, add the cross compiler's bin directories to your PATH.  This will vary
-based on where you installed things.  For instance, my path contains:
-
-/home/brho/classes/ros/ros-gcc-glibc/install-i386-ros-gcc/bin
-
-Just to double check, you should be able to run i686-ros-gcc from your shell.
+Just to double check everything installed correctly, you should be able to run
+x86_64-ros-gcc from your shell.
 
 Now, you have a cross compiler ready, and you can start to build Akaros.
 
 
 Now, you have a cross compiler ready, and you can start to build Akaros.
 
-
 3.2 Kernel
 ----------
 cd back into the repo root.
 3.2 Kernel
 ----------
 cd back into the repo root.
@@ -78,30 +105,22 @@ Like the cross compiler, the kernel has its own Makelocal.
 
 $ cp Makelocal.template Makelocal
 
 
 $ cp Makelocal.template Makelocal
 
-There are a lot of settings in here, which you need to uncomment to turn on.
-
-Most everyone wants KFS turned on (CONFIG_KFS).  This is the in-memory
-filesystem that the kernel uses.  The kernel build scripts will look at
-INITRAMFS_PATHS and take any of those directories and add them to a CPIO
-archive that will eventually become the root filesystem when Akaros runs.  I
-set CONFIG_KFS and suggested a INITRAMFS_PATH in the Makelocal.template.
-
-There are also settings for ext2.  If you turn on ext2 support, you need to
-point to an img file that has been formatted with ext2 and has files in it.  If
-you aren't messing with filesystems at all, feel free to ignore this.  It's an
-in-memory filesystem, like KFS (linked to the end of the kernel), so you won't
-gain much by using it for now.
+This file is used to set up custom make targets that are not part of the
+default Makefile, but fit nicely into your personal workflow. This file is not
+under version control and can me made to contain just about anything.
 
 Now you're ready to build the kernel:
 
 
 Now you're ready to build the kernel:
 
-$ make x86
-
-On future makes, you can just 'make'.  The initial make x86 is to pick a target
-architecture.
+$ make
 
 So the kernel built, but you can't do much with it, and you probably have no
 programs.
 
 
 So the kernel built, but you can't do much with it, and you probably have no
 programs.
 
+Notice that we didn't have to set the ARCH variable this time.  The make system
+knows what architecture we are set up for and will always build for that
+architecture until a new ARCh is selected (i.e. via 'make ARCH=xxx defconfig'
+etc.)
+
 3.3 Userspace
 ---------
 To build userspace and test programs:
 3.3 Userspace
 ---------
 To build userspace and test programs:
@@ -109,12 +128,13 @@ To build userspace and test programs:
 $ make tests
 
 You now have programs and libraries, and need to put them in KFS.  To do this,
 $ make tests
 
 You now have programs and libraries, and need to put them in KFS.  To do this,
-I have a script called 'fill_kfs.sh'.  I usually have it in the directory above
-my repo root.  I put a copy of it in scripts/fill_kfs.sh in the repo.  You will
-need to edit it for your own setup.  Or you can do everything manually.  Either
-way, you need to make sure shared libraries are copied into kern/kfs/lib (given
-kern/kfs as your INITRAMFS_PATH) and you want your programs copied to
-kern/kfs/bin.
+we provide a 'fill-kfs' make target. 
+
+$ make fill-kfs
+
+The 'fill-kfs' target copies your cross compiler's shared libraries and all
+test binaries into the first "KFS/Initramfs path" you set during configuration
+(or kern/kfs/lib if you just kept the default).
 
 Now that you've changed the contents of KFS's source, remake the kernel.  You
 should see something like
 
 Now that you've changed the contents of KFS's source, remake the kernel.  You
 should see something like
@@ -132,18 +152,31 @@ Other userspace programs, like busybox need to be compiled with the cross
 compiler and then have their binaries copied to kern/kfs/bin (I do this
 manually).
 
 compiler and then have their binaries copied to kern/kfs/bin (I do this
 manually).
 
-I'm running busybox 1.17.3, and the config file I use is in tools/patches.
-Copy that to your busybox directory (once you download and untar it, etc) and
-name it ".config".  You can get busybox from http://www.busybox.net/downloads/.
-Eventually I'll upgrade, though it hasn't been a big deal yet.
+I'm running busybox 1.17.3, and the config file I use is in
+tools/patches/busybox.  Copy that to your busybox directory (once you download
+and untar it, etc) and name it ".config".  This config file assumes you want
+x86_64-ros-gcc.  If you are builidng for 32 bit x86 or riscv, you will need to
+edit the config file.
+
+You can get busybox from http://www.busybox.net/downloads/.  Eventually I'll
+upgrade, though it hasn't been a big deal yet.
 
 
-$ cp tools/patches/busybox-1.17.3.config BUSYBOXDIR/.config
+$ cd BUSYBOXDIR/..
+$ wget http://www.busybox.net/downloads/busybox-1.17.3.tar.bz2
+$ tar -jxvf busybox-1.17.3.tar.bz2
+$ cd AKAROS-ROOT
+$ cp tools/patches/busybox/busybox-1.17.3.config BUSYBOXDIR/.config
 
 
-$ cd BUSYBOXDIR ; make
+$ cd BUSYBOXDIR
+
+You'll also want to apply any patches for busybox.  From the busybox directory:
+
+$ patch -p1 < AKAROS-ROOT/tools/patches/busybox/EACH_PATCH_FILE.patch
+$ make
 
 Then I copy the unstripped binary to KFS.
 
 
 Then I copy the unstripped binary to KFS.
 
-$ cp busybox_unstripped AKAROS-REPO/kern/kfs/bin/busybox
+$ cp busybox_unstripped AKAROS-ROOT/kern/kfs/bin/busybox
 
 Note I change the name to busybox (dropping the unstripped).  I want the
 unstripped binary for debugging reasons.
 
 Note I change the name to busybox (dropping the unstripped).  I want the
 unstripped binary for debugging reasons.
@@ -173,19 +206,25 @@ busybox binary whenever I update it.
 I think some of the other devs build busybox so that it spits out the links
 into an install directory.  Feel free to do whatever.  I'll probably just add a
 bunch of symlinks to the repos default KFS contents one of these days.
 I think some of the other devs build busybox so that it spits out the links
 into an install directory.  Feel free to do whatever.  I'll probably just add a
 bunch of symlinks to the repos default KFS contents one of these days.
-Incidentally, kern/kfs/* is now ignored by git.
+Incidentally, kern/kfs/* is ignored by git.
 
 Now that you've changed KFS, don't forget to remake the kernel.
 
 3.5 Building and Loading a Virtual Machine Image
 ---------
 At this point, you probably have a runnable kernel with programs in KFS.  It
 
 Now that you've changed KFS, don't forget to remake the kernel.
 
 3.5 Building and Loading a Virtual Machine Image
 ---------
 At this point, you probably have a runnable kernel with programs in KFS.  It
-should be sitting at obj/kernel/kernel.  However, you need a place to run it.
+should be sitting at obj/kernel/akaros-kernel.  When running in a VM, you can
+either run the kernel directly from qemu, or put it in a virtual machine image
+file. 
 
 
-I run my kernels either in KVM (Qemu) or off a bootable USB stick.
+If you don't want to bother with the image, skip this section.  I tend to run
+my images off an image file, since qemu acts more like hardware (as far as
+multiboot goes).  The downside is the boot up is slower, especially if you have
+a large kernel (>100MB).  It also takes some effort to set up the VM image.
 
 
-You'll need an image file that looks like a hard disk to boot qemu off of.  I
-put one similar to mine at: http://akaros.cs.berkeley.edu/files/hdd268mb.img
+If you are still reading, you'll need an image file that looks like a hard disk
+to boot qemu off of.  I put one similar to mine at:
+http://akaros.cs.berkeley.edu/files/hdd268mb.img
 
 It's around 268MB (256MiB, or whatever).  If you want to make your own, check
 out Documentation/howtos/make-bootable-grub-hdd.txt.  That's actually the
 
 It's around 268MB (256MiB, or whatever).  If you want to make your own, check
 out Documentation/howtos/make-bootable-grub-hdd.txt.  That's actually the
@@ -201,9 +240,10 @@ don't call it hdd64mb.img on my dev machine).
 Personally, I always have hdd.img mounted.  Some of the other devs have make
 targets that mount and umount it.  Whenever I reboot my development machine, I
 run a script (as root) that mounts the image file and sets up a few things for
 Personally, I always have hdd.img mounted.  Some of the other devs have make
 targets that mount and umount it.  Whenever I reboot my development machine, I
 run a script (as root) that mounts the image file and sets up a few things for
-networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll need
-to edit this to use it, and feel free to comment out the networking stuff.
-That's for using networking in qemu.
+networking.  I put a script I use for this in scripts/kvm-up.sh.  You'll likely
+want to copy it to the directory *above* the akaros root directory and edit it
+accordingly. Feel free to comment out the networking stuff.  That's for using
+networking in qemu.
 
 Now that your image file is mounted at mnt/hdd, you'll want to copy your
 freshly built kernel to the root of the image.  I have a make target in my
 
 Now that your image file is mounted at mnt/hdd, you'll want to copy your
 freshly built kernel to the root of the image.  I have a make target in my
@@ -221,13 +261,15 @@ all: kvm
 Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
 -l and check the timestamp).
 
 Now, make kvm.  You should be able to see the new kernel in mnt/hdd/ (do an ls
 -l and check the timestamp).
 
-
 3.6 Running Qemu
 ---------
 Here is the command I use to run qemu/kvm.  It's evolved over the years, and it
 will vary based on your linux distribution.  Don't run it just yet:
 
 3.6 Running Qemu
 ---------
 Here is the command I use to run qemu/kvm.  It's evolved over the years, and it
 will vary based on your linux distribution.  Don't run it just yet:
 
-$ 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
+$ qemu-system-i386 -s -enable-kvm -cpu phenom -smp 8 -m 2048 -nographic -monitor /dev/pts/3 -net nic,model=e1000 -net tap,ifname=tap0,script=no mnt/hdd.img
+
+If you skipped making a virtual machine image, replace "mnt/hdd.img" with
+"-kernel obj/kern/akaros-kernel".
 
 The -monitor is the qemu monitor, which is a CLI for qemu.  Pick a
 tab/terminal/pty in Linux that you will only use for qemu monitoring, and enter
 
 The -monitor is the qemu monitor, which is a CLI for qemu.  Pick a
 tab/terminal/pty in Linux that you will only use for qemu monitoring, and enter
@@ -277,7 +319,7 @@ $ vi tests/hello.c
 $ make tests
 (new version in obj/tests/hello)
 
 $ make tests
 (new version in obj/tests/hello)
 
-$ ../fill-kfs.sh
+$ make fill-kfs
 (updates kfs)
 
 $ make
 (updates kfs)
 
 $ make
@@ -317,10 +359,14 @@ be able to see what's going on all the time.  (unlike when building glibc...).
 
 Oh, and don't forget to:
 
 
 Oh, and don't forget to:
 
-$ ../fill-kfs.sh (or whatever you do)
+$ make fill-kfs
 
 to make sure you run the new pthread_test. 
 
 
 to make sure you run the new pthread_test. 
 
+Additionally, when switching between 32 and 64 bit x86, make objclean before
+filling KFS.  This is the easiest way to make sure you get the appropriate
+libraries loaded in KFS.
+
 Early on as a dev, there are lots of times where you accidentally don't run the
 right program (or kernel) and won't understand why your change isn't happening.
 A few printk("WTF\n")'s later, you realize you didn't have the hdd.img mounted,
 Early on as a dev, there are lots of times where you accidentally don't run the
 right program (or kernel) and won't understand why your change isn't happening.
 A few printk("WTF\n")'s later, you realize you didn't have the hdd.img mounted,