VM Installation Guide¶

This guide provides instructions on how to install the CS Virtual Machine (VM) that you will need to do the assignments in this course. Please make sure you have at least 25GB of free space on your laptop before you follow these instructions.

Note

This guide assumes that you have been provided a USB “thumb drive” with the necessary files to install the virtual machine. If you do not have access to such a thumb drive, you can download the VirtualBox installation files here, and the VM image file here. These files are very big and will take a long time to download. If possible, please try to get a thumb drive (the instructors and the TAs all have a few to lend out)

Installing the VM¶

Please follow the instructions for your operating system (OS X or Windows)

OS X¶

Plug in the flash drive, open a finder window and look for the device labeled CS 2019. Click on the name of the device and then open (by double-clicking) the VirtualBox folder and then open the OSX folder.
Open the file named VirtualBox-6.0.12-133076-OSX.dmg. This action will open a new window.
Double click on the icon that looks an open shipping box. It looks like the screenshot here.
Press Continue when presented with a security message.
Press Continue again on the introductory screen.
Press the Install button to accept the standard installation.

Note

If you see a “System extension blocked” message, click on “Open System Preferences” and then on “Allow” in the bottom half of the screen. Once you do this, go back to Step 3.
Enter the password for your account on your computer.
Press Close once the installation completes.
In your web browser, go to https://mit.cs.uchicago.edu/ and log in with your CNet ID and password.
Open a finder window for the device the labeled CS 2019. Click on the name of the device and then open the file named uchicago-cs-vm_201920.2.ova. This step will open a VirtualBox window and a prompt. Within this prompt, click Import (you do not need to modify any of the settings). This process may take as much as 5-10 minutes.

Note

If you are prompted to allow VirtualBox access to accessibility controls, select “Deny” unless you expect to need to use the microphone in the VM for accessibility purposes.
You have finished installing the VM. Now, you will start the VM and complete some setup steps inside the VM. Proceed to the “Setting up the VM” section.
If you downloaded the VM image (instead of using the one on the flash drive), you can now delete that file from your hard drive. If you are using the flash drive, DO NOT delete any files there!

Windows¶

Plug in the flash drive. Find the device called “CS 2019” in Explorer, by clicking on “Computer” or “File Explorer” in the Start Menu, or by pressing “Windows+E” on your keyboard.
In the flash drive, open the VirtualBox folder and then open the Windows folder. Now right-click (do NOT double-click) on file VirtualBox-6.0.12-133076-Win.exe file and select “Run as Administrator”. If you do not see the “Run as Administrator” option because you are on an older version of Windows, you may resort to double-clicking the executable. Note that if you are not on an administrator account on your machine, your VirtualBox installation may fail.
If you are presented with a UAC prompt (aka: the screen goes dark and you are asked “are you sure you want to run X?”), select Yes and accept the prompt. Do not select No/Cancel/Reject.
You will now be presented with the installer window. Press Next. On the next screen, accept the defaults by pressing Next again. You can customize these settings if you feel you need to, but we do not offer troubleshooting help should you fail to install your VM correctly due to tinkering. Keep pressing Next until you cannot press Next anymore. The installation will begin at this point and may take several minutes to complete.
You may be asked to accept the installation of a new network adapter/interface or setting up a new network connection. In case of the former, you should accept the new network adapter/interface by pressing Yes/Accept/Okay. In case of the latter and a new window pops up, you should indicate that it is a public connection and click Okay/Close.
When the installation is complete, you will be presented with a shiny new VirtualBox window. Minimize/close this window.
In your web browser, go to https://mit.cs.uchicago.edu/ and log in with your CNet ID and password.
Go back to the flash drive that you opened in Step 1.
Once you are presented with the drive’s contents, double-click to open the file named uchicago-cs-vm_201920.2.ova.
Give it a few moments. You will eventually be presented with your VirtualBox window and a prompt. Within this prompt, click Import (you do not need to modify any of the settings). This process may take as much as 5-10 minutes.
You have finished installing the VM. Now, you will start the VM and complete some setup steps inside the VM. Proceed to the “Setting up the VM” section.
If you downloaded the VM image (instead of using the one on the flash drive), you can now delete that file from your hard drive. If you are using the flash drive, DO NOT delete any files there!

