ICS 45C Spring 2022, Installing VMware and the ICS 45C VM (x64)

Installing VMware

Before downloading and installing the ICS 45C VM, there's an important prerequisite you'll need first: the hypervisor! For this purpose, you'll need to install a compatible VMware product, which can be obtained free of charge by ICS students from a service called OnTheHub, which can be accessed here:

ICS OnTheHub

You'll need to log in with your ICS login and password — note that this isn't your UCInetID, but is the login and password that you'd use to log into the machines in the ICS labs. If you don't have an ICS account, your enrollment in an ICS major or an ICS course entitles you to one, but you'll need to get the account activated. To activate your ICS account, please follow these instructions from ICS Support:

Go to https://support.ics.uci.edu/auth

Enter your student ID number

Enter your name as lastname,firstname (included other names as on your student id)

Follow the on-screen prompts

Please note the strict password rules

Let us know if you need any additional help, by emailing helpdesk@ics.uci.edu

Once you're logged into OnTheHub, you'll want to download one of these two products (depending on your operating system):

If you're running Windows or Linux, you'll want VMware Workstation Pro 16.x.
If you're running macOS, you'll want VMware Fusion 12.x Pro.

Add the appropriate VMware product to your cart, then download and install it. Make a note, too, of the serial number that you're provided with; you'll need that after installation, so you can license your product and use it throughout the quarter. If you forget your serial number, you can always get it back by logging back into OnTheHub and viewing your account history, then viewing the details about your VMware download.

After installing VMware

There are a few things you'll want to do after installing VMware and starting it up for the first time.

From the Help menu, select Enter a license key. In the ensuing dialog, enter the serial number that you obtained previously, then click OK. This should license your product for a year or so — as of this writing, mine says I'm under an evaluation period that ends in 408 days, and I just installed it a few days ago.
From the View menu, select Autosize, then click Autofit guest. Also, make sure the setting under Autosize titled Autofit window is checked. (I found this change necessary, so that resizing the window would also resize my VM's desktop. I haven't tried this on VMware Fusion, as I don't have a Mac to test it on, but I needed to do this on VMware Workstation on Windows.)
From the Help menu, select Check for updates and install the latest. I found that my download was older than the most current version. As of this writing, I'm running VMware Workstation Pro 16.2.3; if I was on a Mac with an Intel processor, I'd run VMware Fusion 12.2.3 instead.

Once you've done those things, you're ready to move on to installing the ICS 45C VM.

What is the ICS 45C VM?

The ICS 45C VM is a complete installation of an operating system and the necessary software that we'll be using in this course (and little else). The operating system is Ubuntu Server 20.04.3 (x64 version), with a graphical user interface called XFCE, which provides a look-and-feel similar to what you might get on Windows or macOS. You'll nonetheless spend a lot of your time at the command line within your VM's GUI.

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

One web browser: Firefox, though you can certainly install others if you prefer them, which will allow you to browse the web from within your VM
OpenSSH Server, which allows you to connect to the VM via ssh, the way you might connect to the command line of another computer outside of your own.
Two C++ compilers: Clang (which we'll be using in this course) and GCC (which was used to get the system set up, but will not be used in the course).
Two debuggers: LLDB and GDB (either of which we may use in this course).
Two tools used to assist in compiling and linking C++ programs: CMake and Make.
A program analysis tool called Valgrind, which we'll be using to diagnose and fix low-level issues like memory leaks.
A unit testing framework called Google Test, which we'll be using to write automated tests of (portions of) our programs.
A source control tool called Git.
Four text editors: Vim, Emacs, Nano, and Visual Studio Code.
Python 3 and Java, in case you'd like to experiment with them comparatively as you work through this C++ course.

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

Downloading the ICS 45C VM (x64)

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

This is a large download. To preserve UCI and ICS network bandwidth, we would appreciate it if you would spread the load by sharing it with each other once downloaded; have one of you download it and give copies to ten others, and we'll save a lot of bandwidth that way.
By request of our system administrators, this download is inaccessible outside of the UCI campus network. If you try to download it from off-campus, you will likely receive a message that you are forbidden to access it. Your best move is to download it when you're physically on campus; you can potentially download it via the campus VPN, though you may run afoul of network usage restrictions that way. Be warned.
If you do download via the campus VPN, be sure you're using the Software VPN, as opposed to the Web VPN (which, for at least some students, appears to cap the size of downloaded files to 2 GB, but the ICS 45C VM is larger than that). More details about the Software VPN are available here.

The ICS 45C VM is available here.

ICS 45C VM (x64) — only available while on the campus network (see above)

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

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

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

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

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

What to do if you've taken the course before

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

You may also need to upgrade VMware, if you've installed an older version during a previous iteration of this course. You'll need to be running the same version as everyone else this quarter; see above.

Importing the ICS 45C VM into VMware

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

Prerequisites: Preparing to import a 64-bit VM

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

You must have a 64-bit processor. Note that 32-bit processors on personal computers are exceptionally rare these days, so there's a really good chance you meet this requirement already. Interestingly, it's not important whether you have a 32-bit or 64-bit version of your host operating system; either is fine, as long as your processor is 64-bit.
Your processor's virtualization support must be enabled. Intel and AMD processors have special support for virtualization — Intel calls it VT-x, while AMD calls it AMD-v — and many machines have it turned off by default. (According to my research, Macs will tend always to have this turned on; Windows machines are more hit-or-miss, but you're still likelier to have the support already than not.) To turn virtualization support on, you'd need to modify your BIOS or UEFI settings. How you do that is different depending on what machine you're running, so I can't give you specific instructions on how to do it, but the setting you're looking for is probably called Virtualization, VT-x, or AMD-v, and you'd want to make sure any setting like that is listed as Enabled or On.
If you're running Windows, the Hyper-V feature will need to be disabled. This is pretty rare on anything but the Server versions of Windows, so you're unlikely to have it, but it's one more thing to check if you have problems further down the line. (Apparently, a future version of VMware Workstation will be compatible with Hyper-V, but we're not quite there yet.)

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

