proc: fix refcounting bug in proc_get_set()
[akaros.git] / GETTING_STARTED.md
index 3eb0a04..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.
 
 ----------------------------
 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:
 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.
 
 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 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):
 
 
 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
 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`
 
 
 `$ make tests`
 
@@ -155,7 +173,7 @@ see this, then you probably didn't actually fill KFS properly.
 
 ```
        Building initramfs:
 
 ```
        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
 
 ### 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.
 
 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
 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
 
 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
@@ -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
 
 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.
 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.
@@ -274,8 +292,8 @@ networking, replace the "`-net user`" section with:
 
 `-net tap,ifname=tap0,script=no`
 
 
 `-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).
 
 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
 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
 doing a couple `hello worlds`, you're set.
 
 Alternatively, you could have a make target to run qemu, which also touches all