Infrastructure

This course assumes access to an x86-64-based Linux machine. All problem sets and lecture code can run on a Linux host. Most problem sets and lecture code can also run directly on a Mac OS X host or on Windows Subsystem for Linux. However, for problem sets, we recommend you at least check your work on Ubuntu or another Linux host; your work should not accidentally rely on Mac-specific or Windows-specific behavior.

If you don’t already have a Linux machine, there are two main ways to get one: either via Docker or via a virtual machine. Docker support is new this year and may be preferred for many students. We recommend you try Docker first.

Contents of this page:

• Docker installation instructions
• Full virtual machine installation instructions
• Git version control instructions

Docker

The Docker container-based virtualization service lets you run a minimal CS 61 environment, including a virtual Linux host, on a Mac OS X or Windows host, without the overhead of a full virtual machine solution like VMware Workstation, VMware Fusion, or VirtualBox.

It should be possible to do all CS 61 problem sets on CS 61 Docker.

Advantages of Docker:

• Docker can start and stop virtual machines incredibly quickly.
• Docker-based virtual machines are leaner and take less space on your machine.
• With Docker, you can easily edit your code in your home environment, but compile and run it on a Linux host.

Disadvantages of Docker:

• Docker does not offer a full graphical environment. You will need to run all CS61 programs exclusively in the terminal.
• Docker technology is less user-friendly than virtual machines. You’ll have to type weird commands.
• You won’t get the fun, different feeling of a full Linux desktop.

Preparing CS 61 Docker

To prepare to build your Docker environment:

1. Download and install Docker.

2. Clone a copy of the cs61-lectures repository.

3. Change into the cs61-lectures/docker directory.

To build your Docker environment, run this command. It will take a couple minutes. You’ll want to re-run this command every time the Docker image changes, but later runs should be much faster since they’ll take advantage of your previous work.

$ docker build -t cs61:latest -f Dockerfile .

Running CS 61 Docker by script

Our handout repositories, including cs61-lectures and cs61-psets, contain a cs61-run-docker script that provides good arguments and boots Docker into a view of the current directory. We will update this script throughout the term.

For example:

$ cd ~/cs61-lectures/datarep1
$ echo Hello, Mac OS X
Hello, Mac OS X
$ ls
GNUmakefile     NOTES.md        README.md       add             add.cc          addf.cc
$ ../cs61-run-docker
cs61-user@a47f05ea5085:~/cs61-lectures/datarep1$ echo Hello, Linux
Hello, Linux
cs61-user@a47f05ea5085:~/cs61-lectures/datarep1$ ls
add  add.cc  addf.cc  GNUmakefile  NOTES.md  README.md
cs61-user@a47f05ea5085:~/cs61-lectures/datarep1$ exit
exit
$ 

The script plonks you into a virtual machine! A prompt like cs61-user@a47f05ea5085:~$ means that your terminal is connected to the VM. You can execute any commands you want. To escape from the VM, type Control-D or run the exit command.

The script assumes your Docker container is named cs61:latest, as it was above.

Running CS 61 Docker by hand

If you don’t want to use the script, use a command like the following.

$ docker run -it --rm -v ~/cs61-lectures:/home/cs61-user/cs61-lectures cs61:latest

Explanation:

• docker run tells Docker to start a new virtual machine.
• -it says Docker should run interactively (-i) using a terminal (-t).
• --rm says Docker should remove the virtual machine when it is done.
• -v LOCALDIR:LINUXDUR says Docker should share a directory between your host and the Docker virtual machine. Here, I’ve asked for the host’s ~/cs61-lectures directory to be mapped inside the virtual machine onto the /home/cs61-user/cs61-lectures directory, which is the virtual machine user’s ~/cs61-lectures directory.
• cs61:latest names the Docker image to run (namely, the one you built).

Here’s an example session:

$ docker run -it --rm -v ~/cs61-lectures:/home/cs61-user/cs61-lectures cs61:latest
cs61-user@a15e6c4c8dbe:~$ ls
cs61-lectures
cs61-user@a15e6c4c8dbe:~$ echo "Hello, world"
Hello, world
cs61-user@a15e6c4c8dbe:~$ cs61-docker-version
1
cs61-user@a15e6c4c8dbe:~$ exit
exit
$ 

Full virtual machine

If you don’t like Docker, or you’d like to try running a full Linux virtual machine, please follow these instructions. At a high level, you will:

1. Choose and install virtual machine monitor software (e.g., VMware or VirtualBox).
2. Download a base Linux distribution (e.g., Ubuntu 20.04.1 LTS).
3. Create a virtual machine from that base Linux distribution.
4. Boot that virtual machine and install software needed for CS 61.

Install a virtual machine monitor

A virtual machine monitor, or VMM, is a piece of software that allows you to run another operating system “virtually,” inside your base operating system. For example, you can run Linux inside Windows.

We have had good experiences with a commercial VMM called VMware. VMware’s Mac OS X product is called VMware Fusion, and its Windows product is called VMware Workstation. These products are not free, but you can get an academic license to use one for the duration of the class. You can also use a freely-available VMM, such as Oracle’s VirtualBox.

To obtain VMware:

