A simple guide to have running the os161 kernel in Arch Linux

OS161_set-up.md

A simple guide to have running the os161 kernel in Arch Linux

This are some notes for the course OS 161 from ops-class.org (based on the OS 161 course from Harvard).

Getting started

You will need some tools. A nice Text Editor or a fancy IDE for C, I usually go for gedit, or sometimes vim.

Then you will need to install all the toolchain, the simulator for the course plus some other tools.

Before that I will be using "yay" as my "aur helper". yay is a wrapper around pacman, so it extends pacman's abilities but it also download and build the packages in the aur repository. If you don't know what AUR is or do not know what is an aur helper visit the wiki https://wiki.archlinux.org/index.php/Arch_User_Repository https://wiki.archlinux.org/index.php/AUR_helpers

Choose the aur helper of your liking.

yay -S mips-harvard-os161-binutils mips-harvard-os161-gcc48 mips-harvard-os161-gdb sys161 bmake git wget

The first three packages (*-binutils *-gcc48 *-gdb) are the assembler, linker, crosscompiler and the debugger toolset necesary to develop the OS.

sys161 It's the simulator for the Mips Architecture that will run the OS.

Those 4 packages (mips-harvard-os161-binutils mips-harvard-os161-gcc48 mips-harvard-os161-gdb sys161) are part of the AUR, if you do not use an AUR helper you will have to go to https://aur.archlinux.org/ And take the appropiate action to build them.

bmake is a bsd version of make, in general you will have GNUMake in your system, but it uses different syntax so you need bmake to build the system otherwise it will fail.

git is a program for version control, you should know.

wget it's a tool to download things you can do it without it.

Get the sources

Go to the folder where you want to download the sources for the kernel. We will use git fot this

cd ~/src
git clone https://github.com/ops-class/os161.git

The symbol ~ is a short hand for my (your) home directory /home/user, cd ~/src it's equivalent to cd /home/user/src

git will create the folder os161 inside of /home/user/src and we will work from there

Configure the OS

Now we need to configure the OS so bmake can build all the things.

Go to the main directory of your sources

cd /home/user/src/os161

This time we need to call the configure script, as you can see if you use ls there is a configure file in it there. This is a script that takes only one parameter --ostree, it indicates where we want bmake put all the things. In general you want this to be a subdirectory of your project, but other appropiate location should be fine. From now on I will use root as the root directory of my OS.

./configure --ostree="$(realpath ./root)"

realpath it is a directive in the configure script. It takes an argument and appends the whole rute to the current directory, in this case should return /home/user/src/os161/root That will be the root directory of our OS.

After running configure, a new file defs.mk is created. It has all the deffinitions bmake will use to build the OS.

Configure the Kernel

We are not over. Additionally to configure the OS, we need to configure the kernel too. Go to the Kernel's "configuration" subdirectory.

cd kern/conf

And tell the config script what kind of configuration we want. For the Assignment 0, ASST0 we want DUMBVM

./config DUMBVM

Make all the things

Now we need to call bmake. We will need three steps. One to make all the dependencies, one to make the kernel and one to move all the files to the location that will be our OS root (the osstree we defined before). [NO LOTR reference]

Go to the compile directory of our kernel.

cd ../compile/DUMBVM

And make make make all the things.

First all the dependencies.

bmake depend

If we succeded (no errors), it's time to make the kernel

bmake

And again if no errors move the things, in this case we need to run bmake install

bmake install

If everything went fine, now we have our vm almost ready to run.

Go to the root directory or the directory you defined as osstree

cd ../../../root

Run the Simulator

Now there's only one more thing to do, we need one more configuration file, that will set some parameters for our simulator.

Make sure you are in the root subdirectory of the os161 folder and download the configuration file.

wget https://www.ops-class.org/files/sys161.conf

That should be it, just fire the Simulator

sys161 ./kernel

Getting Help

There are plenty of materials in https://www.ops-class.org You can access the forums in https://discourse.ops-class.org/ for more help.

Would just like to observe that if you're git cloneing into a directory that has spaces, you're going to have a bad time:

1. ./configure --ostree=$(realpath ./root) will need to become ./configure --ostree="$(realpath ./root)"
2. bmake install will probably fail, complaining about too many arguments

If you really want to be able to access your nifty os161 directory from a directory whose tree name contains spaces, I would recommend that you:

1. git clone into a directory whose full name contains no spaces,
2. Finish the rest of the excellent build instructions here,
3. Create a symlink from your desired directory into wherever you built os161, like cd "/path/to/the/best directory that contains spaces/whatever" && ln -sv /path/without/space/to/directory/where/you/built/os161 ..

Other than that, these instructions are great and still work as of the datetime of this comment.

Thank you. That's a really helpful advice. (Both of them)
In general I do not use directories with spaces because I'm wary about them. In my experience spaces are such ambiguous things. They separate words, instructions, arguments, are visual aids (indentation) etc. So I usually don't like them that much.

For the second part yes, and thank you. That's a testament of the power of the unix tools, the work made by the professors of the OS161 course (and the ops-class.org), the work made by the sys161 aur package's maintainer and me (the maintainer of the mips-harvard-os161-binutils mips-harvard-os161-gcc48 mips-harvard-os161-gdb aur packages).

If you are not aware in https://www.ops-class.org they have materials and contact info for the instructors they are really helpful if you need help.
And do not hesitate to post in the forums in https://discourse.ops-class.org/ all your questions regardless if you are enrolled or not.