Getting Started with Weenix - CMPS-6770/handout-2024 GitHub Wiki

Getting Started

To get started, accept the Weenix Assignment from GitHub classroom. Make sure to read the page Development Guide before running Weenix. This gives instructions for setting up your development environment.

Once you've set up your development environment, you can run Weenix.

In order to run Weenix, we must run it in a virtual machine. We use VirtualBox and Vagrant for this.

On a machine with VirtualBox and Vagrant installed (our cmps-lab development server is fully setup!), navigate into your weenix project root.

Start a VM using vagrant:

vagrant up

The first time you do this, vagrant will need to download the virtual machine OS and install it. This will take a few minutes.

Once booted, you will need to ssh in:

vagrant ssh -- -Y

The -Y is case sensitive and enables X11 forwarding which is necessary to see weenix run.

Now you should be in the VM you will run Weenix in.

Vagrant VMs maintain a shared directory between the host and the VM. In the VM, this directory is /vagrant. On the host, the shared directory is the one you ran vagrant in. As a result, if you change directory into /vagrant, you should see all your Weenix files.

cd /vagrant

Now you can run Weenix!

To run Weenix, use the following commands:

make
./weenix -n

(note that the -n is only required for the first run, more on this later. The -n flag will run Weenix with a new disk).

Your Weenix should run and then panic with the following error:

C0 P0 main/kmain.c:181 initproc_start(): Not yet implemented: PROCS: initproc_start, file main/kmain.c, line 181
C0 P0 panic in main/kmain.c:96 kmain():
Returned to kmain()

C0 Halting.

The terminal will then hang. Kill it using ctrl-c.

To shut down your vagrant VM:

exit

This will return you to the development server.

You can shut down the VM:

vagrant halt

When you aren't running and testing Weenix, please shut down your vagrant VM to save RAM and CPU.

If you've made it through these instructions, you are all set to start working on Procs! (Note that all future assignment handouts are already on the Wiki).

If you are stuck, please post to Piazza!

Note that although we're providing some functions, you'll still have to implement everything listed by the output of make nyi. To run Weenix with gdb, you should run the following:

./weenix -n -d gdb

We have provided some scripts below on how to use shortened commands to run Weenix and gdb. Check out the Tools page for tips and tricks that we recommend when working on Weenix.

Scripts

You may have noticed that when running Weenix in GDB, the QEMU window annoyingly stays open even after you quit GDB. You've probably noticed that running Weenix requires first cd'ing into the directory containing Weenix or typing the absolute path of the Weenix executable. The TAs a couple years ago wrote two very simple functions that rectified these problems: rw and wg (short for "run Weenix" and "Weenix GDB"). The first script will run Weenix (with the -n argument, if provided), while the second will run Weenix with GDB (with the -n argument, if provided), and will close QEMU after GDB exits. Both commands can be run from any directory. Inside Vagrant, these commands are preinstalled. On other systems, copy and paste the text found in weenix-scripts.txt into your .bashrc to use them (cat <weenix home dir>/weenix-scripts.txt >> ~/.bashrc). Make sure to source it afterwards (source ~/.bashrc). You must also replace <weenix home dir> with the directory where you normally run ./weenix. You can find this using pwd.