Launching VMware

Launch the VMware application that you installed previously. This will bring up a window titled VMware Workstation or VMware Fusion, which lists the VMs that you've installed, allowing you to do things like start them, stop them, create new ones, etc.

Importing the OVF into VMware

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

Note that you will need as many as 15 GB of free hard disk space in order to complete this process successfully. Be sure you have that available now before proceeding.

From the File menu, select Open....
Choose the .ova file you downloaded previously.
A dialog titled Import Virtual Machine will be shown, in which you can choose a name for your new virtual machine (which you're best off leaving as the default of ics45c-2022spring) and a location for it. Click Import to begin the process of importation.
- You may receive a warning indicating that The import failed because [it] did not pass OVF specification conformance or virtual hardware compliance checks. If you do, click the Retry button — this warning turns out to be innocuous, as far as I can tell — and it should succeed subsequently.
After waiting for a while for the import to be completed — this can take some time, as this is a large file — you should see a VM titled ics45c-2022spring listed in the VMware window. This is your newly-created ICS 45C VM.

Ensuring you have 64-bit VM support

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

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

Be sure that you've performed a full reboot of your machine after changing the virtualization settings in your BIOS or UEFI. This doesn't mean hibernation, sleep, or standby; you'll want to do a full reboot.

Don't feel like you need to do this now; just remember that you may need to come back to this a little later in the instructions.

A word about where the VM files are stored

Note that VMware prefers to store the VM files in a particular directory (e.g., on Windows, VMs are stored by default in C:\Users\your_user_name\Documents\Virtual Machines). This is a setting you can change:

Before importing the VM into VMware, open the Edit menu, then select Preferences.... On the ensuing dialog, find the setting titled something like Default location for virtual machines and choose your desired location for VMs to be stored. After making that change, any subsequently created or imported VM will be stored in your chosen location.

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

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

After importing the VM, find the directory on your hard drive containing the VM's files. Move the entire directory where you want it to be. Then, in VMware, right-click the ics45c-2022spring VM, then select Remove, which will remove the VM from your VMware list. Finally, from the File menu, select Open..., then browse to the directory in its new location and open the .vmx file within that directory.

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

Once you've imported the ICS 45C VM into VMware, you're ready to start it up and log into it for the first time. In the VMware window, select the ics45c-2022spring VM and click the Power on this virtual machine link. You'll see another window pop up, which is the console of your VM.

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

Logging into the ICS 45C VM

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

Having logged in, you should eventually see a desktop, much like you would see on Windows or 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 this:

ics45c@ics45c-2022spring-x64 : ~ $

If so, you're off and running! Go back to the Project #0 write-up and pick up where you left off.

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