2016/Infrastructure

From CS61
Jump to: navigation, search

Computer Science 61 and E61
Systems Programming and Machine Organization
Fall 2016

Infrastructure

Download the CS61 Virtual Machine

You will need the CS61 virtual machine for some assignments. You may wish to use it for all assignments as it has been pre-populated with some of the tools we think you'll need during the semester. Most problem sets can also be run on other Linux machines or Mac OS X machines. However, we recommend you at least check your work on the course VM, in case you are accidentally relying on Mac-specific behavior.

  • If you will be using VirtualBox (on either OSX, Linux, or WIndows), download the CS61 Virtual Machine from here. Note that some versions of Chrome may change the file extension to .ovf. If that happens change it back to .ova.
  • If you will be using VMware Fusion (OSX), download the CS61 Virtual Machine from here.
  • If you will be using VMware Workstation on Windows or Linux, download the CS61 Virtual Machine from here.
  • The login and password for the machine (regardless of which you downloaded) are both "vagrant".

Install a virtual machine monitor (VMM)

If you wish to run the course virtual appliance, you will need a virtual machine monitor -- we recommend VirtualBox, but if you already have either VMware Fusion (Mac) or VMware Workstation (Linux or Windows), you should be able to use them. You should however make sure that you are running the latest version of your VMM (version 8 for Fusion; version 12 for Workstation).

You can obtain VirtualBox for Mac (OSX), Windows, or Linux here.

Using VirtualBox

Linux

Prerequisites

  • Before installing VirtualBox on Debian (Jessie) or Ubuntu (Xenial Xerus), make sure you have:
    • Qt 4.8.0 or higher
    • SDL 1.2.7 or higher (this graphics library is typically called libsdl or similar)
    • header file packages (linux-headers and linux-kbuild)
  • For other distributions, or older Debian/Ubuntu releases, see [1]

VirtualBox setup

  • Install the appropriate VirtualBox package for your distribution using one of the methods from [2].
  • Start up VirtualBox.
  • Select Preferences under the File menu.
  • Go to Network -> Host-only Networks.
  • If vboxnet0 is not already listed, click the plus sign on the right hand side, and then vboxnet0 should appear in the box.
  • Select vboxnet0 and, click on the screwdriver icon to the right of the box (the last icon).
  • Under the Adapter section of the new window, check that the settings match the following:
    • IPv4 Address: 192.168.33.1
    • IPv4 Network Mask: 255.255.255.0
    • IPv6 Address:
    • IPv6 Network Mask Length: 0
  • Under the DHCP Server section, make sure that "Enable Server" is selected, and check that the settings match the following:
    • Server Address: 192.168.56.100
    • Server Mask: 255.255.255.0
    • Lower Address Bound: 192.168.56.101
    • Upper Address Bound: 192.168.56.254

At this point, you're now ready to import the CS61 Appliance. Download it from here.

  • Go to the File menu and select Import Appliance.
  • Click Open Appliance, navigate your way to the ova file that you downloaded, and click Open. Then click Next.
  • You should see a summary of the appliance’s settings. Click Import, and the virtual disk image should begin importing.
  • The CS61 Appliance should now appear as "Powered Off" in the box on the left.
  • Highlight the CS 61 appliance and click Start to start the appliance. You should see the Ubuntu startup screen and within a few seconds.

Mac OS X

  • Download the appropriate package for your OS and launch the VirtualBox installer.
  • Once you've completed the installation process, start up VirtualBox.
  • Select Preferences under the VirtualBox menu in your display’s top-left corner.
  • Go to Network -> Host-only Networks.
  • If vboxnet0 is not already listed, click the plus sign on the right hand side, and then vboxnet0 should appear in the box.
  • Select vboxnet0 and, click on the screwdriver icon to the right of the box (the last icon).
  • Under the Adapter section of the new window, check that the settings match the following:
    • IPv4 Address: 192.168.33.1
    • IPv4 Network Mask: 255.255.255.0
    • IPv6 Address:
    • IPv6 Network Mask Length: 0
  • Under the DHCP Server section, make sure that "Enable Server" is selected, and check that the settings match the following:
    • Server Address: 192.168.56.100
    • Server Mask: 255.255.255.0
    • Lower Address Bound: 192.168.56.101
    • Upper Address Bound: 192.168.56.254

