ICS 46 Spring 2018
Project #0: Getting to Know the ICS 46 VM

Due date and time: Wednesday, April 11, 11:59pm


The goal of this project is to allow you to work through downloading and setting up the ICS 46 VM, which is the development environment we'll be using to do our work in this course, then using it to practice some C++ skills that solidify things you will mostly already have learned in prerequisite coursework. If you took ICS 45C with me previously, you may recognize a lot of what follows, but some of it will be different than you've seen before, so be sure to run through the whole project so you don't miss any important details; if, instead, you've taken ICS 45C with someone else, this might be wildly different than what you're used to, but think of that as an opportunity to learn something new (which is the spirit in which I'm offering it).

Having worked through this project, you'll have set up the ICS 46 VM to run on your own computer, experimented with it a little bit, understood how your files will be organized when working on ICS 46 projects, ensured that you know how to "gather" files for submission (the same way you'll do in later projects), and taken some important steps toward being productive on subsequent projects and beyond.

Don't lose sight of the fact that there is a deliverable here: You'll need to write us a C++ program that meets a set of stated requirements and submit it. Having done that, you'll be sure to be ready to do the same on subsequent projects. For your trouble, we're offering 2% of your overall course grade if you're able to do this successfully, but we won't be offering that credit to anyone who doesn't follow these directions and submit exactly what we're looking for, as described below. You may prefer other ways to work — a different operating system, different development tools — but be aware that this course, like many workplaces and other circumstances where you're working within an existing framework, is not offering you that choice.


Traditionally, a computer is a collection of hardware — processor, memory, secondary storage, video and network adapters, and so on — on which a single operating system runs at a time. You "boot" the computer into your chosen operating system, whose role is to arbitrate access to that hardware, so that applications running on top of your operating system can effectively use and share that hardware. At any given time, a single physical computer traditionally runs one operating system at a time: Windows, Mac OS X, some flavor of Linux, or whatever. It wasn't that long ago that the only fancy trick to work around this was to install more that one operating system (e.g., one on each of a few hard drives; or even multiple ones on the same drive, which sometimes required some fancy footwork), then select one of them at boot time.

Despite all of the pretty user interfaces, the fundamental role of an operating system is arbitrating access to hardware on behalf of the applications it runs. If an application wants to establish a connection over the Internet, it asks the operating system for access to the network interface; the operating system manages data moving into and out of the network interface, and makes sure that it is directed to the right application when it arrives. If it wants to display something on the screen, it negotiates with the operating system for the right to draw and have it be visible. This allows many applications to run on a single operating system, while preventing them from stepping on each other's toes.

More recently, virtualization has dramatically altered the way that an operating system interacts with its underlying hardware. Operating systems are ultimately just programs; they're software. So it makes a certain amount of sense that operating systems could run like applications do. Instead of running them directly on the hardware, virtualization allows us to run them on top of another "bridge" application within another operating system; that bridge is sometimes called a hypervisor or virtualizer. In this scenario, we call the "main" operating system (the one running directly on the hardware) the host and the other operating system the guest. Every time a program on the guest operating system needs access to hardware, it asks the hypervisor to negotiate with the host operating system for that access; the host operating system can grant it the way it grants hardware access to any other application. If the guest operating system needs to receive something from the Internet, that request is arbitrated by the host operating system; when the host operating system receives data, it is passed to the hypervisor, who then passes it along to the guest operating system, who then passes it to whatever application on the guest operating system needed it. The guest operating system operates, more or less, under the illusion that it's running directly on hardware, thanks to the hypervisor.

This is a complex trick, but a very important one. A single computer — not just beefy, expensive servers in data centers, but relatively inexpensive personal computers like laptops, which are nowadays equipped with hardware support to make this happen more efficiently — is capable of simultaneously running a host operating system and one or more guest operating systems, limited only by the available amount of memory, processing power, network bandwidth, etc. Since they must pass through the hypervisor to access hardware, the guest operating systems generally run slower than the host does; you won't necessarily find yourself playing heavy-duty 3D video games or watching high-definition video in a guest operating system. But virtualization is a wonderful way to experiment with an operating system without fully committing yourself to it, to set up separate software installations for different tasks, to isolate different operating systems and different setups from one another, and to migrate software setups from one computer to another with relative ease.

