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

Overview

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 3% 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.

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 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. 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 46 VM

Before downloading and installing the ICS 46 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 46 VM.
If you're running macOS on an Intel processor, you'll want to use VMware and run the x64 version of the ICS 46 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 46 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 46 VM in the ICS labs

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

Using the ICS 46 VM

Once you've successfully installed your ICS 46 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):

ics46@ics46-2022spring-x64 : ~ $

ics46@ics46-2022spring-arm64 : ~ $

The shell prompt

When using the ICS 46 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, ics46@ics46-2022spring-x64, identifies the username (ics46) and the name of the VM (ics46-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/ics46; 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 ics46 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:

ics46@ics46-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. 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 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. 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 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 provided, your ICS 46 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 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:

From the shell prompt, type the command ics46 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 a C++ program, along with some additional tools that will assist in development the more complex projects we'll work on this quarter.
Change to the ~/projects/hello directory by typing the command cd ~/projects/hello. Use the ls command to take a look around.
Notably, you'll see four directories in your project directory:
- core, which is where you'll normally write most of the C++ source code for your projects. The idea is that the core directory contains the "core" code for your project (e.g., data structures, algorithms, user interface functionality, etc.), without a main() function, unit tests, or any other outer "shell."
- app, which will generally contain only a single source file that defines the main() function for your project. Ordinarily, you'll want main() to do nothing but call into code from your core directory or other code that we've provided; quite often, your main() function will be just a couple of lines of code.
- exp, which will contain a "playground" program in which you can experiment with code from your core directory without affecting the main program you're writing. In this directory, you'll write a separate main() function, along with whatever other experimental code you'd like to write. This can be handy for testing or experimenting.
- gtest, which will contain unit tests written for the Google Test framework. Already present will be a file gtestmain.cpp that you should not modify. Simply create new source files with unit tests in them and they will automatically be picked up on the next build.
Additionally, you'll see a few scripts in your project directory with names such as build, clean, gather, 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).
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;
}
```
Create a source file in your core directory and write a function in it; any function will do, but make it something that takes one or more parameters and returns a result. Then create a header file in the core directory that declares your function. (As will be our custom in this course, name your source files with names ending in .cpp and your header files with names ending in .hpp.)
Edit the main.cpp file in your app directory so that it calls your function and prints the result to std::cout, in addition to just printing "Hello Boo!". Note that you'll be able to #include files from your core directory in source files in your app directory — that kind of thing has been set up for you already in CMakeLists.txt.
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, which should display whatever output emanates from the function you wrote. Note that you can pass an additional parameter to the ./run script specifying which program you'd like to run:
- ./run app
- ./run exp
- ./run gtest
and that you can pass an additional parameter --memcheck (note there are two dashes before memcheck) which will run one of these programs using a tool called Memcheck, which watches for erroneous uses of memory and displays error messages when it detects them. So, for example, if you wanted to run the app using Memcheck, issuing the command ./run --memcheck app would do the trick.
Add a couple of unit tests in your gtest directory and a short experiment in your exp directory. Try rebuilding afterward, fix any compile-time errors, and then try running each of the three programs, so you're sure you understand the way the project directory is laid out; we'll be following this basic model all quarter.
- If you've never used Google Test to write unit tests before, have a look at my Unit Testing notes from ICS 45C. You're going to need this skill throughout this quarter.

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:

ics46 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.
ics46 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.)
ics46 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 46 VM was new; you could subsequently use the ics46 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 46 VM

Another way to connect to your ICS 46 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 46 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 46 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 46 VM.

IP address and port of the VM

The ICS 46 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 46 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., ics46-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 ics46@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 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

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.

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 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 from your ICS 46 VM

Your ICS 46 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 — 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 are not permitted to use any standard library functionality — this includes both the C Standard Library and the C++ Standard Library — since the goal is to exercise your skills at writing lower-level C++ code. (This is the kind of problem you'll need to be adept at solving, if you want to succeed in this course, so better to test and solidify those skills out now.) Note that even including a standard header file, such as <iostream> or <cstdlib> violates this rule.
Implementations of all member functions must be written in String.cpp, though you will probably need to declare some additional private members (member variables and/or member functions) in String.hpp.
Your implementation must not leak or mismanage memory, even in situations when exceptions are thrown from your member functions. (This includes both exceptions that you throw yourself, as well as exceptions arising from the things you do — note, for example, that the new operator throws std::bad_alloc when there is not enough memory to allocate what's been asked for.)

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 Illuminating the Dark Corners notes from my most recent ICS 45C.

How do I debug my program without using iostream?

You may have become accustomed to doing a lot of your debugging by printing things to the standard output by including, for example, the <iostream> header from the C++ Standard Library. Since you aren't permitted to include standard headers in this project, you might be wondering how to debug your work. In truth, the kind of work you're doing in this project probably doesn't lend itself to printing-based debugging, anyway, since the kinds of things that are likely to go wrong will have symptoms that will be difficult to diagnose by simply printing things out.

For that reason, debugging your work in this project is best done with the LLDB debugger that's part of our ICS 46 VM environment. If LLDB is new for you, check out the Illuminating the Dark Corners notes from my most recent ICS 45C. Learning how to use it is likely to pay off in future projects, when the debugging tasks will sometimes be even gnarlier than those you'll see in this project.

How your work will be graded

Unlike other projects, this project will be graded on a 3-point scale, with the 3 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, which 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. 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. (You may have preferred using .h for header files in your prior coursework, but we'll be standardizing on .hpp throughout the quarter.)
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 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 Canvas (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 Canvas 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 Canvas.

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.

Windows has no built-in support for SCP, but there are a few well-known programs you can download and install. The simplest is called WinSCP, which provides a graphical user interface for connecting to your VM using SCP.
- Download WinSCP from winscp.net. The easiest option is to select the Installation package, which you would want to download and then run; it will install WinSCP and make it available like a typical Windows application (e.g., from the Start menu).
- Launch the WinSCP application. Click New to create a new session and enter the following values:
  - Under Host name, specify the IP address of your VM
  - Under Port number, specify 22
  - Under User name, specify ics46
  - Under Password, specify the password belonging to the ics46 user account on your VM — you did change it already, didn't you?
  - Leave Private key file blank
  - Next to File protocol, select SCP
  - Now that you've set these up, you can click the Save... button to save these settings so you don't have to enter them again, then click Login.
- Once logged in, you should see the files on your VM. Navigate to the /home/ics46/projects/proj0 directory. You should now see the project0.tar.gz file you created earlier, which you can drag and drop to your host machine wherever you'd like it to be stored.
- After copying the file to your host machine, you can close WinSCP.
If you use macOS, Linux, or other flavors of Unix, you're in luck! SCP support is built into your operating system. Your best bet is to bring up a shell prompt (e.g., a Terminal window in macOS), decide what directory on your host machine you want to copy the file to, then to issue the command scp ics46@VM_IP_ADDRESS:~/projects/proj0/project0.tar.gz TARGET_DIRECTORY_ON_HOST to copy the file.
- So, for example, if you want to copy the tarball to the directory /Users/boo/Documents on your host machine, you would issue this command: scp ics46@VM_IP_ADDRESS:~/projects/proj0/project0.tar.gz /Users/boo/Documents
- Note that whatever directory you choose on your host machine will already have to exist!

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 directories called app, core, and 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.

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

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 46 VM; you'll be on your own. For example, the provided project templates are specifically set up to work on the ICS 46 VM; making them work on something else will be up to you, and you might find this to be a tricky (and sometimes impossible) task, even if you believe you have all the same software we do.
We'll be using the ICS 46 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 46 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 46 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 deduct a substantial number of points from your submission because we had to perform special workarounds to be able to grade it.

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.