Install and Build OS 161

Step 1: Set up your environment.

In order to use OS161, the operating system you will use and develop in this course, you will need access to a few tools, namely the simulator on which OS161, called System/161, the OS161 cross-compiler, the debugger and binary utilities. There are several ways in which you can access these tools:

Option 1. On your laptop in a Docker container.
Option 2. On a virtual machine appliance, which can be installed on your laptop.
Option 3. On the ECE department server.
Option 4. On your own Mac machine.
Option 5. On your own Ubuntu Linux machine.

Options 4 and 5 are not supported by our staff, so use them only if you are prepared to debug things on your own if something goes wrong. You only need to set up the tools in ONE environment -- pick the one that works best for you. If you think you need the tools set up in more than one way (e.g., on the department server, so you can work from the lab machine and on your home Windows desktop) you are welcome to do that, but you are NOT required.

Option 1: Preparing to use the tools on your laptop in a Docker container.

Follow these instructions.

Option 2: Preparing to use the tools on a virtual machine appliance.

Using tools installed on the department server requires you to have a network connection. Sometimes you may wish to work from home on your own laptop in a disconnected mode. In that case, you can install a virtual appliance with all the tools packaged inside. Follow these instructions if you would like to have that option.

To make tool installation easier on a variety of hardware and operating systems, we have created a virtual appliance with the tools already installed. To run this appliance, you will first need to install software that knows how to run virtual machines. In our case, this will be Virtual Box.

Follow these instructions for installing Virtual Box on MacOS, Windows or Linux and then installing the CS50 appliance. Note that we will be working with the 2014 version of the appliance. Make sure that you can launch your appliance.

There are two ways you can use your CS50 appliance. You can use your appliance in the window that pops up when you start it up. Alternately, you can access it remotely from your host (real) computer via a network connection. Look at the bottom-right corner of the machine window. You will see an IP address, such as 192.168.166.128. You can ssh (or sftp) to this IP address as ssh jharvard@192.168.166.128. This way, you can treat the appliance as a server and edit files as you would on any remote server, either with an editor that can use sftp, such as TextWrangler or Notepad++, or using ssh and vim, emacs, nano, etc. If you are connecting to the virtual machine or want to install new programs in it, you will need the password for jharvard. The password is crimson.

For more information on how to use your appliance: connecting to it, copying files, setting up Dropbox, taking a screenshot, etc., click here.

Now, depending on which appliance you chose to download, you have two options:

If you downloaded an appliance without tools, you must install the tools that we will be using in this class yourself. If you wish to do so, please follow instructions here.
An easier way is to download an appliance with tools already installed. Then you can simply launch this appliance in your virtual box and you do not need to install your own tools.

Option 3: Preparing to use the tools on the department server.

This is the easiest method to access the tools. All you have to do is to ssh to ssh-ubuntu.ece.ubc.ca and log on with your ECE account. If you do not know what ssh is and how to use it, read here. Then, find out what shell you are running by typing:

ps

at the prompt. If you see 'bash' in the list, like so:

ssh-linux2:~/> ps
PID   TTY      TIME CMD
3100  pts/7    00:00:00 ps
13740 pts/7    00:00:00 bash

then you are running a Bourne shell. If you see a 'tcsh' or 'csh', like so:

ssh-linux2:~/tools> ps
PID   TTY      TIME CMD
3100  pts/7    00:00:00 ps
13740 pts/7    00:00:00 tcsh

then you are running a variant of a C-shell. If you are running a Bourne shell, add the following lines to the end of your ~/.bashrc file, like so:

echo 'PATH=/ubc/ece/home/af/other/os161/tools/sys161/bin:/ubc/ece/home/af/other/os161/tools/os161/bin:$PATH' >> $HOME/.bashrc

And for C-shell:

echo 'set path = ($path /ubc/ece/home/af/other/os161/tools/sys161/bin /ubc/ece/home/af/other/os161/tools/os161/bin)' >> $HOME/.cshrc

Then type source .cshrc or source .bashrc depending on which file you modified.

Type: which sys161 to make sure that the system is able to find the tools. If the binary is located, you are all set!

Course staff: If you would like to set up the tools on a new Ubuntu system, this script will help you. To install tools on Arch Linux, use this script. The Arch Linux script was contributed by Jade Lovelace. It also contains a fix for a multiple-definition compiler error that may appear on other systems.

Option 4: Preparing to use the tools on MacOS

These instructions will teach you how to install all the needed tools on a MacOS, so you can work from your Mac system without needing a network connection.

Option 5: Set up the tools on your own Ubuntu Linux machine

All you need to do is to download the following script:

  wget http://people.ece.ubc.ca/os161/download/cs161-ubuntu-darwin.sh

Depending on the software installed on your system, you may or may not have pre-requisite packages, such as bmake, libncurses, libmpc, etc. If unsure, open the script you just downloaded and uncomment the line at the top of the script, which installs these packages, so that this:

#echo '*** Installing Ubuntu packages ***' 
#sudo apt-get -y install bmake ncurses-dev libmpc-dev

turns into this:

echo '*** Installing Ubuntu packages ***' 
sudo apt-get -y install bmake ncurses-dev libmpc-dev

Now run the script:

$ bash ./cs161-ubuntu-darwin.sh

Step 2: Get the OS161 source code and set up the source management

Course staff: click here for instructions to import the source tree into an empty repo. Here are the old instructions for creating the master repo on the ssh.ece server.

In order to manage your source code, collaborate on the code with your partner and submit your assignments, you will be using a software version management system called Git. Read this short introductory guide to git before proceeding.

As explained in the guide, though git is a distributed environment, it is customary to have one clone of the repository reside on a more secure backed up server where your files are less likely to get lost or become compromised. In this document we will refer to this repository as the "master" repository. So the very first thing that you will do is create such a master repository for yourself. Then you will clone this repository either on your CS50 appliance or in another directory on the ssh.ece server, so you can develop, build and debug the code there.

You will create the master repository on UBC GitHub and import the OS161 base code into it. Follow the instructions here.

Step 3: Configure and build the source tree

These instructions are adapted from here.

To build your OS161 for the first time, refer to a "quick" set of instructions below. For future building of OS161 we expect you to be familiar with a long set of instructions found here. They explain more about each step of the build process and when you need to rerun it.

The instructions below assume that you have followed the steps above and that you have an environment with the tools installed, either in your virtual appliance or on the ssh.ece server, and that you have a clone of your master git repository either on the virtual appliance or somewhere in your home directory at ssh.ece server. We assume that your git clone lives in the ~/os161/src directory. In the shell type the following commands:

Configure the build.

cd ~/os161/src
./configure --ostree=$HOME/os161/root

Build userland.
```
bmake
bmake install
```
Configure a kernel.
```
cd kern/conf
./config DUMBVM
```

Compile and install the kernel

cd ~/os161/src/kern/compile/DUMBVM
bmake depend
bmake
bmake install

Step 4: Run your kernel on System/161

And now, to the most exciting part: run your kernel on the System 161 simulator. The manual for System/161 can be found here.

First off, you need a configuration file. We will simply use an existing sample file and copy it into the root tree of your kernel:

  wget people.ece.ubc.ca/os161/download/sys161.conf.sample -O ~/os161/root/sys161.conf

Then, run it!

cd ~/os161/root
sys161 kernel

os161_ubc

Your portal to resources on OS161 at UBC.

Useful Links