ICS 45C Spring 2019
Project #0: Getting to Know the ICS 45C VM

Due date and time: Friday, April 12, 11:59pm


Overview

The goal of this project is to allow you to work through downloading and setting up the ICS 45C VM, which is the development environment we'll be using to do our work in this course, then using it to write a short C++ program. Having worked through this project, you'll have set up the VM to run on your own computer, experimented with it a little bit, 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 fairly short C++ program 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 open source projects, is not offering you that choice.


Virtualization

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 than 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 45C 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 45C 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 as your host. (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 6.0.4. This is the only version that I've tested the ICS 45C 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 45C 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 6.0.4.


What is the ICS 45C VM?

The ICS 45C 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 18.10 (64-bit), 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. You'll nonetheless spend a lot of your time at the command line within your VM's GUI.

In addition to the operating system, the ICS 45C VM has a set of software already installed and configured for our use. You may not find that you need all of these software packages, but some of these are going to be vital, and others are available if you do.

Along with this preinstalled software, the ICS 45C 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. 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 45C VM

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

The ICS 45C VM is available here.

The files are 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; it's a few gigabytes. (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.

Being sure you have a complete copy of the ICS 45C VM before you proceed

In past quarters, we've experienced a number of problems with students receiving only partial copies of the ICS 45C VM, given that it's such a large download. Before proceeding, be sure that the size of the file you downloaded is exactly 3,076,412,928 bytes. (Your operating system may show you a shorthand, like 3,004,310 KB or 2.86 GB, but you'll want to verify it all the way to the byte.) If not, you've got a corrupt copy of the file and will need to download it again.

Some students have asked me in the past for an MD5 checksum for this file, as well. This quarter's VM has the following MD5 checksum: 24483954d2cf908891b027b3ba20509f.

What to do if you've taken the course before

If you've taken this course before, you're still going to need to download this quarter's ICS 45C VM. The VM changes slightly every quarter, in ways that sometimes change whether or not code will run the same way (or, in some cases, will even compile at all); furthermore, a previous quarter's VM will only support the previous quarter's assignments, notes, and so on.

You're also going to want to upgrade VirtualBox, if you've installed an older version during a previous iteration of this course. You'll need to be running the same version as everyone else this quarter.


Importing the ICS 45C VM into VirtualBox

Once you've downloaded the OVA file containing the ICS 45C 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 45C 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

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 ones, 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 sometimes configured automatically, but often needs to be configured manually, though your experience may vary a bit. (I've also found that I sometimes need to reconfigure these settings, as they occasionally get reset, for reasons I've not been able to identify.) 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 will need around 10 GB 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 ics45c-2019spring 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 or UEFI settings before you can run the ICS 45C 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). This is a setting you can change:

Additionally, when you import the VM, one of the choices you'll have is where you'd like to store it — this will default to the configured default setting, but you can change it on a VM-by-VM basis. So I suggest carefully considering where you want your VM before you import it.

Still, if you decide you'd rather move it to a new location after you've created it, that's possible too.

Using the ICS 45C VM in the ICS labs

If you want to use the ICS 45C 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; 8GB is probably not enough, so 16GB and above is a safer bet.


Starting the ICS 45C VM and logging into it for the first time

Once you've imported the ICS 45C 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 ics45c-2019spring VM and click the Start button. You'll see another window pop up, which is the console of your VM.

If your ICS 45C VM does not start up properly (e.g., it only displays a blank area, but doesn't appear to do anything else), the likeliest problem is that you need to enable virtualization support. See the section titled Ensuring you have 64-bit VM support above for more details.

Logging into the ICS 45C VM

Once you've booted up your VM, you'll see a dialog box asking you to specify a username and a password. The username is selected from a dropdown list; ics45c 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 ics45c — 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. Find the Terminal application (which might also be listed as Terminal Emulator) and start it. A window should pop up and contain a prompt that looks like this:

ics45c@ics45c-2019spring : ~ $

(Note: You might find the default font and colors not to your liking, though it's easy enough to change them. From the Edit menu in your Terminal window, select Preferences.... A dialog will pop up allowing you to configure whatever you'd like; when you're done, click Close, and subsequent uses of the Terminal application will repsect the changes you made.)

The shell prompt

When using the ICS 45C VM, there's a pretty good chance that 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, ics45c@ics45c-2019spring, identifies the username (ics45c) and the name of the VM (ics45c-2019spring). 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 — ~ is a common shorthand in Linux for our actual home directory location, /home/ics45c; every user has a home directory, which is quite often stored in the location /home/USERNAME.

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 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 (that's a lowercase L followed by a lowercase S) and press Enter. ls is a way to list the files residing in the current working directory. You should see something sort of like this:

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

The names listed in blue and followed by a slash are directories. Files are listed in gray and are not followed by a slash. Executable files (i.e., programs you can run) are listed in green and are followed by a star. Most likely, your home directory will only contain directories initially, but we'll see files and executable files soon enough.

Many of the directories you'll see are installed automatically with XFCE, the graphical user interface that we're using, but the environment/ directory, which is specific to our course, is the one we're primarily interested in for now.

You can tell that all of these are themselves directories (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:

ics45c@ics45c-2019spring : ~/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 directory. Type the command ls again.

scripts/  templates/  updates/

(This is your first important lesson about interacting with the shell prompt. The commands you issue quite often work differently depending on where you are, i.e., what your current working directory is. For example, ls lists the files in the current working directory, so it naturally gives you different output when your current working directory changes.)

The scripts directory contains a small set of scripts used to automate certain tasks for our 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 45C VM, if we discover a widespread problem for which lots of you 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 its 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 45C VM has been set up

As provided, your ICS 45C VM's home directory will contain two directories of interest in this course (along with a fair number of others created by the GUI, but that are not relevant to our work):

The ics45c command

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

Creating a new project and writing your first C++ program

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

Restoring or refreshing your ICS 45C environment

Periodically throughout the quarter, it will be necessary to refresh your ICS 45C 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 45C VM

Another way to connect to your ICS 45C VM, if you prefer, is to connect to it using a protocol called SSH, which allows you to access a shell prompt, but without the XFCE GUI being visible to you. The ICS 45C VM has been configured already so that you can connect to it this way, if you prefer. Depending on your host operating system, you would use slightly different tools for this. (And you might find this useful, 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 45C VM has been configured so that it will appear to your host operating system to have the IP address 192.168.56.45. (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., ics45c-2019spring) 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 ics45c@192.168.56.45. This should display the login prompt for your ICS 45C 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

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

Shutting down or rebooting the GUI version of the VM

Near the bottom-right corner of your VM's GUI, you'll see an icon that looks like an on/off button (one of the icons to the left of a clock that displays the current time). Click that icon 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 Restart.... Either of these commands should warn you about closing programs first, so that you don't accidentally lose work.

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

Shutting down or rebooting the VM from a shell prompt

Shutting down the ICS 45C VM from a shell prompt is simple. Log into your VM (either in the VM console window or via SSH), so that you'll have access to any 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 other programs that your VM depends on. But, once in a while, we'll 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 ics45c 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 from your ICS 45C VM

Your ICS 45C VM is capable of accessing the Internet — provided that your host operating system is connected (e.g., to the UCI Mobile Access wireless network on campus). The VM includes a web browser (Firefox), which you can use as you would use any other browser. 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 interfaces is all you need to do, which you can do by issuing these commands from a shell prompt.

sudo netplan apply

This has solved the problem for me every time I've had it; your mileage, 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 discussions 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. A lot of what I know about using Linux and a command prompt have their roots in things I learned when I was a student, when I also faced this same challenge. Embrace this challenge and you will emerge stronger!


The program

As a warm-up, this project asks you to write and submit a short C++ program. The program itself isn't actually the interesting part, though it's one that you might find takes you a little bit of time to write. The main goal here is to be sure you're able to use the ICS 45C VM to do your work, that you learn what you need to know about one of the available text editors to write your program, and that you use 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 45C VM for this project, to be sure that you can use it for your work later in the quarter.

Creating a new project on the ICS 45C VM

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

Compiling and running your program

Whatever C++ code you write should be placed into the app directory inside your project directory. (You can safely ignore the exp and gtest directories in this project.) When you're reading to compile it, change into the directory ~/projects/proj0 (if you're not already there) and issue the command ./build app. (Note the dot and the slash in front of the word "build", and the space between "build" and "app"; those are important.) If compiling is successful, then issue the command ./run to run your program.

The program's requirements

Your program is required to read a single line of input from the user (without printing any input prompt), which is expected to be a positive integer n. You can freely assume this will be a positive integer, and it's not important what you do in any other case; we'll only test your program with positive integer input. You can also freely assume that n will not be greater than 999.

After reading the input, your program will print a block pyramid of size n. The bottom level of the pyramid will be n blocks wide, the level just above that will be n − 1 blocks wide, and so on, with the top level consisting of a single block. Each level's blocks are centered with respect to the blocks on the level below.

The precise format is best demonstrated with an example. If the input to the program was 3, the output would look like this:

  ***
  * *
 *****
 * * *
*******
* * * *
*******

A few additional requirements apply:

We will not be answering any additional questions about the structure of a block pyramid; the description above is enough to solve the problem. However, we do have some tools to let you experiment some more, and to let you know whether your program is ultimately correct.

Experimenting with the provided solution

Your output is required to be precisely the same as what is specified here, down to the character, so some care will have to be taken in ensuring that you've got it right. To avoid you feeling like you have to wait for us to give you assurance, an example solution has been provided in the project0 project template; while we won't necessarily make a habit of this, it will be useful in this project to be able to see precise expected output easily.

To run the provided solution, change into the directory ~/projects/proj0 (if you're not already there) and issue the command ./solution. You'll see no output initially, because the program is waiting for you to type its input. Type 3 and press Enter. You will then see a block pyramid that is three blocks high.

Try other inputs, and make sure you have a clear understanding of what block pyramids of different sizes are supposed to look like. We will not be providing you with formulas or further descriptions of the requirements; everything you need to know about it can be deduced by running the solution with various inputs and inspecting the corresponding outputs, and we're leaving it to you to figure out an appropriate algorithm to print the pyramid.

Comparing your program's output to the provided solution automatically

When you think you've got the program finished, you'll want to be absolutely sure that your program's output exactly matches the output of the provided solution. Rather than eyeballing it, we've provided a script that does this for you automatically. Here's what you need to do to try it:

If you are not able to successfully run the compare script with a variety of valid inputs (any positive integer is valid) and be told that there are no differences, your program is not done, and you will not receive the full 2% credit for it. There are no exceptions!

How to solve the problem

You can use any C++ techniques you'd like and write the program in any way, so long as it compiles, runs, and generates the correct output for valid inputs. We will not be grading this project for style or quality at all — something which will most definitely change going forward! The only goal is that we're able to take the source code you submitted, run the provided build script to compile and link it, then run the provided compare script to validate it.


Gathering and retrieving files from the ICS 45C 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, which is the only file you'll need to submit.

The gather script will gather all of the files in your app, exp, and gtest directories and no others, so be sure that anything you want to submit is in the app, 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 using the ICS 45C VM's GUI

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 45C 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.)

Retrieving the tarball from your VM

If you'd like to retrieve the tarball from your VM — because you prefer to submit it from your host operating system, or simply because you want to keep a separate copy of it — this is one way to do it.

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:


Deliverables

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 45C VM

You are certainly within your rights to use something other than the ICS 45C 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 45C 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.