Compilers

OCaml VM Setup

This semester, you will develop a compiler which translates human-readable source code into machine code which will be executed by your operating system. This process is quite system-specific: although we will learn principles which apply generally to the process of compilation, you only have time to make your compiler work under specific circumstances. For this reason, your compiler will target 64-bit POSIX-compliant systems similar to the Linux computers we use in the Swarthmore computer labs.

While we could use the CS network computers, the tools we are using are not necessarily designed to work over a network connection and, even if they do, the experience of that type of remote development is often choppy and fraught. To avoid this work, you are encouraged to download and use a virtual machine provided specifically for this course named Lugus (after a Celtic god of arts, trade, and travel). This virtual machine contains all of the software you need for CS75 and is preconfigured for ease of use.

This page documents how to set up the virtual machine for use.

VirtualBox

To run a virtual machine, you need a virtual machine manager (VMM) application. VMM software simulates the behavior of a computer’s hardware: it simulates disks, processor interrupts, and so on. In the same way that we can use a linked list anywhere a list is expected, we can use a virtual hardware anywhere an operating system expects hardware. The operating system in question need not be aware that the computer it’s running on is simulated and programs running within that operating system are likely just as oblivious. This will allow you to run Linux applications on your computer without running Linux directly on your hardware.

For this course, you are recommended to download and install VirtualBox, a free, open source VMM for which Lugus was designed. (It is possible to run Lugus using other VMMs, but we will not detail the process here.) The computer running the VMM software is called the “host” while the virtual machine is called the “guest”. So if your actual computer is running Windows, you should download the VirtualBox Windows host software (even though Lugus is a Linux guest). The installation of VirtualBox is likely typical to other programs you have installed in the past; default settings should be fine.

Downloading Lugus

VirtualBox is essentially just friendly a hardware simulator. In order to run anything with it, we must create a virtual machine configuration, describe what hardware to simulate, and then use the virtual machine to install an operating system and/or other software. While this is not too complex, it’s time consuming. Lugus is a preconfigured virtual machine with an installed operating system and appropriate software installed.

This virtual machine is represented by two files you will store on your computer: a file describing the virtual machine itself (how much memory it should have, what kind of devices are attached, etc.) and another file with the contents of the machine’s simulated hard drive. The drive file is very large: it contains the virtual machine’s operating system and all of the software that has been installed on it and consumes about eight gigabytes when uncompressed. If you will not have the ability to store such a file throughout the semester, please reach out to your instructor for guidance.

Fortunately, the drive file compresses quite well, so you will only need to download a ZIP file containing two gigabytes of data. You can obtain this file from one of two places: either the Swarthmore CS web server or Google Drive. Google Drive is faster but is notoriously incapable of resuming broken downloads (because the URLs from which it delivers files are temporary). So:

• If you are off campus and have a reliable connection and expect to be able to download the file in one sitting, you can obtain Lugus.zip from Google Drive. If your download is interrupted, you’ll likely have to start again (although the Internet has a few posts on how to work around this problem).
• If you are off campus and are concerned that your download may be interrupted, you should download Lugus.zip from the CS web server. If your download is interrupted, you should be able to resume it from within the download manager of your web browser.
• If you are on campus, the CS web server is likely the fastest option (since it’s literally a few hundred meters away from you).

Once you have obtained Lugus.zip, you should extract it to a location where you intend to keep it while you work on your lab assignments. Once you have extracted the files Lugus.vbox and Lugus.vdi from this file into a separate location, you can delete Lugus.zip.

If you have any trouble obtaining these files or working with them, please make sure to ask for help!

Configuring Lugus

Once you have the virtual machine files, you can add the VM to VirtualBox. The initial VirtualBox window contains a vertical tab bar on the left with an entry “Tools” selected by default. Since you have downloaded an existing virtual machine, press the Add button to add the files you already have to VirtualBox. A file chooser dialog will pop up. Select the Lugus.vbox file that you unpacked from Lugus.zip.

Adding a virtual machine in VirtualBox

Once you have added this file, the virtual machine will be recognized by VirtualBox. The vertical tab pane will now have an entry for Lugus. When Lugus is selected, the Settings and Start buttons will appear in the right pane (along with a general description of the virtual machine). Settings allows you to change the hardware associated with the virtual machine, such as giving it more RAM. (Note that the virtual machine’s RAM is simulated by using the host computer’s RAM, so that memory is tied up while the VM is running.)

Starting Lugus in VirtualBox

Press the Start button to boot Lugus. This will open a new window that shows the display of the guest computer. It will move through a standard Linux boot sequence, eventually showing you a login prompt. As you use the virtual machine, it will occasionally display notifications at the top of the screen to help you use VirtualBox. Those notifications are worth reading over. Most notably: VirtualBox uses a “host key” (by default: the right control button on PCs and the left command key on Macs) to signify that you want to talk to VirtualBox even when the guest OS window has keyboard focus. Take note: if your mouse is ever “stuck” in the guest VM, press the host key to get out.

The Lugus login screen

The username you use for the virtual machine is “cs75”; the password is the same. By default, Lugus does not run any remote login services like SSH so you don’t need to change this password, but you’re welcome to do so if you prefer. The root password on this machine is the same, so you can install any software you like.

This virtual machine uses Debian Linux, which is similar to the Ubuntu Linux used on the CS network computers. It is not, however, linked to your CS network home directory, so none of the configuration or customizations you have there will apply here. Most importantly, this means we must authorize the VM to interact with your Swarthmore GitHub account so you can clone and push to your assignment repositories. This is similar to a process you have likely gone through in the past: create an SSH key and paste it into the right place on Swarthmore’s GitHub site. Dr. Tia Newhall’s Swarthmore GitHub Setup page might be familiar as it is often referenced when setting up GitHub on your CS network account.

Running Lugus’s GitHub Setup Script

To simplify this process, you can run a script provided with the virtual machine. Type bin/github-setup.sh into a terminal. If you are asked to overwrite a key, say “yes”. You will be asked to set a passphrase for this key; whether you leave it blank is up to you and your level of comfort. The script will then do two things: print the contents of your SSH public key for you and open a web browser to the appropriate page on the Swarthmore GitHub Enterprise site.

Copying the SSH public key

Follow the instructions from the terminal window: begin by copying the SSH key from your terminal window. Then, go to the web browser and paste your SSH key into the “Key” field in the web form. You should give your key a title describing how it’s used (e.g. “Lugus”) so you’ll know in the future whether you want to delete it or not. After you’ve finished, press the “Add SSH Key” button at the bottom of the form to grant access to the corresponding private SSH key on Lugus.

Adding the SSH key to GitHub

That’s it! You should now be able to follow instructions from the lab write-ups, cloning your repositories just as you would from the CS network. Remember: while things you push are stored on Swarthmore’s GitHub Enterprise, anything you haven’t pushed (or which isn’t in a Git repository) is stored on the virtual machine. The virtual machine is a figment of our imagination: its data is actually stored in the Lugus.vdi file on your host computer’s hard drive. You could e.g. move that file to another computer, but make sure you don’t delete it if the virtual machine still contains information you care about!