proc: don't throw from proc_get_set()
[akaros.git] / GETTING_STARTED.md
index ce3ba94..20a21d1 100644 (file)
@@ -49,6 +49,14 @@ usually idling in there (alone), and if I'm at my computer, I'll respond.
 ----------------------------
 I'll describe how to get x86 working.  RISCV is similar.
 
+To start off, make sure AKAROS_ROOT and AKAROS_XCC_ROOT are set in your
+environment.  AKAROS_ROOT is the Akaros repo directory.  AKAROS_XCC_ROOT is a
+directory of your choosing where the toolchain will be installed (more on that
+in Section 3.1 below).
+
+I also suggest running `scripts/one-time-setup.sh`, once per `git clone`.  This
+performs various checks and other setup.  Check it out for details.
+
 The first step is to configure the kernel.  Targets like `config`,
 `menuconfig`, and some of the other KBuild targets work.  Defconfig gives you a
 default configuration.  For example, to config for 64-bit x86:
@@ -92,14 +100,20 @@ template to work from.
 You need to set your `INSTDIRS` to some place where you want the cross compiler
 installed.  I have a directory named `akaros-gcc-glibc` for this.
 
+Additionally, you must set the environment variable `$AKAROS_XCC_ROOT` to point
+to the installation directory for your architecture.  For instance, my
+AKAROS_XCC_ROOT is:
+
+`/home/brho/classes/akaros/akaros-gcc-glibc/install-x86_64-ucb-akaros-gcc/`
+
 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/akaros/akaros-gcc-glibc/install-x86_64-ucb-akaros-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 (for example):
 
@@ -136,7 +150,11 @@ architecture until a new `ARCH` is selected (i.e. via `make ARCH=xxx defconfig`
 etc.)
 
 ### 3.3 Userspace
-To build userspace and test programs:
+First, you'll need to build a few common applications and libraries:
+
+`$ make apps-install`
+
+Then you can build the tests and small utility programs:
 
 `$ make tests`
 
@@ -155,7 +173,7 @@ see this, then you probably didn't actually fill KFS properly.
 
 ```
        Building initramfs:
-               Adding kern/kfs to initramfs...
+       Adding kern/kfs to initramfs...
 ```
 
 
@@ -192,7 +210,7 @@ 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/akaros-kernel`.  When running in a VM, you can
+should be sitting at `obj/kern/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.
 
@@ -220,10 +238,10 @@ Anyway, I put that img in `AKAROS-ROOT/mnt/`, and make a folder next to it:
 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 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`.
+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
@@ -246,7 +264,7 @@ 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-x86_64 -s -enable-kvm -cpu kvm64 -smp 8 -m 4096 -nographic -monitor /dev/pts/3 -net nic,model=e1000 -net user,hostfwd=tcp::5555-:23 -net dump,file=/tmp/vm.pcap -drive file=mnt/hdd.img,index=0,media=disk,format=raw
+$ qemu-system-x86_64 -s -enable-kvm -cpu kvm64 -smp 8 -m 4096 -nographic -monitor /dev/pts/3 -net nic,model=e1000 -net user,hostfwd=tcp::5555-:22 -net dump,file=/tmp/vm.pcap -drive file=mnt/hdd.img,index=0,media=disk,format=raw
 ```
 
 If you skipped making a virtual machine image or want to run the kernel
@@ -255,7 +273,7 @@ to `format=raw`) 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
-`tty'.  Whatever it tells you, put in place of `/dev/pts/3`.  I've been using
+'`tty`'.  Whatever it tells you, put in place of `/dev/pts/3`.  I've been using
 the same tab for about 4 years now.  In that tab, enter '`sleep 999999999`'.
 Qemu will still access it, but you won't have to worry about bash trying to
 handle your inputs.
@@ -264,7 +282,7 @@ handle your inputs.
 spawning off a fake cpu crt/monitor.
 
 The command as written uses qemu's user networking.  It's emulated and a little
-slow.  The example I have alo forwards port `5555` on the host to port `23` on
+slow.  The example I have alo forwards port `5555` on the host to port `22` on
 the guest.  Customize it according to your needs.
 
 Another option for networking is to set up a tun/tap device.  I use this on
@@ -274,8 +292,8 @@ networking, replace the "`-net user`" section with:
 
 `-net tap,ifname=tap0,script=no`
 
-The "`-net dump`" option saves a pcap trace of the network traffic.  This is very
-useful for debugging, but probably not needed for most people.
+The "`-net dump`" option saves a pcap trace of the network traffic.  This is
+very useful for debugging, but probably not needed for most people.
 
 Feel free to pick different values for the number of cpus and RAM (8 and 4096
 in the example).
@@ -375,7 +393,7 @@ 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, or you didn't fill KFS, or you didn't relink your binaries, or you
-forgot to save all files in `vi1 (and not just the current buffer).  But after
+forgot to save all files in `vi` (and not just the current buffer).  But after
 doing a couple `hello worlds`, you're set.
 
 Alternatively, you could have a make target to run qemu, which also touches all