At this point, you're now ready to import the CS61 Appliance. Download it from here.

  • Go to the File menu and select Import Appliance.
  • Click Open Appliance, navigate your way to the ova file that you downloaded, and click Open. Then click Continue.
  • You should see a summary of the appliance’s settings. Click Import, and the virtual disk image should begin importing.
  • The CS61 Appliance should now appear as "Powered Off" in the box on the left.
  • Highlight the CS 61 appliance and click Start to start the appliance. You should see the Ubuntu startup screen and within a few seconds.

Windows

  • Download VirtualBox for Windows x86/amd64 from here.
  • In the file manager, right-click on the file and select Run as administrator from the menu that appears. If asked whether you want to allow the following program to make changes to this computer, click Yes.
  • A window entitled Welcome to the Oracle VM VirtualBox 5.1.4 Setup Wizard should then appear. Click Next.
  • A window entitled Custom Setup should then appear. You should not need to change anything. Click Next.
  • Another window entitled Custom Setup should then ask whether you’d like to create a shortcut on the desktop and/or in the Quick Launch Bar. Check all the boxes, then click Next.
  • A window entitled Warning: Network Interfaces might then try to scare you. Don't panic, click Yes.
  • A window entitled Ready to Install should then appear. Click Install.
  • If prompted one or more times whether you would like to install this device software, click Install each time.
  • A few seconds or minutes later, a window entitled Oracle VM VirtualBox 5.1.4 installation is complete should appear.
  • Leave the check box labeled Start Oracle VM VirtualBox 5.4.1 after installation checked, then click Finish. VirtualBox should launch.
  • Select Preferences under the File x menu in your display’s top-left corner.
  • Click Network.
  • Select the Host-only Networks tab. Ideally, you will see VirtualBox Host-Only Ethernet Adapter. If you do not, iclick the plus sign on the right hand side, and select the VirtualBox Host-Only Ethernet Adapter.
  • Click on the screwdriver icon to the right of the box (the last icon).
  • Select the Adapter tab and verify that the settings match the following:
    • IPv4 Address: 192.168.56.1
    • IPv4 Network Mask: 255.255.255.0
    • IPv6 Address:
    • IPv6 Network Mask:
  • Select the DHCP Server tab, and make sure that "Enable Server" is selected, and check that the settings match the following:
    • Server Address: 192.168.56.100
    • Server Mask: 255.255.255.0
    • Lower Address Bound: 192.168.56.101
    • Upper Address Bound: 192.168.56.254
  • Exit out of the Preferences dialog box.
  • In the File Manager, find the CS61-Appliance.ova file that you downloaded and double click on it.
  • This should bring you to an Import Virtual Appliance screen. Click on Import.
  • After a few minutes, the CS61 Appliance should appear in the "Powered Off" state. The import may claim that it will take about 30 minutes; don't believe it; it will complete in under 5.
  • Select the appliance and click Start to run it.
  • If you get a VirtualBox Error that says, "Could not start the machine CS61-Appliance because the following physical network interfaces were not found." select Change Network Settings. Click on the Adapter 2 tab and verify that you have VirtualBox Host-Only Ethernet Adapter in the name field. Click OK.
  • You may get one more error about not finding the vagrant directory; you can ignore this too.
  • Finally, you'll see the Ubuntu desktop. (You can close the little boxes at the top that explain about mouse capture.)

Running the CS61 VM with VMWare

