Development Guide

Learning Objectives

The learning objectives for Development Guide are:

Using the tools needed for CS 341

Development in CS 341 #

In this course, we use Virtual Machines (VMs) for all our development. We will not support development in any other environment (e.g. EWS). We would like to stress that no matter what method you use to develop code for CS 341, test all your final code on your VM. The autograding environment is similar to your VM. Thus even though your code “works” on your machine, it may not work on the VMs and thus for the autograder.

Connecting to your VM

For all registered students in the course, you will receive a VM in the CS Department’s VM Farm provisioned by EngrIT. When your VM is provisioned you should receive an email about your VM. If you registered late, please email the CS 341 Admin (you can find the email on our staff page).

Approximately 12-24 hours aftering registering for the course your VM host name should also be on this page - so that’s another way to lookup your VM name.(VPN needed).

Once you have received your VM, you can connect to your VM via SSH. If you are not on the campus network you will need to install and use the campus VPN.

The VM number will be included in the email you received.

If you use VS Code, please follow this tutorial. Otherwise:

On Linux / Mac, you can do something like

$ ssh <NETID>@sp25-cs341-<NUM>.cs.illinois.edu

On Windows, you can use an SSH client like PuTTY.

Note that if you are not connected to on-campus internet, you will need to use a Virtual Private Network (VPN) to connect to your VM. Instructions on downloading and using the UIUC VPN can be found here.

An alternative to using the UIUC VPN is to SSH twice. You can first SSH into your EWS account and then into your personal VM. Just remember that this causes potentially double the network lag. If you are using the VS Code SSH client, setup your .ssh config like this:

Host 341-VM
  HostName sp25-cs341-<Your VM Number>.cs.illinois.edu
  User <NetID>
  ProxyCommand ssh ews -W %h:%p

Host ews
  HostName linux.ews.illinois.edu
  User <NetID>

If you want further information on what this is actually doing, you can read this tutorial on proxying.

Additionally, make sure your VM is on and running, which can be done at the VM dashboard. Use this page to lookup your VM name if needed.
Note: Both of the above links also require campus wifi or a VPN

Creating your course repository #

You will get the starter code for all the labs and MPs through Git and Github, and submit your solutions to be graded in the same way.

Click on the repository creator and follow the instructions to create your own CS 341 repository. This process will also add you to the illinois-cs-coursework organization and thus give you permission to our release repository.

Configuring Git

Once you are in your VM, you’ll need to set up some global defaults. The name and email you input here will be used to mark your commits.

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email NETID@example.com

Make sure to replace FIRST_NAME and LAST_NAME and NETID@example.com with your information. For example:

git config --global user.name "Lawrence Angrave"
git config --global user.email "angrave@illinois.edu"

Cloning your course repository

Checkout your repository as follows:

git clone https://github.com/illinois-cs-coursework/sp25_cs341_NETID.git

Unfortunately, cloning a repository is not so easy. If you follow git’s prompt and submit your username and password, you will likely see an error message like the following. If so, continue to the instructions in Authenticating with GitHub.

remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/illinois-cs-coursework/sp25_cs341_NETID.git'

Authenticating with GitHub

There are three ways that we recommend for authenticating with GitHub

Option 1: Using the GH Auth tool (Recommended)

gh is Github’s official command line interface. Almost anything you can do through the Github website, you can do through gh, and this includes authenticating your Git:

Run sudo apt update && sudo apt install gh on your VM to install gh.
Run gh auth login, choose Github.com for account type, HTTPS for protocol, and Y for authenticating Git, then follow its instruction to complete authentication.

You can learn more about what gh can do here.

Option 2: Using a Personal Access Token

You can think of a personal access token as a password with limited privileges and an expiration date. To create a token, go to Github settings, and click Generate new token (classic).

We recommend only giving your new token repo scope, as that is all you need to push and pull from your repos.

Once the token is generated (be sure to save it somewhere), you must further authorize the token with your NetID to access your CS 341 repos with it. See GitHub’s docs here.

Finally, you can run git clone again and use your newly generated token in place of your password. If you’re using VSCode, you may need to log out of Github in VSCode (Using Accounts button at bottom left) and log in again.

Option 3: Using SSH keys