Setting up the VM¶

From VirtualBox, select the “UChicago CS VM” and click Start. A window will open where a Linux environment will boot up. This may take 1-2 minutes.

Note

If you get an error saying “VT-x is not available. (VERR_VMX_NO_VMX)” (or any error referring to “VT-x” or “Virtualization extensions”), this means your laptop needs to be configured to support VMs. This is an advanced operation, and better performed by the course staff. Please speak to a TA or come to office hours so we can help you complete your setup.
Eventually, an Ubuntu login prompt will appear. The “CS Student” account should be pre-selected (if not, select it). The password is uccs.
An empty desktop should appear, with a dock on the left. At the top, you may see one or more messages with Xs to dismiss them on the right. Dismiss these so that you can see “Ubuntu Desktop” at the top left of the display-within-a-window.
Sometimes, you may see “Software Updater” window appear (this may appear on the dock as an icon with a large “A” in a circle with two arrows. Always dismiss this; do not update any software on the virtual machine unless told to do so by an instructor.
Click on the terminal icon, which is third from the top in the dock and looks like a screen. You now have a Linux command line window open.
You can switch back and forth between programs running on your computer, and programs running within the VirtualBox window. But, you should do all your work (such as writing code) within the VirtualBox environment so that the files are in the right place. You can do other course-related tasks using your standard applications (e.g. using a web browser to visit Piazza).

You can copy text from your browser in the usual way (Command-c in OS X, Ctrl-C in Windows) and then paste it in the terminal window in the VM using Shift-Control-v. Make sure you have selected the terminal window on the VM (just click on it) before you do the paste.
Run the following command in the terminal window.
```
update-cs-software
```
You will be asked for the password for the student account when you run this command. The password is uccs. Note that you will not see any characters echoed back as you type the password. The output may be several lines that just say “Requirement already satisfied”. This is normal.
You are now ready to set up your Git repository. Git is a software version constrol system that we will be using for labs and programming assignments. Run the following commands:
```
cd
cs-setup-script cmsc12100-aut-19
```
You will be asked for your username, which is just your CNetID, and your password, which is just your CNet password. You will then be asked which repository you wish to set up, choose option 1. If the command is successful, you will see text of the form:
```
Setting up your Git repository...
Your git repository has been created in /home/student/cmsc12100-aut-19-username

Setting up chisubmit...
chisubmit has been set up. You can use chisubmit commands inside /home/student/cmsc12100-aut-19-username
```
where username has been replaced by your CNetID.
If you want to suspend your VirtualBox, click the red close button in the top left of the window. We recommend choosing “Save the machine state”. That way, you can always pick up where you left off.

Note

Never select “Power off the machine” when closing your VM, because this option is the equivalent of yanking the power cord on a running desktop machine. This option can result in hard drive corruption and many other problems.

When closing your VM, make sure that you always select either “Save the machine state” (this is the best option, as it will allow you to resume the VM in the exact same state you left it) or “Send the shutdown signal” (which will perform an orderly shutdown of the machine).

If you need to shut down the machine where your VM is running, make sure you close your VM before shutting down your machine. Shutting down your machine while the VM is running can have the same effect as selecting the “Power off the machine” option when closing the VM.
When you want to resume a session, relaunch the VirtualBox application, select the VM, and click on “Start”. Do not repeat any of the steps in this guide
If you back up your computer, you may want to exclude the large files maintained by VirtualBox from your backups. In particular, when you use your VirtualBox, the state of the machine is saved to your disk, and a large (multi-GB) file is changed each time. This can result in very large backups with each backup saving another copy of this large file due to the changes. Make sure to exclude the “VirtualBox VMs” directory if you wish to avoid this problem.