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

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, macOS, 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. This way, everyone is running the same version of the same operating system, with the same versions of the same tools installed on it, which turns out to be more important when working with a natively-compiled language like C++ than it would be in, for example, Python or Java.

Setting up the ICS 45C VM

Before downloading and installing the ICS 45C VM, there's an important prerequisite you'll need first: the hypervisor! However, what you'll need is a little different, depending on what kind of host you'll be running on.

If you're running Windows or Linux on an Intel (or compatible) processor, you'll want to use VMware and run the x64 version of the ICS 45C VM.
If you're running macOS on an Intel processor, you'll want to use VMware and run the x64 version of the ICS 45C VM.
If you're running macOS on an Apple Silicon processor (such as an M1), you'll want to use UTM and run the ARM64 version of the ICS 45C VM.

Determine which of these you need — we can help you, if you're not sure — and then click one of the links below and follow the installation instructions you find there.

Setting up the ICS 45C VM in the ICS labs

If you want to use the ICS 45C VM in the ICS labs, you'll find that the Windows workstations in the lab include VMware, so you should be able to obtain the x64 version of the ICS 45C VM and create a VM on 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.

Using the ICS 45C VM

Once you've successfully installed your ICS 45C VM, booted it up, and logged into it, you'll see a desktop, much like you would see on Windows or macOS. In the bottom-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 one of these (depending on which version of the VM you installed):

ics45c@ics45c-2022spring-x64 : ~ $

ics45c@ics45c-2022spring-arm64 : ~ $

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-2022spring-x64, identifies the username (ics45c) and the name of the VM (e.g., ics45c-2022spring-x64). 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:

From the shell prompt, type the command passwd and press Enter.
When asked for the current password, type ics45c and press Enter.
When asked for a new password, type something else that you can remember and press Enter.
Finally, you'll be asked to re-type the new password to confirm it's the one you want. Type your new password again and press Enter.
If you typed the new password the same way twice, your password is now changed. Don't lose your new password! There's nothing we'll be able to do to help you get it back if you do!

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-2022spring-x64 : ~/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/  version