Mac OSX (VMware Fusion 8)

  • Visit the VMware Software Center for CS50 and sign in with your Harvard University ID number and pin. You will automatically receive an account at the Software Center. Its user name and initial email address will both be your Harvard email address.
  • The VMware Software Center is set up like a store. On the "store front" page, click on VMware Fusion 8. If you see both a free and a non-free offering of the product, choose the free one.
  • Click the Add to Cart button, then proceed through the check-out process until you reach a screen with a Start Download button. Click the Start Download button to download the installer for Fusion8.
  • On the store front page, click on Your Account/Orders under the Hello, <your email> menu. Click on View Details to see your Serial Number. You will need that serial number the first time you try to run VMware Fusion.
  • Click on the file you downloaded to mount the VMware Fusion icon on your desktop.
  • Click on the VMware Fusion (or VMware Fusion.app) icon in the new window, click Open if prompted, and type your password if prompted. Follow the instructions to install Fusion 8. When prompted for a license key, use the serial number generated for you by the VMware Software Center.

You are now ready to import the CS61 Appliance (Virtual Machine or VM) into VMware Fusion.

  • Launch Fusion
  • Under the file menu, select Import and then browse to the CS61-Appliance-fusion.ova file that you downloaded.
  • When Fusion begins importing the appliance, you may see the message "The import failed because pathname to .ova file did not pass OVF specification conformance or virtual hardware compliance." Click on Retry, which should succeed (albeit slowly -- importing the appliance will take some time).
  • You may see the message, "Cannot connect the virtual device ide0:0 because no corresponding device is available on the host." You'll be asked if you want to try to connect to this device every time you power up. Select no.
  • You may also see a message indicating that the VBoxClient is not running; you can safely ignore this message.
  • After a minute or two, your VM will boot and you'll have the Ubuntu Desktop displayed. You're ready to go!

Windows (VMware Workstation 12)

  • Visit the VMware Software Center for CS50 and sign in with your Harvard Key. You will automatically receive an account at the Software Center.
  • The VMware Software Center is set up like a store. On the "store front" page, click on VMware Workstation 12.
  • In the drop-down menu labeled Choose a platform, make sure that Windows is selected. Click the Add to Cart button, then proceed through the check-out process until you reach a screen with a Start Download button. Click the Start Download button to download the installer for Workstation 12.
  • On the store front page, click on Your Account/Orders under the Hello, <your email> menu. Click on View Details to see your Product Key.
  • Click on the file you downloaded and launch VMware Workstation’s installer. If you are asked whether to allow the installer to make changes to your computer, enter your password, and click Yes.
  • A window entitled Welcome to the VMware Workstation Pro Setup Wizard should appear. Click Next.
  • When prompted with a license agreement, select I accept the terms in the license agreement, then click Next.
  • You'll next come to a Custom Setup window. You need not change the Install Location. You'll probably want to select Enhanced Keyboard Driver, and then select Next.
  • On the next screen, User Experience Settings uncheck the Help improve VMware Workstation Pro box and click Next.
  • When prompted about Shortcuts, leave both boxes checked and click Next.
  • You'll now come to the Ready to install VMware Workstation Pro screen; select Install. It will take a minute or two for the installation.
  • When you come to the Completed the VMware Workstation Pro Setup Wizard screen, click on License, and paste the license key that you got from the VMware store. Then click Finish.

