Instructions

SoftSys Computational Setup #

This guide walks you through the steps necessary to set up your computer for the work you will do in this course. Once you have completed this setup, you should have most or all of the software tools you need to complete the exercises, homework, and projects in this course.

These instructions are only for Windows 10. If you are already running Linux, you should be able to more or less use it as is for this course, though you will want to make sure you are running an OS with a major version released in 2022 or later, like Ubuntu 22.04. If you are running macOS, most of this course should run as is, but a few things (like the Valgrind tool) will probably not work. macOS users can use the Virtual Machine option below, but please note the slight difference in instructions.

Setup Options #

For this course, you’ll need a UNIX environment with the ability to compile and run code in C. We have a few options for you to set this up if you don’t already have a UNIX environment. You should read the descriptions of each option and choose the one that you think will best suit you.

Run a Linux Virtual Machine #

You can download and run a virtual machine (VM) running Ubuntu 22.04, a common Linux-based operating system (OS). A VM is essentially a program running on your computer (whether Windows, macOS, or Linux) that emulates the components of a computer, allowing you to run a full OS within your existing machine.

Pros:

  • It’s relatively easy to set up.
  • The VM can be easily deleted after the course to conserve disk space.

Cons:

  • Performance can be slow, particularly on school-issued machines.
  • Occasional strange failures have been reported, such as blank displays or frozen screens. Debugging these issues can take time and is not always possible.
  • A few instances of data loss or corruption have been reported, so you should be comfortable backing up your work often.

Run Linux in Windows #

The Windows Subsystem for Linux (WSL) essentially runs a very stripped-down VM within Windows. After setting up WSL, you can install a Linux distribution, which is a version of the Linux operating system, like Ubuntu. Each Linux distribution can be installed and started like most other apps on your computer.

Pros:

  • Performance is pretty decent.
  • You do not need to pre-allocate disk space or restart your machine to use Linux.
  • WSL requires less configuration than a VM in most use cases.

Cons:

  • Depending on your specific version of Windows 10, setup might be a bit complicated.
  • Linux distributions in WSL are harder to configure than a VM or dual-boot installation.
  • A few issues related to Windows firewall have been reported.

Set up a Dual-Boot System #

You can set up a dual-boot system, which allows you to have two OSes side by side on your computer. Each time you start your computer, you’ll be able to choose which OS to boot into.

Pros:

  • Since your UNIX environment will be running on your computer’s actual hardware, performance will be close to what you have on your existing OS.
  • Failures such as those with the VM are much rarer.

Cons:

  • Not all laptops can use this option. In particular, you need to have an unlocked bootloader to install an additional OS.
  • You will need to pre-allocate some portion of your hard drive’s space for this OS.
  • You will need to restart your machine if you want to switch OSes.
  • Very occasionally, something may not work out of the box. One year this was wi-fi, which wasn’t fun.

Option 1: Virtual Machine Setup #

If you have macOS Big Sur, VirtualBox will likely not work. Use VMWare Fusion instead of VirtualBox, which has been reported to work.

To get started with the course virtual machine, head to the VirtualBox downloads page and download the “VirtualBox 6.1.18 platform packages” for your OS. Download the version for the OS you are currently running (which is likely Windows or OS X for most of you). Run the downloaded file to install VirtualBox on your system.

You wiill also need the VM image for this course, which you can get here. You are strongly recommended to use a fast, stable Internet connection (preferably a wired connection), as the file is quite large (5.2 GB).

Once you have this file, you need to import it into VirtualBox. Open the VirtualBox VM Manager and select File -> Import Appliance. When prompted, select the softsys-ubuntu2004.ova file you downloaded.

Once imported, you can start the VM and log in. The password for login is Under the C (exactly as written, including spaces). Once you’ve done this, you need to configure Git with your name and email. Head to the “Configure Git” section at the bottom to set this up.

Make sure you finish by following the two post-install steps below.

Option 2: WSL Setup #

First, you need to install WSL on your system. These steps will by default install Ubuntu 22.04, which will work for this course. If you want to install a different Linux distribution, feel free to find and install one from the Microsoft Store.

