6.106 Student Software

Welcome to 6.106! This document will direct you through how to get setup with a VM and all the software you will need to use during the class.

Part 1: VM Setup

The following section will guide you in setting up a local VM for running all course software. Recommended setup differs depending on your OS:

macOS

For Macbooks, we recommend creating and running an Ubuntu machine with OrbStack.

1. Download OrbStack by downloading from the site above or by running the following command.

   brew install orbstack
   

2. Turn on Rosetta translation (this will allow your binaries to run much faster if you are on Apple silicon).

   orb config set rosetta true
   

3. Create a Linux VM for the class by opening named 6106 as follows:

   orb create -a amd64 ubuntu:noble 6106
   

   You can also create VMs through the OrbStack desktop app.

   We require for this class that you run an AMD VM, not an ARM VM.

4. SSH into your VM by running:

   ssh orb
   

5. Within the Linux terminal, install git:

   sudo apt-get update
   sudo apt-get install git
   

OrbStack supports file sharing between Linux and macOS, so you may choose to develop entirely within your macOS directories if you find it convenient. Visit this link for more details.

You may also set up a remote VSCode connection from your Mac by downloading the Remote - SSH extension and connecting to host orb.

Windows

For Windows computers, we recommend running an Ubuntu distribution through Windows Subsystem for Linux (WSL).

1. Download WSL by running the following command:

   wsl --install --distribution Ubuntu-24.04
   

   If you have previously installed WSL, run the following command to update your VM to what we will be using in this class:

   wsl --set-default-version 2
   wsl --set-default Ubuntu-24.04
   

2. After installing, create a username and password as prompted.

3. Enter the WSL shell by running:

   wsl
   

The C: directory of your Windows machine is mapped to /mnt/c/.

Linux

If you are working on a Linux machine, most of the course software should be natively compatible. However, the setup scripts use the apt package manager to install packages, so if you are not using this package manager, it would likely be easiest to do this setup in a virtual machine, e.g. setting up a Docker container. Some tools used by this class also require a rather recent GLIBC version (2.32). If your GLIBC is not up to date, you should also consider using a Docker container. For an example of how to set up a development environment in a Docker container, see https://code.visualstudio.com/docs/devcontainers/containers.

Part 2: Configure Your 6.106 VM

Within your Linux machine,

Configure GitHub credentials

1. Check if an SSH key exists by running the following command.

   ls -al ~/.ssh
   

   If you find that ~/.ssh does not exist or that no key (id_ed25519.pub) exists, continue to step 2. Otherwise, skip to step 3.

   Note: For users who already have SSH credentials on their local computers, OrbStack forwards your SSH-Agent to the VM. In this case there is no need to create a new SSH key as it should already exist at ~/.ssh within the VM. Furthermore, if your local SSH key is already registered on GitHub, there is no need to add it a second time.

2. Create an SSH key

   ssh-keygen -t ed25519 -C "[email protected]"
   

   Press Enter to accept the default file location, and enter a passphrase when prompted (or leave it empty).

3. Copy the pub key from the terminal

   cat ~/.ssh/id_ed25519.pub
   

4. Navigate to Settings > SSH and GPG keys on GitHub and click New SSH Key. Paste the pub key into the Key field and Add SSH Key.

5. Verify your SSH connection

   ssh -T [email protected]
   

   You should see the following message

   Hi <user>! You've successfully authenticated, but GitHub does not provide shell access.
   

Install the 6.106 software

1. Clone this repo:

   git clone [email protected]:6106-fall24/student_software.git
   

2. Inside the same terminal, after cloning the repository, run:

   cd student_software
   ./install.sh
   

   Warning: the installation will take quite a while (around 40 minutes in testing) and may occasionally require you to enter your password.

3. After running the installation script, you will need to register your telerun credentials - run:

   authorize-telerun
   

   Enter your kerb as the username. To obtain your token, visit this site and authenticate with your MIT certificate. If you don't have an MIT certificate or have not renewed your certificate since last school year, please generate one using CertAid and reboot your computer. If the browser prompts you that the site is unsafe, just bypass the safety warning.

4. Configure your git identity:

   git config --global user.name "<your name>"
   git config --global user.email "<your github.com email>"
   

5. (Optional) Configure git to use your favorite editor. For example, to use vim:

   git config --global core.editor vim
   

6. Close your terminals and open a new one for some setup to be effective.

Part 3: Using the Software

Clang

Clang is the C compiler that we will use in this class. We provide a custom version of clang that is built with OpenCilk. If you want to compile some file through the command line or while writing Makefiles, you will want to use:

clang-6106

telerun

telerun is the program you will use to submit jobs to the class instances for reliable performance benchmarking. You will learn more about his during your first homework. You can use it by running:

telerun [binary]

Part 4: Test

Build the student_software test program

1. Start a new terminal in your VM or through a remote VSCode window.

2. Inside the Terminal, run (You can ignore warnings/messages printed by the LLVM Gold plugin during compilation):

   cd ~/student_software
   make
   ./test_program
   telerun ./test_program
   

   If everything worked correctly, you should see the following output.

   user@vm:~/student_software$ make
   clang-6106 -std=gnu11 -Wall -fopencilk  -O3 -DNDEBUG -ftree-vectorize -flto=full -march=native -Weverything -Werror -Wpedantic  -o fib.o -c fib.c
   clang-6106 -std=gnu11 -Wall -fopencilk  -O3 -DNDEBUG -ftree-vectorize -flto=full -march=native -Weverything -Werror -Wpedantic  -o sum.o -c sum.c
   clang-6106 -std=gnu11 -Wall -fopencilk  -O3 -DNDEBUG -ftree-vectorize -flto=full -march=native -Weverything -Werror -Wpedantic  -o main.o -c main.c
   clang-6106 -lrt -lm -fopencilk -flto -lXext -lX11  -o test_program fib.o sum.o main.o
   
   
   
   user@vm:~/student_software$ ./test_program
   Welcome to 6.106!
   
   
   user@vm:~/student_software$ telerun ./test_program
   
   Submitting Job: ./test_program
   Waiting for job to finish...
   ==== Standard Output ====
   Welcome to 6.106!
   
   
   ==== Standard Error ====
   

   If you did not see that, please let the staff know in a Piazza post, office hours, or recitation.