You are now ready to import the CS61 Appliance (Virtual Machine or VM) into VMware Workstation.

  • Launch VMware Workstation
  • Select the "Open a Virtual Machine" choice.
  • Browse to the location to which you downloaded the CS61-Appliance-vmware.ova file and select it.
  • You will then be given the option to change the name of the Appliance and select a different directory into which to store your VM; we recommend keeping the defaults, so just click Import.
  • When Workstation begins importing the appliance, you will see the message "The import failed because pathname to .ova file did not pass OVF specification conformance or virtual hardware compliance." Click on Retry, which should succeed (albeit slowly -- importing the appliance will take some time).
  • After a few minutes, the import will complete and you should have a tab in Workstation that says "CS61 Appliance." Click on "Power on this virtual machine"
    • You may get a message about the keyboard hook timeout -- if you do, click OK.
    • If you get a message that the VMware Authorization Service is not running, click on the Windows icon and select Windows Administrative Tools. From there select Services. On the list of services, you should see the VMware Authorization Service. If it is not started, start it.
    • You may see the message, "Cannot connect the virtual device ide0:0 because no corresponding device is available on the host." You'll be asked if you want to try to connect to this device every time you power up. Select no.
    • You may see a message the the VBoxClient isn't running; ignore it.
  • Finally, you'll see the Ubuntu desktop and your VM is ready to go!
  • After you've gone through this import once, the next time you want to start your VM, you will want to select the machine in the Virtual Machines folder instead of loading the .ova file again.

Linux (VMware Workstation 12)

  • Visit the VMware Software Center for CS50 and sign in with your Harvard University ID number and pin. You will automatically receive an account at the Software Center. Its user name and initial email address will both be your Harvard email address.
  • The VMware Software Center is set up like a store. On the "store front" page, click on VMware Workstation 12. If you see both a free and a non-free offering of the product, choose the free one.
  • In the drop-down menu labeled Choose a platform, make sure that Linux is selected. Click the Add to Cart button. If you receive a message saying "The platform of the product you have chosen appears to be different than the computer you are presently using. Are you sure you would like to add this product to your cart?" you can ignore it.
  • Proceed through the check-out process until you reach a screen with a Start Download button. Click the Start Download button to download the installer for Workstation 12.
  • On the store front page, click on Your Account/Orders under the Hello, <your email> menu. Click on View Details to see your Product Key.
  • Once you have downloaded the .bundle file, and make it executable before running it:
    • chmod +x VMware-Workstation-Full-12.1.0-3272444.x86_64.bundle
    • sudo ./VMware-Workstation-Full-12.1.0-3272444.x86_64.bundle
  • Go through the steps presented by the installer (the default settings should be fine) and enter the Product Key when prompted for a license key.

You are now ready to import the CS61 Appliance (Virtual Machine or VM) into VMware Workstation.

  • Launch VMware Workstation
  • Select the "Open a Virtual Machine" choice.
  • Browse to the location to which you downloaded the .ova file and select it.
  • When Workstation begins importing the appliance, you will see the message "The import failed because pathname to .ova file did not pass OVF specification conformance or virtual hardware compliance." Click on Retry, which should succeed (albeit slowly -- importing the appliance will take some time).
  • After a few minutes, the import will complete and you should have a tab in Workstation that says "CS61 Appliance." Click on "Start up this guest operating system."
  • Finally, you'll see the Ubuntu desktop and your VM is ready to go!

Updating your compiler

The CS61 VM, unfortunately, has a relatively old compiler (GCC-4.8). Here’s how to upgrade the CS61 VM to GCC-6, a more modern compiler.

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-6
sudo update-alternatives --install /usr/bin/cc cc /usr/bin/gcc-6 50

On Mac OS X, install a newer compiler with Homebrew. I've installed the gcc-6 package. Then you can specify a specific compiler like so:

make SANITIZE=1 CC=gcc-6

Version control with Git

We will be using git with GitHub Classroom for turning in problem set submissions and version control.

What is git?

Git was developed by Linus Torvalds for development of the Linux kernel. It’s is a distributed version control system, which means it supports many local repositories which each track changes and can synchronize with each other in a peer-to-peer fashion. It’s the best widely-available version control system, and certainly the most widely used. For information on how to use git, see:

Cloning the problem set repository

Problem sets will be released using the cs61/cs61-psets repository.

Please click this link to create your own private clone of the problem sets repository. You’ll clone that repository onto your computer, do work there, and then push your work upstream to the GitHub-hosted repository for us to grade.