Create an SSH key on your VM. Currently, we recommend the EdDSA key algorithm. You can create an EdDSA key with the command ssh-keygen -t ed25519 -a 100. This command generates a private and public key in the directory ~/.ssh, where ~ denotes your home directory. It will prompt you to enter a name for the file storing your private key, and will generate a .pub file for your public key. It’s not necessary to enter a password for the key.
Copy the public key to your clipboard. This is usually stored at a path like ~/.ssh/*.pub, where ~ denotes your home directory. You can print out the public key to the terminal with the cat command.
Log into your GitHub account, navigate to Settings->SSH Keys, and follow the prompts to add a new SSH key by pasting in the public key on your clipboard.

Please keep in mind that if you use this method, you will need to use SSH protocol URLs (e.g. git@github.com:<repo>) when you pull from / push to Github, not HTTPS protocol URLs (e.g. https://github.com/<repo>).

Fetching from `_release`

Change your directory into your repo folder:

cd sp25_cs341_NETID

You’ve probably noticed the repository is empty! In order to access the assignments, complete the following steps. This adds the _release repository as an extra remote, and this step must be completed every time you want to initialize your repository on a new machine.

git remote add release https://github.com/illinois-cs-coursework/sp25_cs341_.release.git
git pull release main --allow-unrelated-histories --no-rebase
git push origin main

Whenever you start an assignment, you will need to run git pull release main to retrieve the starter code for the assignment.

Install compiler and CS341 tools #

Your VM should already be provisioned with the required tools. This section is for reference in case you need to reinstall specific tools, e.g. in the case where your VM must be reset

Here is the script used to provision the VMs this semester:

# update sources and install basic tools
sudo apt-get update && \
    apt-get install -y \
      software-properties-common \
      wget \
      bzip2 && \
    add-apt-repository ppa:deadsnakes/ppa && \
    apt-get update

# install python3.6
sudo apt-get install -y python3.10 python3-pip python2-dev python3.10-dev cmake iproute2 && \
    rm /usr/bin/python3 && \
    ln -s python3.10 /usr/bin/python3 && \
    ln -s -f /usr/lib/x86_64-linux-gnu/libc.a /usr/lib/x86_64-linux-gnu/liblibc.a

# install bulid-related tools
sudo apt-get install -y \
        clang=1:14.0-55~exp2 \
        libncurses5-dev=6.3-2ubuntu0.1 \
        rpcbind=1.2.6-2build1 \
        git=1:2.34.1-1ubuntu1.10 \
        strace=5.16-0ubuntu3 && \
    rm -rf /var/lib/apt/lists/*

# install the latest version of valgrind
wget https://sourceware.org/pub/valgrind/valgrind-3.21.0.tar.bz2 && \
  echo "b8b89b327732c12191306c3d31cfd4b1 *./valgrind-3.21.0.tar.bz2" | md5sum -c - && \
  bunzip2 valgrind-3.21.0.tar.bz2 && \
  tar xf valgrind-3.21.0.tar
cd ./valgrind-3.21.0
./configure && \
  make && \
  make install
cd ..
rm -rf valgrind-3.21.0

# valgrind fix: install debug symbols for libc
sudo apt-get install -y libc6-dbg

Installing Other Stuff #

This is your VM! You can sudo and install whatever you want on it (given that it is school appropriate and compliant with VM Farm policies)

You can install vim or emacs. If you’ve ever wanted to become terminal-savvy, this is definitely the course to do it! If you don’t feel like learning a new language and want to stick to GUIs, you can also ssh into your machine and work on your code through VSCode, which is covered in greater detail in this guide.

If anything is unclear, either post on the course forums or ask your TAs/CAs/fellow students! Be careful about messing up your VM. If your VM ever gets into an unusable state, please make a private post in the course forums with your VM number, and we will try to resolve it.

You may find ssh-copy-id useful (A web search using Google/Duck Duck Go is useful). You can also configure MS Code and other GUI editors to work remotely. However some people still use ‘out of the box’ terminal-based editors like vi/vim that you can find (or install) on even the smallest of Linux distributions, and work even on low-bandwidth connections.

Have fun! In the worst case we can reset your VM back to its initial state.

If you can’t connect -

Not on the campus network? You will need to use the University VPN, Cisco AnyConnect
Check the status of your VM on the VSphere console and start/restart it if necessary. The VMs are shutdown daily at 5am, or perhaps you created a fork-bomb while working on the Shell MP. Additional Power on/reset instructions are at this IT page
Check EngrIT Annoucements and slow loading Status Page and the class forum

Still have VM issues? #

If you are sure that you follow the setup guidance correctly and you are on either the Campus VPN or the IllinoisNet WiFi but you still have VM issues (e.g. cannot access vc.cs.illinois.edu, cannot ssh into VM), then the fastest resolution will come from directly contacting EngrIT with your issue using their form. In the form, under the “Which lab(s) or remote resource(s) is your request about?”, you can type “CS VM Farm”.

You can contact IT by directly emailing cs-vmfarm-help@illinois.edu. This a bit faster than the known ‘standard’ emails, ews@illinois.edu, and engrit-help@illinois.edu because these last two need an extra manual step to get your request to the right support people.

Include as many details as possible (Course number, your VM hostname, time of error, type of error, and description of what you’ve tried.

Provisioning a local VM using Vagrant (optional) #

If you are taking the course remotely and have a slow internet connection when using the Campus VPN, you can set up a VM locally (on your own computer) using Vagrant. This page has instructions on how to do that.

Note: Your EngrIT-provisioned VM is still the authoritative place for final testing. Your local Vagrant VM is just a way to help remote students with development.