Install WSL and Ubuntu #

Follow Microsoft’s official WSL installation instructions to properly install WSL on your machine. You can stop once you have completed the “Prerequisites” and “Install” steps.

NOTE: If your machine does not meet the prerequisites in the linked page, the installation instructions shown WILL NOT WORK. Instead, you will need to use the manual WSL installation instructions linked at the end of the Prerequisites section. To be explicitly clear, your Windows version information should display something like this:

Windows version information display

If on your machine this window does not show that you are running Version 2004 or later and OS Build 19041 or higher, then you need to follow the manual installation instructions. If following the manual installation instructions, in Step 6 (Install your Linux distribution of choice), install the “Ubuntu” or “Ubuntu 22.04.1 LTS” app - do NOT install older versions.

Once you have installed Ubuntu, you should set it to be your default WSL distribution. Open PowerShell (instructions for doing so are in the installation instructions linked above) and run wsl -l -v. You should see a list that might look similar (but not necessarily identical) to this:

  NAME                   STATE           VERSION
* docker-desktop         Running         2
  Ubuntu                 Running         1
  docker-desktop-data    Running         2

If the asterisk (*) is not by Ubuntu, then run the command wsl --setdefault Ubuntu. (If the name shows up as something slightly different above, like Ubuntu22.04.1, then use that name in place of Ubuntu in the command.)

Launch and set up Ubuntu #

If everything has gone well, you should be able to select and launch the Ubuntu app from your Start menu. The first launch may take a bit of time to start up.

When you first launch Ubuntu, you will be prompted to create a new username and password, which is used to run administrative commands on Ubuntu. These do not have to match what you use for Windows, and can be whatever you’d like. Note that when you are entering your password, the text you enter will not be shown, but you will be asked for your password twice to avoid typos.

You may also see a firewall warning when first starting Ubuntu. Allowing connections with the default configuration (on private networks only) is fine.

Once you launch Ubuntu and see a text prompt, type the following command and press Enter:

sudo apt install gcc make git

You will be prompted for your password, but when you type, no text will be shown. This is for security purposes, and is normal.

Install and configure VS Code #

Go to the VS Code Download page and click the Windows button to download the installer. (By default, this will download the 64-bit User Installer whose link is just below the download button.) Run the installer, using all of the default options. Most importantly, make sure that “Add to PATH” remains checked. (You can uncheck “Launch Visual Studio Code” at the end of the install process, as you need to launch it from WSL in the next step anyway.)

Once you have installed VS Code, make sure Ubuntu is running, and in the command prompt, run code. The first time you run this command, it will do some setup on WSL, so it may take awhile.

Once it has started, you will need to install two extensions. Navigate to the extensions menu via File -> Preferences -> Extensions or by pressing Ctrl-Shift-X. Then search for and install the extensions “Remote - WSL” and “C/C++”, both from Microsoft. Once you have done this, you can close VS Code.

Finally, you need to tell Ubuntu to use VS Code as the default text editor for Git operations. Run the following command in Ubuntu:

git config --global core.editor "code --wait"

Make sure you finish by following the two post-install steps below.

Option 3: Dual-Boot Setup #

This method results in better performance on Ubuntu, but is more involved than above. For this method, you’ll need a spare USB drive with 4 GB or more of space that you don’t mind wiping and overwriting. You’ll also want enough spare hard disk space - for this course, 16 GB should be more than enough, but if you want to use Linux for anything else, you will likely want more free space.

Prepare an Ubuntu Installer USB #

Head to the Ubuntu download page and download the Ubuntu 22.04.1 LTS image. This is a reasonably large file, so a wired connection is recommended.

Once you have the image, you need to write it to the USB device. If you have a preferred way of doing this already, you can just use that. Otherwise, download balenaEtcher for your OS and install it.

After installation, start up balenaEtcher and choose “Flash from file”, selecting the image you downloaded (this should end in .iso). Then click on “Select target” and choose the USB drive you want to write to. Finally, click “Flash!” and wait for the application to write the image to the USB drive.

Allocate Space for Ubuntu #