(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. version is a file that describes the current version of the environment.

(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):

environment, which contains general tools that we'll use throughout the quarter. Not all of the tools we need are there to begin with, but, as we'll see, a single command can be used to download the latest environment from the course web site, so you can stay up to date.
- As a general rule, you'll want to leave the files in this directory alone. You have the power on your VM to do pretty much anything you want, though these files turn out to be important for what we'll be doing. But if you ever do cause problems in this directory, there's an easy way to get it back, as we'll see.
projects, which is initially missing, but will be created later in this project; it will ultimately contain a separate directory for each project you work on — every time you want to write a new program, you'll need a new "project," even if it's one you're not going to turn in.

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:

From the shell prompt, type the command ics45c start hello basic. In this example, start means we want to start a new project, hello is the name of our project, and basic is the name of the template that we want to create the project from. (The basic template is already installed in the ~/environment/templates directory.)
A new directory ~/projects/hello will be created, containing all of the files you need to compile and run your first C++ program.
Change to the ~/projects/hello directory by typing the command cd ~/projects/hello. Use the ls command to take a look around.
- You'll see a directory called app, which is where you'll store the C++ source code for your project (the "app" that you're building). Additionally, there are several executable scripts such as build, clean, and run — you can tell they're executable because their names are followed by * in the directory listing — and a file called CMakeLists.txt, which is a file used to configure compiler settings (a longer story for another day).
- You'll also see a directory called gtest, which is where you can write unit tests for use with a unit testing framework called Google Test, which we'll use later this quarter. You can safely ignore this directory for now.
- Additionally, you'll see a directory called exp, which is available so you can write short programs that experiment with features of the larger program you're building. As with gtest, you can safely ignore it for now.
To see the contents of the app directory, type ls app. You'll see a single file, main.cpp, which contains an empty C++ program. Edit that file using a text editor. The simplest editor to use from within the shell is nano; a more familiar GUI-based editor called Visual Studio Code is available and can be run using the command code . from within a project directory (note the space and the dot after the word code). Personally, I prefer vim, and I've had a lot of students prefer emacs. In general, it's not important which editor you choose, and you can expect any of them to have a learning curve. Many tutorials online will explain the details of how to use these editors, so I'll leave that to you to figure out. Using whichever editor you'd like, edit main.cpp so that the contents of the file look like this:
```
#include <iostream>


int main()
{
    std::cout << "Hello Boo!" << std::endl;
    return 0;
}
```
Make sure the changes you made are to a file called main.cpp in the ~/projects/hello/app directory. If you save main.cpp into ~/projects/hello, the subsequent steps will fail. (Our projects in this course will all work under the assumption that all of your C++ code is in a subdirectory called app, all of your unit tests are in a subdirectory called gtest, and any other experimental code you write is in a subdirectory called exp.)
Once you've saved your changes to app/main.cpp, you're ready to build the program and run it. From the ~/projects/hello directory, enter the command ./build (note the dot and the slash; that's important). You'll see a fair amount of output, which should contain three messages like this, which means that the program was compiled and linked successfully:
```
...
[ 33%] Built target a.out.app
...
[ 66%] Build target a.out.exp
...
[100%] Built target a.out.gtest
```
Notice that three separate programs have been built:
- An app, which has the main() function from your app directory as its entry point and is intended to be the main program you're developing for a given project
- An exp, which has the main() function from your exp directory as its entry point and is intended for whatever experimentation you'd like
- A gtest, which has the main() function from your gtest directory as its entry point and is intended to run a set of unit tests
You can avoid waiting for all three programs to build by specifying which of them you'd like to build, e.g., ./build app, in which case only the specified one will be built.
Finally, if building the program was successful, from the ~/projects/hello directory, enter the command ./run app, which should display this output:
```
Hello Boo!
```

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:

ics45c version, which will display the current version of the environment you have. This will generally consist of a timestamp (the time it was published to the course web site) and a short description.
ics45c refresh, which will connect to the course web site and download the latest version of the environment, installing it in your ~/environment directory in place of your existing one. (Note: Do not store your own files in the ~/environment directory, as they will be wiped out by this process.)
ics45c restore, which you can use if you ever accidentally delete or corrupt your environment to the point where you can't run the above two commands. This will restore the original environment from when your ICS 45C VM was new; you could subsequently use the ics45c refresh command, then, to download the latest one.

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. SSH also forms the basis of other ways to connect to your VM, such as the ability to transfer files between your host and your VM (using protocols that work via SSH, such as SCP or SFTP), or even the ability to edit code on your host and save changes back to the VM (which some editors, such as Visual Studio Code, can be configured to do).

The ICS 45C VM has been configured already so that you can connect to via SSH 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.

Determining where to connect

To connect to the ICS 45C VM via SSH, you'll need to know two things:

An IP address, which is made up of four numbers (in the range 0-255) separated by dots. Ordinarily, any machine connected to a network will have one of these assigned to it.
A port, which is a number (in the range 0-65535) that effectively selects one program running on a machine that's connected to a network.

What you'll need will be different depending on whether you're using the x64 or ARM64 version of the ICS 45C VM.

IP address and port of the VM

The ICS 45C VM has been configured so that it will appear to your host operating system to have an IP address, which you can use to connect to the VM from within your host operating system. Whether you're using VMware or UTM, an IP address will be assigned to your VM when it starts up, so the best way to find out your VM's address is to ask it, by running the command ip addr. This command will give you a fair amount of output, but there's only one part of it you'll be interested in. When I ran the ip addr command on the ICS 45C VM, this is what I saw.

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host 
       valid_lft forever preferred_lft forever
2: ens33: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 00:0c:29:74:8a:d0 brd ff:ff:ff:ff:ff:ff
    inet 192.168.65.128/24 brd 192.168.65.255 scope global dynamic ens33
       valid_lft 992sec preferred_lft 992sec
    inet6 fe80::20c:29ff:fe74:8ad0/64 scope link 
       valid_lft forever preferred_lft forever

What this is describing are the VM's two network adapters. One is listed as lo and is what's called a loopback adapter. Its job is to allow programs on the VM to talk to each other without using the external network. The other is listed as ens33 and is the one that's used to communicate with the Internet. (Yours may have a different name; for example, on UTM, I've seen enp0s9 instead.) Within the information about your Internet-facing network adapter, you'll see an IP address listed — which I've boldfaced and underlined here. Mine is listed as 192.168.65.128, but yours may differ. In my experience, the 192.168 is always the same, VMware chooses the third number (in my case, 65) upon installation, and the fourth is issued when the VM starts up, which means it can vary if you reboot your VM — though, in my experience, they've been fairly stable for me, if I use the same few VMs most of the time.

To be clear, the IP address listed 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.

The right port to use will be 22, which is the default for SSH connections.

Connecting via SSH using PuTTY on Windows

If you run Windows, a good tool to use for SSH connections is PuTTY, which you can download here. (What you want to download from that page is putty-64bit-0.76-installer.msi, which is a program that installs PuTTY and all of its associated tools.)

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

Under Host Name (or IP address), type the IP address that you determined previously
Under Connection type, select SSH
Under Port, type the port number that you determined previously

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-2022spring-x64) 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 macOS or various flavors of Unix

On macOS or various flavors of Unix, your best bet will be to bring up a Terminal window, then issue the command ssh -p PORT ics45c@VM_IP_ADDRESS, replacing PORT with the port number and VM_IP_ADDRESS with the IP address of your VM. 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 operating 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 this command 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:

Though I've indented the text above to set it apart from the rest of this project write-up, note that the bottom level of blocks must begin in the leftmost column of the output (i.e., it should not be indented).
There must be no spaces after the last * character on each line.
There must be a newline character on the end of each line, including the last one.

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:

First, be sure that you've build your program with the ./build app command. Only if that was successful can you proceed to the next step.
Next, decide what input you'd like to use for the comparison. For example, if you want to compare your three-block-high pyramid to the one generated by the example solution, you'd use the input 3.
Issue the shell command ./compare 3 (replacing 3 with whatever you'd like the test input to be). Behind the scenes, the compare script will run your program and the provided solution with the input 3, then compare the outputs to see if they're character-for-character identical.
- If the outputs were identical, you'll be told that no differences were found.
- If there was even the slightest difference — including extra spaces, extra blank lines, etc. — you'll instead be told that there were differences found, and the differences will be shown to you in a format sometimes known as a diff. (In a diff, there's a left-hand side and a right-hand side; your program's output is the left, and the provided solution's is the right.)

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 3% 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. Additionally, only files meeting certain characteristics will be gathered, even if they're in these directories:

Only files whose names end in either .hpp or .cpp are gathered.
Only files whose sizes are not more than 128KB are gathered.

Files not meeting these characteristics are extremely unlikely to be things that we're interested in — they'll generally be temporary files generated by your editor or development environment, for example, which has led to students attempting to submit hundred-megabyte submissions for what are otherwise small programs.

Make note of the list of files that the gather script picked up; they'll be shown to you. It's your responsibility to ensure that nothing is missing, and "I wanted to submit this file but gather didn't pick it up" does not constitute an excuse to submit late work.

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 Canvas. 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 Canvas and submit the file as you would 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:

On Windows, you will need to obtain a tool that can open a .tar.gz file; Windows doesn't support this ability by default. You may have such a tool already (e.g., WinZip, WinRAR); if not, a good free choice is 7-Zip.
On macOS, you'll find that you can simply navigate to the file in Finder and double-click on it, which will extract its contents. It should create a directory called app and another called gtest inside of the directory where the .tar.gz file resides, containing all of the files that are included in the tarball.
On other flavors of Unix or Linux, you can extract the tarball most easily from a shell prompt, by changing into the directory containing the tarball and issuing the command tar xvfz project0.tar.gz. (This works from a Terminal window on macOS, as well.)

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

Understand that we will only accept projects submitted to the appropriate dropbox (for the appropriate assignment) on Canvas; we do not accept printed copies of your projects, nor do we accept them via email or other means under any circumstances.

You are responsible for submitting the version of your project that you want graded. We will grade the most recent submission made before the deadline. Accidentally submitting the wrong version, nor is there any remedy (outside of the late policy described above) for forgetting to submit your work at all.

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.

What do I do if Canvas slightly adjusts my filename?

Canvas will sometimes modify your filenames when you submit them (e.g., when you submit the same file twice, it will change the name of your second submission to end in -1.tar.gz instead of just .tar.gz). In general, this is fine; as long as the file you submitted has the correct name, we'll be able to obtain it with that same name, even if Canvas adjusts it.

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:

You'll be responsible for setting up and configuring the necessary software. As a rule, we won't be available to help configure environments other than the ICS 45C VM; you'll be on your own. For example, the provided project templates are specifically set up to work on the ICS 45C VM; making them work on something else will be up to you, and you might find this to be a tricky task, even if you believe you have all the same software we do.
We'll be using the ICS 45C VM to grade your work, so if you write a program that compiles and runs on your own setup, but does not compile and run in the ICS 45C VM, you'll be the one to bear that risk. (This is not at all unrealistic, given differences in C++ compiler versions and the operating systems they run on, so don't discount this risk lightly.)
When it comes time to submit your work, we expect everyone to use the provided gather script to gather their files for submission, so that everyone's submission is in the same format. We have test automation tools that depend on that. If you work outside of the ICS 45C VM, you'll have the additional problem of making sure that your submission is in the right format — and, if it's not, risk us not being able to grade your work, or that we refuse to grade your submission because we would have to perform special workarounds to be able to grade it.

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.