Here’s how it should work.

  1. Click the link.
  2. Log in to GitHub, or create an account.
  3. The link should automagically clone the repository. For instance, if your account name was kohler-dumb, you should get a repository called cs61/cs61-f16-psets-kohler-dumb.

Working with a partner? No problem. Find out their GitHub username, and then add them to your repository as a collaborator using Settings > Collaborators & teams.

Teaching GitHub about your identity

The easiest way to access GitHub repositories is using an SSH key, a secret key stored on your CS61 VM that defines your identity. This handy HCS tutorial may be useful to teach you about SSH; or just follow the steps below to create a key for your virtual machine.

  1. Launch your VM and open a terminal.
  2. Run ssh-keygen -t rsa -b 2048 and follow the instructions.
    • Press enter to use the default file path and key name (should be ~/.ssh/id_rsa).
    • Choose a password or leave it empty.

This creates your ssh keys, which live in the directory ~/.ssh. Your public key is in the file ~/.ssh/id_rsa.pub.

Finally, tell GitHub about this key.

  1. Run cat .ssh/id_rsa.pub to display your public key.
  2. Copy your public key (that is, select the text on the screen, and copy it to the clipboard).
  3. In GitHub, go to your profile settings page (accessible via the upper-rightmost link—this looks like a bunch of pixels for new accounts). Select “SSH and GPG keys” and hit the “New SSH key” button. Then copy and paste the contents of your ~/.ssh/id_rsa.pub file into the “Key” section. Give the key a sensible title, hit the “Add SSH key” button, and you’re good to go.

Creating a local clone

Once GitHub knows your SSH identity, you’re ready to clone your problem set repository and start doing work! Here’s how to get a local copy of the repo on your machine:

  • Launch your VM and open up a terminal.
  • Configure your git "identity":
     git config --global user.name "FIRST_NAME LAST_NAME"
     git config --global user.email "YOUR_@COLLEGE_EMAIL"
  • Execute the following command:
     git clone REPO_URL

where REPO_URL is the URL for your repository. This will be something like git@github.com:cs61/cs61-f16-psets-yourname.git, and can be obtained on GitHub by clicking the “Clown or download” button. You want to clone using SSH, not HTTPS, so you might need to click “Use SSH”.

Troubleshooting

If you are having any trouble with your keys (e.g., you cannot clone a repo because "the connection timed out"), check if your firewall is blocking port 22, and open port 22 if it is blocked. You can use your favorite search engine to figure out how to do this.



Obtaining future problem sets

The following should be done every time a new pset is released or an old pset is updated.

This will download the latest pset directory into your repo.

Another way that’s convenient long-term is to add a handout remote to your repository. That works like this:

 git remote add handout git://github.com/cs61/cs61-psets.git

Now you can:

  • Fetch and merge new code with git pull handout master
  • Compare the handout code with your code with git diff handout/master

Submitting problem sets

Be sure that git status (from your “cs61-f16-psets-yourname” directory) reports that you have no uncommitted changes.

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.

nothing to commit, working directory clean

If git status reports that you have uncommitted changes, you'll need to commit these changes! Read through our Git tutorial for details.

Then, run git push, and be sure Git reports that everything is up-to-date:

$ git push
Everything up-to-date

Head over to the grading server and make sure that your code passes all tests you expect it to. The first time you visit the grading server, enter your official email address for the username (that will be your college.harvard.edu address if you are a college student and the email address you used when you registered for the class if you are an extension student. Then request a password reset. Once you've got your password, you can log into the grading server and enter the URL of your repository.

Obtaining lecture code

The code we’ll look at in lecture, and the lecture exercises, is available at the beginning of lecture in a public Git repository. Here’s how to obtain it the first time:

     git clone git://github.com/cs61/cs61-exercises.git

This will put the lecture code in a directory called cs61-exercises.

To update exercise code for a new lecture, change into that directory and run git pull