1. Fill out this Google form with your name, e-mail, HUID, etc, requesting the latest version of VMware for your computer platform (VMware Fusion for Mac OS X, VMware Workstation for Windows, or (rarely) VMware Workstation for Linux). You will receive an account at the VMware Software Center once your request is approved. This step is manual and it may take up to one business day for you to receive a response.

   Your account at the VMware Software Center will have user name and initial email address both set to your Harvard email address.

2. The VMware Software Center is set up like a store. On the “store front” page, select the latest version of the VMware product you need for your platform (Fusion or Workstation for Windows). If you see both a free and a non-free offering of the product, choose the free one.

3. 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.

4. 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 or Product Key. You will need that information to run VMware.

5. If you’re installing Fusion:

   1. Click on the file you downloaded to mount the VMware Fusion icon on your desktop.

   2. 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. When prompted for a license key, use the serial number generated for you by the VMware Software Center.

   If you’re installing Workstation for Windows:

   1. 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.
   2. A window entitled Welcome to the VMware Workstation Pro Setup Wizard should appear. Click Next.
   3. When prompted with a license agreement, select I accept the terms in the license agreement, then click Next.
   4. 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.
   5. On the next screen, User Experience Settings uncheck the Help improve VMware Workstation Pro box and click Next.
   6. When prompted about Shortcuts, leave both boxes checked and click Next.
   7. 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.
   8. 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.

Download a base Linux distribution

We recommend the latest Ubuntu LTS release or later, such as Ubuntu 20.04.1 LTS (Focal Fossa) or even the latest beta release of Ubuntu 20.10. You can download Ubuntu here. Note that Ubuntu is free and you don't need to make a donation. This is a large download.

Create a virtual machine

1. Launch your VMware product.

2. Create a new virtual machine (for instance, with File > New or File > New > Virtual machine).

3. Select “Install from disc or image” and use the Ubuntu .iso file you downloaded.

4. Use Easy Install to set a display name, account name (username), and password like you would on any computer. Don’t forget your password!

5. You may want to Customize Settings to choose the location of your virtual machine and to allocate it enough memory. You want at least 2 GiB (2048 MiB) of memory and 2 processor cores.

   Windows note: Do not store your virtual machine in your OneDrive! Students have experienced serious problems with virtual machines that were stored in OneDrive.

6. Power on the virtual machine and go!

Install CS 61 software

We will be using the GNU C++ compiler (g++) for our C++ projects. The C++ compiler is not installed by default. Here is how to install it in your VM:

sudo apt update
sudo apt install g++

This will install the GNU C++ compiler, g++, to the system. Once done, verify that you've got the compiler correctly installed by running

g++ --version

You will see output indicating the correct version of the C++ compiler is now installed. We are hoping your compiler will be version 9 or above.

Then run the following command to install tools we will be using throughout the course:

sudo apt update
sudo apt install git kcachegrind linux-tools-generic qemu

When prompted, type y and hit Enter to approve the tool installations, and then you're ready to hack!

Git version control

We will be using git with GitHub Classroom for turning in problem set submissions and version control. 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:

• Our git notes, which include an explanation of version control in general
• SEAS’s git introduction
• Resources for more links

Teaching GitHub about your identity

The easiest way to access GitHub repositories is using an SSH key, a secret key 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.

1. In a terminal window, 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.

2. Run cat .ssh/id_rsa.pub to display your public key.

3. Copy your public key (that is, select the text on the screen, and copy it to the clipboard).

4. 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.

You’ll want to copy this identity to every computer on which you’re planning to work. For example, if you’ve installed a full virtual machine, you should copy the ~/.ssh/id_rsa_h and ~/.ssh/id_rsa_h.pub files from your host into the ~/.ssh directory on your virtual machine. It’s important to get the permissions right; these commands should do it:

mkdir ~/.ssh
... copy your id_rsa_h and id_rsa_h.pub files into ~/.ssh ...
chmod -R go-rwx ~/.ssh
chmod go+r ~/.ssh/id_rsa_h.pub

Cloning lecture code

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

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

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

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

Cloning the problem sets

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

Please click this link to create your own private clone of the problem sets repository. (The link will ask you to choose a name for your team; choose whatever you like.) You’ll clone that private 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. Provide a team name.
4. The link should automagically clone the repository. For instance, if your team name was kohler-dumb, you should get a repository called cs61/cs61-f20-psets-kohler-dumb.
5. Use the “Clone or download” button to clone your repository.

You can give other students access to your repository with Settings > Collaborators & teams. The collaboration policy allows students to share some code and even to commit to one another’s repositories. However, remember that every student is expected to submit separate code. GitHub access makes code sharing easier, but it also makes cheating easier. So make sure you and your collaborators have read the course collaboration policy and that you’re granting repository access only to people you trust.

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-f20-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.

Problem set updates

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

• Launch your VM and open a terminal.
• Navigate to your cs61-f20-psets-yourname directory.
• Execute git pull git://github.com/cs61/cs61-f20-psets.git main

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-f20-psets.git

Now you can:

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

Problem set submission

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

$ git status
On branch main
Your branch is up-to-date with 'origin/main'.
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.