In this course, virtualization is important because you'll run the ICS 46 VM development environment as a guest operating system in whatever host operating system you prefer, with a hypervisor used to arbitrate between the host and the guest.

Installing Oracle VM VirtualBox

Before downloading and installing the ICS 46 VM, there's an important prerequisite you'll need first: the hypervisor! For this purpose, you'll want to download and install a program called Oracle VM VirtualBox, which you can obtain at www.virtualbox.org. VirtualBox is available for Windows, Mac OS X, and various flavors of Unix and Linux, so you should be able to install and run it regardless of which operating system you prefer. (You'll also find that VirtualBox is already installed on the machines in the ICS labs, so you won't need to download or install it to proceed there.)

The latest version of VirtualBox, as of this writing, is 5.2.8. This is the only version that I've tested the ICS 46 VM against. If you already have a different version of VirtualBox (or you prefer a different hypervisor, such as VMware), you may find that these instructions don't match what you see, and you may even find that the ICS 46 VM does not work correctly; I suggest an upgrade. Unless you have a good reason to use something else, I would suggest installing and using VirtualBox 5.2.8.

What is the ICS 46 VM?

The ICS 46 VM is a complete installation of an operating system and the necessary software that we'll be using in this course (and little else). The operating system is Ubuntu Server 16.04 (64-bit). It's being provided with a graphical user interface called XFCE, which provides a look-and-feel similar to what you might get on Windows or Mac OS X; the GUI option will be important for us this quarter, because at least some of the project work will involve GUIs (albeit ones provided, as opposed to ones you'll build). You'll nonetheless spend a lot of your time on an the command line within your VM's GUI.

In addition to the operating system, the ICS 46 VM consists (more or less) of the following software:

Along with this preinstalled software, the ICS 46 VM also includes an environment for the course, which consists of a set of commands and scripts that you can execute to perform common tasks, and templates from which you can start new project work without having to worry about detailed setup of things like makefiles and build scripts. Over the course of the quarter, we'll update the environment, and updating yours is a single command away. (More on that later.)

Downloading the ICS 46 VM

You can download the ICS 46 VM at the following link. Before you do that, please bear three things in mind:

The ICS 46 VM is available here.

The file is in a format called OVA, which is an Open Virtualization Archive, a single file that contains a directory consisting of several files; those files comprise something called an OVF (Open Virtualization Format), which is a standard format for distributing a preconfigured virtual machine, including the contents of its virtual hard disk, various hardware settings, and so on. The OVF can be imported into the native format used by various hypervisors, such as VirtualBox, the hypervisor we'll be using this quarter.

Be patient; the download may take a fair amount of time. (So much the better that you get a copy from someone else who's already downloaded it!) Once you have a complete copy, you can move on to the next step.

Verifying that the download is complete and correct

The most basic thing to do when you believe you've downloaded a file as large as the entire ICS 46 VM is to verify the integrity of the download. If the download didn't finish successfully, or if it was corrupted at all, it will not be possible to import the VM into VirtualBox in the next step.

Importing the ICS 46 VM into VirtualBox

Once you've downloaded the OVA file containing the ICS 46 VM, you'll be ready to import it into VirtualBox. (Did you install VirtualBox already? If not, you'll need to do that before you proceed.) Here's what you'll need to do to import the VM into VirtualBox.

Prerequisites: Preparing to import a 64-bit VM

The ICS 46 VM runs a 64-bit version of Ubuntu Linux, and VirtualBox is only able to run 64-bit VMs when the host machine meets certain prerequisites. In particular, there are three prerequisites that you'll need to be sure your host machine meets:

If you're not sure whether you have virtualization support turned on, one way forward is to proceed under the assumption that you do; most Windows machines (laptops and desktops) and essentially all Macs will meet these requirements by default. Later in this document, I'll explain how to recognize that you've got a problem and what to do to fix it.

Launching VirtualBox

First, launch the VirtualBox application that you installed previously. This will bring up a window titled Oracle VM VirtualBox Manager, which lists the VMs that you've installed, allowing you to do things like start them, stop them, create new VMs, etc.

Configuring VirtualBox's network settings

In order for your host operating system to communicate with your new VM, you may need to configure VirtualBox's network settings. In our experience, this is usually configured automatically when running VirtualBox on Windows, but often needs to be configured manually when running VirtualBox on Mac OS X. Before proceeding, you'll need to ensure that things are set up correctly and, if not, you'll need to set them up.

In particular, what you'll need to configure is something called a host-only network adapter. This is what allows your host operating system to connect to your VM, as though your VM was a separate machine running on a network.

Importing the OVF into VirtualBox

The next step is importing the OVF — the OVA file you downloaded previously — into VirtualBox, which will create your new VM.

Note that you may need as much as 16 gigabytes of free hard disk space in order to complete this process successfully. Be sure you have that available now before proceeding.

Hooking up the host-only network adapter

The next step is to verify that your VM is connected to VirtualBox's host-only network adapter correctly. Here's what you do:

Ensuring you have 64-bit VM support

Now is a good time to verify that your machine will be able to run a 64-bit VM in VirtualBox. Select the ics46-2018spring VM in Oracle VM VirtualBox Manager window by clicking on it once. This will display a bunch of information about its settings, arranged into sections. In the General section, a setting called Operating System is listed; its value should read Ubuntu (64-bit). If it does; you're probably in good shape. If it reads Ubuntu (32-bit) instead, you'll need to enable virtualization support in your BIOS settings before you can run the ICS 46 VM.

How you enable virtualization support is different depending on what machine you're running, so I can't give you specific instructions on how to do it, but the setting you're looking for is probably called Virtualization, VT-x, or AMD-v, and you'd want to make sure any setting like that is listed as Enabled or On.

After enabling that support, there are a couple of additional things you'll have to do:

A word about where the VM files are stored

Note that VirtualBox prefers to store the VM files in a particular directory (e.g., on Windows, VMs are stored by default in C:\Users\your_user_name\VirtualBox VMs). If you'd rather store the files somewhere else, you have two choices:

Using the ICS 46 VM in the ICS labs

If you want to use the ICS 46 VM in the ICS labs, you should use the procedure described in the previous section to move the files to a removable storage device (e.g., a USB stick). Files stored on the ICS lab machines are deleted automatically when you log out, but you won't want to download and reinstall the VM every time you enter the lab, particularly because any files you will have stored on the VM the last time you used it will have been lost.

Note that you'll need a fair amount of available space on your USB stick; you'll probably need 16GB, to be safe. (When I imported a fresh copy of the ICS 46 VM, without having done anything with it yet, it took up just short of 10GB.)

Starting the ICS 46 VM and logging into it for the first time

Once you've imported the ICS 46 VM into VirtualBox, you're ready to start it up and log into it for the first time. In the Oracle VM VirtualBox Manager, select the ics46-2018spring VM and click the Start button. You'll see another window pop up, which is the console of your VM. Eventually, you should see a GUI login screen appear in place of that console. This is a lot like booting up a separate computer, so you can expect that it'll take a little bit of time.

Logging into the VM

Once the ICS 46 VM has started up, you'll see a dialog box asking you to specify a username and a password. The username is selected from a dropdown list; ics46 will probably already be selected, but make sure it's selected if it's not already. In the text field below that, type the password ics46 — which you'll want to change (see below) — and click the Log In button.

Having logged in, you should eventually see a desktop, much like you would see on Windows or Mac OS X. In the top-left corner is a small icon that can be used to start common applications or edit operating system settings. One of the most important of these, for us, is the Terminal application, which will give you a shell prompt that you can use to issue commands. Find the Terminal application and start it. (An alternative, at least if you use Windows as your host operating system, is to simply hold down the Windows key and press T. I presume a similar shortcut works on Mac OS X hosts.) A window should pop up and contain a prompt that looks like this:

ics46@ics46-2018spring : ~ $

One minor thing to note: By default, the font size in the Terminal window is quite small, but that's something you can change, if you'd like. At the top of the Terminal window, select Edit and then Preferences.... On the ensuing dialog, select the Appearance tab, and there will be a way to change the font. For what it's worth, I like a font called Liberation Mono at an 11-point size; if your eyes are better than mine, you might like the same one, but a little bit smaller. (I loved 8-point fonts in my youth; those days are long gone now.) You can also set the default geometry of the window, so that it's a larger size by default. For that, I like 100 columns and 40 rows, but my laptop screen is pretty big; your experience may vary. Once you've changed the settings, click Close on the dialog, then close the Terminal window and bring up a new one, and you should see things in your new configuration.

The shell prompt

As you do your work within the ICS 46 VM, you will spend a lot of your time interacting with a shell prompt. It's important, first, to understand what the shell prompt itself is telling you.

The first part, ics46@ics46-2018spring, identifies the username (ics46) and the name of the VM (ics46-2018spring). The colon is meant to separate this from the next part, which lists the current working directory (i.e., the directory on the virtual hard drive where we currently reside); initially, that directory is the special directory ~, which is our home directory (a shorthand for our actual home directory location, /home/ics46).

At this point, you're logged into your VM and ready to issue it some commands.

Changing your password

Before you get too much farther, it's a good idea to change your password, so that other students can't log into your VM if you don't want them to. Changing your password is simple:

Taking a look around using the shell prompt

A Linux shell prompt can be intimidating if you've spent most of your time using an operating system with a graphical user interface. However, familiarizing yourself with a shell prompt — on any operating system, not just Linux — is a worthwhile skill, because many more advanced tasks are either difficult or even impossible from a typical operating system's graphical user interface; the graphical interface will usually streamline common tasks, but when it comes time to do something more involved, a shell prompt is wonderfully useful.

At the shell prompt while within your home directory, type the command ls and press Enter. ls is a way to list the files residing in the current working directory. You should see something like this:

Desktop/     Downloads/    Music/     Pictures/  Templates/
Documents/   environment/  packages/  Public/    Videos/

You can tell that environment (and many other things here, which are part of the GUI shell) is itself a directory (subdirectories of your home directory) because of the slashes that come after their names. This means we can change into them and see what's inside of them. Issue the command cd environment. Notice what happens to your shell prompt:

ics46@ics46-2018spring : ~/environment $ 

It's now telling you that your current working directory is the environment directory inside of your home directory. Let's take a look at what's inside the environment. Type the command ls again.

scripts/  templates/  updates/

The scripts directory contains a small set of scripts used to automate certain tasks for the course. The templates directory contains a set of templates used to create new C++ project directories to do your work in. The updates directory (presently empty) may eventually contain tools and scripts used to update the ICS 46 VM, if we discover a widespread problem for which lots of you will need a fix.

(You won't actually want to modify the contents of the environment directory or any of its subdirectories, as it contains scripts and tools that are intended to work the same way for everyone in the course. But you can feel free to look at what's there, if you're curious.)

Let's leave the environment directory and head back to our home directory. When you want to move to the directory that contains the current directory (usually called the parent directory), you issue the command cd ... (No matter where you are, .. (two dots) always means "The parent directory of the directory I'm in now," while . (a single dot) always means "The directory I'm in now.") Try that now, and then type ls to see if you ended up where you thought you would.

If you ever want to get back to your home directory, that's as simple as typing cd by itself, with no parameter.

How the ICS 46 VM has been set up

As you proceed with your work this quarter, your ICS 46 VM's home directory will contain (at least) three directories that matter:

Additionally, you'll see several other directories, which were created when the GUI shell was installed, but they aren't our focus here.

The ics46 command

From the shell prompt, you can use the command ics46 to perform certain common course-specific functions. If you're curious what functions are available, type ics46 at a shell prompt and press Enter; you'll see a description of how to use the ics46 command.

Creating a new project and writing a short C++ program

Creating a new project from an existing template is simple; you use the ics46 command to do it. Let's create our first project:

Restoring or refreshing your ICS 46 environment

Periodically throughout the quarter, it will be necessary to refresh your ICS 46 environment, so that it contains the files necessary for you to proceed with your work. There are three relevant commands you can use for this purpose:

In general, I'll specify when the environment has changed, and let you know what version you need to proceed with a task, so there's no need to refresh it unprompted on a regular basis.

Using SSH to connect to your ICS 46 VM

Even though your ICS 46 VM has a GUI-based shell, you might also want to log into its command line shell directly. For that, we need to be able to connect to our VM with something else. The ICS 46 VM has been configured already so that you can connect to it using a protocol called SSH. Depending on your host operating system, you would use slightly different tools for this. (And you might find this useful even though the VM has its own GUI, if you'd prefer not to switch back and forth between the Linux GUI and your host operating system.)

Even if you plan to do most of your work in the Linux GUI, do work through this section and make sure you can connect to your VM using SSH, because you may need this later when it comes time to submit your work.

Network settings

The ICS 46 VM has been configured so that it will appear to your host operating system to have the IP address (Note that this is an internal address, and no other machines will be able to connect to it using that address; this is only used for host-to-guest communication, but that's all we need it for.)

Using PuTTY on Windows

If you run Windows, a good tool to use is PuTTY, which you can download here. (What you want to download from that page is putty.exe. It's not an installer; it's a program you can drop pretty much anywhere, including a USB stick, if you prefer.)

To connect to your VM using PuTTY, you would do the following:

A number of other settings — such as the window size and whether the window closes automatically when you log out — are available. To avoid setting these things up repeatedly, when you have them the way you want them, type a name (e.g., ics46-2018spring) under Saved Sessions and click the Save button; this will allow you to load that session and reuse it later, so you don't have to change these settings every time you connect. (On Windows 7 and above, you'll find that frequently-used sessions are easily accessible from the taskbar if you pin PuTTY to it. Very handy!)

You can run as many instances of PuTTY as you'd like, which can give you as many shell prompts as you need to do your work. Don't limit yourself to only one shell prompt; you'll probably find multiple of them useful (as I do).

Using a Terminal window on Mac OS X or various flavors of Unix

On Mac OS X or various flavors of Unix, your best bet will be to bring up a Terminal window, then issue the command ssh ics46@ This should display the login prompt for your ICS 46 VM and allow you to log into it. You can do that from as many Terminal windows as you'd like, allowing you to have as many shell prompts on your VM as you'll need. Don't limit yourself to only one shell prompt; you'll probably find multiple of them useful (as I do).

Shutting down or rebooting your VM

Why it's important to shut down and/or reboot carefully

Your VM may feel somewhat like any other application running on your computer, such as a word processor or media player, so you may feel safe simply closing the VM's window when you're done with it. It's important to understand that your VM is not just an application; it's more akin to a separate computer, whose video output happens to be displayed in a window on the host. Just as you don't typically shut down your computer by simply powering it off or unplugging it, it's wise to go through a safe shutdown sequence when you want to shutdown your VM.

When you want to shut down your VM, you should do this; it's the best way to be sure that no data is lost and that you avoid problems like virtual hard drive corruption which, while rare, are not impossible when you simply power the VM down without shutting it down first. In previous quarters, some students ended up with irreparably corrupted VMs and had to start over with a new one, and the likeliest cause was unsafe shutdowns leaving the VM in a corrupt state. Best to be careful.

How to shut down or reboot the VM

Near the top-right corner of your VM's GUI, you'll see an icon that looks like a gear. Click that gear with your mouse and you'll see a menu pop up, giving you a few options.

To shut down your VM, select Shut Down from that menu.

To reboot your VM instead, select Log Out, which will pop up a dialog box that will given you a handful of options. Click the Restart button in that dialog to reboot your VM.

Alternatively, you can start the Terminal application and issue the same commands detailed in the next section for shutting down or rebooting the VM that way.

Shutting down or rebooting the VM from the shell prompt

Shutting down the VM from the shell prompt is also simple. From a shell prompt, and issue the following command: sudo shutdown -h now. You may be asked for your password; once you enter it, your VM will be shutdown, the console window will eventually disappear, and any SSH connections will be severed.

Similarly, you can reboot your VM by issuing the command sudo reboot instead. Existing SSH connections will be severed and your VM will be stopped and immediately restarted.

What's sudo?

On Linux, certain user accounts can be given special rights to run commands as a superuser. A superuser is one that can do essentially anything — equivalent to what is called an "administrator" on some other opreating systems. This is not a power to be taken lightly; you really can render your VM completely useless by doing things you shouldn't, like deleting the directories that contain operating system files or installed programs that your VM depends on. But we'll once in a while encounter a situation where we need to execute a command as superuser (e.g., when installing new software, or in the example above of shutting down or rebooting your VM).

When you want to issue a command as the superuser, you prefix the command with the word sudo. Shutting the VM down and rebooting it are fairly harsh operations — remember, this is a server operating system, so the operating system's presumption is that the VM could potentially be in use by many users at once — so they are often available only to superusers.

Not all users on a Linux system are allowed to operate as superusers, though your ics46 user account has been configured so that it can. This is your VM, so you should be able to do what you want with it.

Along the way, we may discover the need to run other commands as superuser — e.g., downloading and installing software — though it's not something you'll likely see often in this course.

A note about outgoing network access

Your ICS 46 VM is capable of accessing the Internet; for example, it includes a web browser (Firefox). However, you may notice that its ability to connect to the Internet is flaky at times, particularly when your host operating system enters and exits sleep mode or hibernation. The solution to this problem is quite simple, once you know how to do it: Restarting the network interface used to connect out to the Internet is all you need to do, which you can do by issuing these commands from a shell prompt.

sudo ifdown enp0s3
sudo ifup enp0s3

This has solved the problem for me every time I've had it; your experience, of course, may vary.

Learning more about Linux

It may seem uncomfortable to be pressed into using an operating system other than the one you're used to. The idea of spending most of your time at a shell prompt, of learning to use a new text editor like vim or emacs, of having to look up how to do simple things like move files from one place to another might seem unpleasant to you. But a university education is a great time to experiment with new things, especially new things with real-world applicability.

The Internet is a wonderful resource for learning about Linux and the shell prompt. Our TAs and lab tutors will be available during our lab meetings to help, as well. In general, we're leaving you to learn a lot of these things on your own, because you'll usually find that the need to know one thing will lead you to find the answers to four or five other questions you didn't realize you had yet. It won't be long before you're plenty productive, and this is knowledge that will serve you well for the rest of your technology career. Embrace this challenge and you will emerge stronger!

The program

As a warm-up — both to make sure that you're familiar with the ICS 46 VM, as well as to be sure you're prepared to use C++ in the way we'll be using it this quarter — this project asks you to write and submit some C++ code, using features of the language that are going to be important to us, but that you might or might not have had a lot of prior experience with.

The goal here is to be sure you're using the ICS 46 VM to do your work, learning what you need to know about one of the available text editors to write your program, and using the provided tools to gather your files for submission. Even if you normally prefer a different working environment, you would be well-served to use the ICS 46 VM for this project, to be sure that you can use it for your work later in the quarter.

Creating your new project directory for your Project #0 work

At a shell prompt in your VM, issue the command ics46 start proj0 project0. This will create a new project in the directory ~/projects/proj0, using the project0 project template (which should already be in your environment). Having done that successfully, change into that directory (cd ~/projects/proj0) and you're ready to get started!

The requirements

Change into your new ~/projects/proj0 directory. Notice that three files are already present in the core directory: String.hpp, String.cpp, and OutOfBoundsException.hpp. Your goal in this project is to implement the String class declared (and described in comments) in String.hpp. There are a few requirements to be aware of:

You'll notice, too, that there is a file called StringTests.cpp in the gtest directory, which provides an example of how each of the member functions should behave. All of these tests should pass (and exhibit no memory-related issues) when your implementation is complete. If Google Test is something new for you, see the Unit Testing notes from my most recent version of ICS 45C. You can feel free to add any additional unit tests you'd like, but resist the temptation to modify the existing ones.

Compiling and running your project

Your String implementation should be written in the file String.cpp in the core directory inside your project directory.

When you're ready to compile it, change into the directory ~/projects/proj0 (if you're not already there) and issue the command ./build. (Note the dot and the slash in front of the word "build" — those are important! — and remember that you can tell that script what to build if you only want to build one thing, like gtest.) If compiling is successful, then issue the command ./run gtest to run the unit tests, ./run app to run your application (if you write one, which is not required), or ./run exp to run your experiments (if you write any, which are also not required).

Also, if you want to check for misuse of memory, you can use the --memcheck option when you use the run script (e.g., ./run --memcheck app), which uses a tool called Valgrind to monitor memory usage. For more information on that, see the section titled Using Valgrind to check your memory usage in my most recent ICS 45C Project #2.

How your work will be graded

Unlike other projects, this project will be graded on a 2-point scale, with the 2 points being allocated completely to whether or not you submitted something that meets all of the above requirements. We'll be using automation — based around unit tests using Google Tests, as well as checking for other violations of the requirements (e.g., uses of the standard library) — to determine a score for each of you. Note, too, that if your submission cannot be graded automatically — because, for example, you didn't submit a project0.tar.gz file generated by the provided gather script, your score will be 0.

Gathering and retrieving files from the ICS 46 VM for submission

When you've completed your work on this project, you'll need to submit your C++ source and header files to us. Because we'll be using some automated tools to test your work, it's important that everyone submits their work in the same format — files arranged in the same way, in the same directories, etc. — so I've provided a script called gather in your project directory that will gather up the necessary files, arrange them in the way that we expect, and prepare a file called project0.tar.gz; that is the only file you'll need to submit.

The gather script will gather all of the files in your app, core, exp, and gtest directories and no others, so be sure that anything you want to submit is in the app, core, exp, or gtest directories before running it.

What's a .tar.gz?

A .tar.gz file (sometimes called a "tarball") is a compressed archive format common on Linux and various other flavors of Unix. (The .tar means that it is an archive of files; the .gz means that the archive has been compressed using an algorithm called gzip.)

Submitting your work from within the VM

When you're ready to submit your project0.tar.gz file, you'll want to submit it to our web-based system called Checkmate (described below). The easiest way to do this is to use the web browser (Firefox) built into the ICS 46 VM, which will allow you to log into Checkmate and submit the file as you would on your host operating system.

Alternatively, you might prefer to retrieve the file from your VM and submit it from your host operating system; if so, see the next section for instructions on how to retrieve the file. (It's not a bad idea to learn how to do this, anyway, as it provides you a way to back up your work, by copying it off of your VM and on to something else.)

Take a moment to be sure you're submitting the tarball you'd like to have graded. It's not a bad idea to copy the file somewhere temporarily, extract it, and ensure it's what you want to submit. For example, you might run these commands to do that:

mkdir -p ~/temp
cp project0.tar.gz ~/temp
cd ~/temp
tar xfvz project0.tar.gz

Now check the files in the ~/temp directory to make sure they're what you want to submit. If so, submit the project0.tar.gz file to Checkmate.

Retrieving the tarball from your VM

You might also want to retrieve the tarball from your VM and use your host operating system to submit it — or you might just want to keep a backup copy on your host (which isn't a bad idea, actually). If so, you'll need to know how to retrieve files from your VM.

The simplest method for retrieving a file is to use a protocol called SCP. SCP is a protocol that allows you to copy files from one machine to another. You'd connect to your VM using SCP, then copy the tarball to your host. How you use SCP depends on your host operating system.

Inspecting your tarball before submitting it

It's not a bad idea to inspect the contents of your tarball before you submit it, just to be sure that (a) all of the files you want to submit are included, and (b) the right versions of the files are included. How you open the file depends on your host operating system:


After using the gather script in your project directory to gather up your C++ source and header files into a single project0.tar.gz file, then submit that file (and only that file!) to Checkmate.

Follow this link for a discussion of how to submit your project via Checkmate. Be aware that I'll be holding you to all of the rules specified in that document, including the one that says that you're responsible for submitting the version of the project that you want graded. We won't regrade a project simply because you submitted the wrong version accidentally. (It's not a bad idea to look at the contents of your tarball on your host operating system before submitting it.)

Can I submit after the deadline?

This project is not included in the late work policy for this course. It needs to be completed on schedule and submitted before the due date above. Submissions beyond that deadline will not be considered.

The late work policy for this course — which does not apply to this project, but applies to all of the others — is described in the section titled Late work at this link.

Understanding the risks of using something other than the ICS 46 VM

You are certainly within your rights to use something other than the ICS 46 VM to do your work this quarter, but you should be aware that you are bearing some risks by doing so:

At minimum, my suggestion is to get the ICS 46 VM set up, so that you can test your projects in it before submitting them and then run the gather script before submission, even if you prefer to do your day-to-day work elsewhere.