Homework 1: lots of tools, and a simple program

In this homework, we primarily familiarize ourselves with a number of tools we'll be using throughout the semester. Partial credit is hard to get in this homework - in order to get something running, and manage to submit the homework on time, you probably have to get it all right, so please get started early as there are many stumbling blocks along the way.

The instructions below are very minimal. Expect to have to do some googling along the way to figure out how to get things to work on your end. For a great manual of git, see http://git-scm.com/book. Make sure to read sections 1-3 to get a good understanding of its operation.

Set up a Linux environment

For this class, you need access to a Linux machine. It is convenient if your laptop is running Linux natively, but many other solutions will work as well. The recommended setup is to use VMWare to run the latest Ubuntu distribution.

To get a free copy of VMWare for your machine, follow these instructions:

• Go to http://go.uic.edu/csvmware
• Click on the "sign in" link at the top
• click on "register"
• select "An account has been created..." and continue with the registration.

You do not need a linux GUI for this class, so you can use a remote Linux server if you cannot use VMWare or another virtual machine emulator. You do need to run xv6 in a VM on your local machine, however. If you do not own a suitable computer, you may use the CS computer labs in SEL. Let me (Jakob) know, as this may take a little extra doing.

Install qemu on your machine

Qemu is a PC emulator we'll be using to run xv6 under. In linux (Ubuntu), apt-get install qemu should do it. On a mac, install Macports, then port install qemu.

Get the xv6 sources, build (under Linux) and run (under Linux or elsewhere)

On your Linux machine, first install git: apt-get install git. Then fetch the version of the xv6 source tree that is hosted at UIC:

git clone http://bits.cs.uic.edu/git/xv6.git

This creates a directory xv6 which contains all the sources. To build xv6, you need a toolchain: compiler, linker, and such. To get the basics, apt-get install build-essential. Now, you should be ready to build and run xv6 under qemu: make qemu.

note: If you are using a Linux machine to build xv6, and a Windows or OS X machine to run xv6 within qemu, there is an extra step involved. First build xv6 make xv6.img, then run it on your machine. On OS X, say qemu-system-i386 -m 512 -hdb fs.img xv6.img. Not sure how it goes on Windows, but should be quite similar.

Create a git branch for hw1

In the xv6 folder, create and check out the branch git checkout -b hw1.

Write a 'divide' program for xv6

xv6 comes with a number of small programs, like ls and cat. You are to create a new program, divide, which takes two integer arguments on the command line, and prints out the value of the first argument divided by the second argument.

Name the program divide.c, and make sure that typing make qemu automatically builds the divide binary just like it builds the other binaries. For a correct implementation, running divide in qemu should produce an output like:

=4 / 5 = 0.8 =

If you install the package expect, you can test your solution by running make test.

Commit your work to the local repository

Stage your modified and added files git add Makefile divide.c, and commit your staged files git commit -m "Homework 1, first attempt".

Submit Homework Using Git

As of January 17 2015, your personal repositories are set up. Follow the instructions here to get those working: AddStudentRepo. Once that is set up and you've followed the instructions, you'll run

git push turn-in hw1:hw1

to push your local hw1 branch up to the turn-in repository.

alternative push methods

If you used a different name for your local branch, or forgot to use a branch altogether, you could also do:

git push turn-in anotherbranch:hw1

or

git push turn-in HEAD:hw1

to push whatever local branch you currently have checked out.

Check your submission

To see that your submission was successfully pushed to your turn-in repository, try this in a new, empty directory:

• git clone cs385:/cs385f16/youruseridhere
• git checkout hw1
• see that the file you added and committed shows up