You will need to make sure your hard drive has enough free space for the OS install. Again, for this course 16 GB should suffice, but if you want to use Linux for other things, you should consider allocating more space. You can resize your existing hard drive’s allocation of space to make sure that Ubuntu will have enough. In macOS, you can do this through Disk Utility by selecting Images -> Resize on your main image.

To do this in Windows, open the start menu and type diskmgmt.msc into the search box, then press Enter to start the Disk Management utility. Select the line with the largest amount of space (usually your C:\ drive), and select Action -> All Tasks -> Shrink Volume…, which will bring up a new window.

In this window, you can shrink your partition by some size, specified in MB. If allocating 16 GB, enter 16000 and proceed. Once the process is done, you should see the appropriate amount of “Unallocated Space.” It may be necessary to restart Windows to see this space.

Install Ubuntu #

Shut off your machine, and then insert the USB drive into a spare port. Start up your machine and press the appropriate key when you see your computer manufacturer’s logo (usually this key is Del or F12). This will bring up a “boot menu” from which you can select which device to boot your computer from. Select the USB drive you set up earlier.

This should bring up a graphical installer that you can go through to install Ubuntu on your machine. In this process, you should be able to see the partition of free space that you allocated earlier. Make sure you install Ubuntu there, or you risk overwriting existing data.

Once the installation process is complete, you can restart your machine, which should now give you the option of selecting which OS to boot into. To finish setting up your machine, select the Ubuntu 22.04 option using your arrow keys and Enter.

Set up Ubuntu #

While the VM we provide for the course has most things set up for you, the version of Ubuntu you installed here is a stock installation, and you need to install additional software yourself.

Open a Terminal from the start menu or by pressing Ctrl-Alt-T. Then type the following command and press Enter:

sudo apt install gcc make git

You will be prompted for your password, but when you type, no text will be shown. This is for security purposes, and is normal.

Once you have installed this software, you should install a text editor to write code in. The VMs for this course are preloaded with Atom, which you can download and install for free. If you are using Atom, run the following command in Terminal after installation:

git config --global core.editor "atom --wait"

This ensures that Git will use Atom as your editor for commit messages.

Make sure you finish by following the two post-install steps below.

Post-Install 1: Create a GitHub account #

In this course, we use a tool called Git, which is a system for managing versions of your code. To share your code with others, it’s helpful to use a hosting service that stores an online copy of your code and its history. (The copy does not necessarily have to be publicly accessible, though this is often the reason for hosting your code online.) For this purpose, we will use GitHub.

If you don’t already have a GitHub account, go to https://github.com and create an account. Feel free to use any email address you want (or create one just for this account), but remember which email address you use, as you will need it when configuring Git on your computer (which is a later step in this guide). Your username does not have to be related to your actual name at all. That being said, like most usernames, it will be publicly visible, so if you plan on sharing code with the world, make sure you choose a username that you would be comfortable with others seeing.

To test that you have correctly set up your GitHub account, go to https://github.com/username, replacing username with the username you created. You should see a profile page for your username. If you get a 404 page, you may not have completed the account creation process.

You may also want to check that you can log into your account.

Post-Install 2: Configure Git #

Regardless of which Linux option you use above, you need to set your name and email address so that GitHub can properly attribute your work to your account.

If you try to do other operations in Git without having set up your name and email, you will see a message that starts with something like *** Please tell me who you are. and whatever operation you were trying to do will fail.

To set your name in Git, run git config --global user.name "Alan Turing", substituting your name for Alan Turing (but leaving the quotes in place). This can be any name you want, though you should probably avoid using a name that may be seen an attempt to impersonate someone else (e.g., “Bill Gates”).

To set your email, run git config --global user.email "alan@turing.org", substituting your GitHub email address for alan@turing.org. It’s important that your email match the one that GitHub has, because a mismatch can make Git fail in unintuitive ways.

If you mistyped your name or email in the above steps, you can run the same command again with the correct name/email to fix the typo. If you mistyped user.name or user.email, you can use git config --unset user.naem (replacing user.naem with whatever you mistyped earlier) to remove that setting.

You can check that this process was successful by running git config --list. If you see lines starting with user.name, user.email with the values you expect, then the process was successful.