Theme: auto

Setup (PC)

This is the setup guide for PC. If you’re using a Mac, go to those instructions instead!

System Requirements

In general, any PC made within the last few years will be perfectly fine for this course. Windows 11 is a little bit easier to setup, but Windows 10 should work, also. You will likely need around 10GB of free space because you will need to install WSL (Windows Subsystem for Linux).

Installing and Configuring WSL

From a Windows command prompt, run:
```
wsl --install
```
If you run the above command and it seems to just output some help text, this means you previously installed WSL. In this case, you can install the Ubuntu distribution by instead using:
```
wsl --install -d Ubuntu
```
If you get an error message about needing to enable virtualization on your machine, try these instructions.
The first time you run WSL it’ll ask you to make a user account. I advise either using using your normal Windows password or save the password in a password manager.

If you forget your WSL password, you will have no way to get back in. So you need to either use your Windows password or save it in a password manager.

Once you have the command prompt up and running in WSL, you will need to install several packages.

First, update apt-get:
```
sudo apt-get update
```

Next, install all of these packages:

sudo apt-get install cmake clang-14 g++ make flex libncurses5-dev gdb
sudo apt-get install zlib1g-dev ninja-build zip libzstd-dev libfl-dev

To simplify things, we will also add some symbolic links for clang and clang++. We also will change the default linker to ld.gold because it will link significantly faster. To do this:
```
cd /usr/bin
sudo ln -s clang-14 clang
sudo ln -s clang++-14 clang++
sudo rm ld
sudo ln -s ld.gold ld
```

If you change the default linker to gold, you will not be able to build and link a new Linux kernel anymore. But I’m pretty sure you can’t do that inside WSL anyway.

Building LLVM

For this class, you are going to work out of an itp439 directory from your home directory. Run the following commands:
```
cd ~
mkdir itp439
cd itp439
```

Download the source code for LLVM (we are using the relatively new 15.x branch, but not the bleeding edge 16.x):

curl -L -O https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.6/llvm-project-15.0.6.src.tar.xz

Extract the archive:
```
tar xJf llvm-project-15.0.6.src.tar.xz
```
Rename the extracted directory to just llvm-project:
```
mv llvm-project-15.0.6.src llvm-project
```
Enter the llvm-project directory:
```
cd llvm-project
```
Inside llvm-project, make a build directory and change to it:
```
mkdir build
cd build
```

Next, run CMake to configure LLVM with the following command:

CC=clang CXX=clang++ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=ON ../llvm

To build LLVM in parallel with Ninja, you need to know how many parallel jobs you want. The easiest way to figure out the number is to go to your Task Manager and on the CPU tab, look at the “Logical processors” number, and that’s the number you want. In my case, my desktop has 24 “Logical processors” so I went with 24. It’s likely the number you will want is significantly less than that, so you should change the number after the -j command to what you want. If you don’t build in parallel, it will take significantly longer to build.
Once you’ve figured out the number you want, run this command to build:
```
cmake --build . -j 24
```
The build will take 5-20 minutes depending on your system and value of -j, but you only have to build once the entire semester.

Git and GitHub

Here are the steps to getting setup on GitHub:

On the Windows side, install https://gitforwindows.org/
You need to accept the GitHub classroom assignment: https://classroom.github.com/a/3f2PzNBu
Select your USC email from the list. If you do not see your email address listed, that’s okay, just “skip” this step for now.
Once you accept the assignment, GitHub will create a repository for you with a URL like this: https://github.com/itp439-20231/uscc-YourUsername. It should automatically redirect you to your repository page once created.
Next, setup the Git Credential Manager so you will not have to type in a password and it will instead authenticate you with OAuth.
Return to terminal and your ~/itp439 directory:
```
cd ~/itp439
```
Clone your repo into a directory called uscc. The command will look something like this:
```
git clone https://github.com/itp439-20231/uscc-YourUserName.git uscc
```

Visual Studio Code Setup

Visual Studio Code has support for running natively on Windows actually building and running on WSL.

First, make sure your WSL command prompt is closed.
Download and install Visual Studio Code (https://code.visualstudio.com/). You need to install this from Windows, NOT WSL.
When prompted to Select Additional Tasks during installation, be sure that the Add to PATH option is checked so you can easily open a folder in WSL using the code command.
Once Visual Studio Code is installed, open it and install the Remote Development extension pack
Close Visual Studio Code
Now open a new WSL command prompt
Navigate to your uscc directory with:
```
cd ~/itp439/uscc
```
From this directory, you can launch Visual Studio Code with:
```
code .
```
The first time you do this, Visual Studio Code will download and install some additional components needed to work with WSL. Then Visual Studio Code will ask if you trust the author of the files in this folder. Make sure you check “Trust the authors of all files in the parent folder ‘itp439’” box and then click the Yes button.

To keep things simple, when working on the ITP 439 assignments you should always just launch Visual Studio Code from your WSL prompt. There are other ways to do it, but this is the easiest.

Now that Visual Studio Code has launched from WSL, you need to install some extensions for it to work properly with CMake and C++.

Go to View>Extensions and search for and install all of the following: VS Code will automatically figure out which extensions it needs to install on WSL and which it’ll install on Windows, you shouldn’t need to mess with it.
After installing the extensions, quit Visual Studio Code and relaunch it from WSL using code .

Working in Visual Studio Code

After relaunching Visual Studio Code it should detect that uscc is a CMake project, and it may ask you “Would you like to configure project ‘uscc’”. Say Yes. It will show you a dropdown like this:
Select the most recent Clang option you have (it should be Clang 14 in your case).
Next, click the Build button on the bottom toolbar. It should successfully finish.
Since we need to run with command-line arguments you CANNOT launch by using the play or bug button in the button toolbar. Instead, you need to select the “Run and Debug” option and click the green “Debug” button at the top:

This will launch with the command line arguments in the launch.json file, which initially are -a test002.usc. This tells uscc to to parse and generate the AST for the test002.usc test case.
If you’ve previously debugged in Visual Studio Code, you may hit a breakpoint with a call stack like this:

If you get this breakpoint, you should uncheck the “C++: on throw” option under the “BREAKPOINTS” dropdown and then continue past it.

You should see the following output in Visual Studio Code’s terminal:

test002.usc:16:1: error: Function implementation missing
{
^
1 Error(s)

Changing the Command Line Arguments

To change the command line arguments you launch the executable with, you need to edit the launch.json file’s args array:

launch.json args

This is the equivalent of launching the uscc executable from the command line with -a test002.usc.

Running the Unit Tests

Although you should do all your development and debugging through Visual Studio Code, to run the entire test suite you will need to run the Python scripts from the command line (you can use the terminal from inside Visual Studio Code to simplify things).

Make sure you have built the up-to-date executable in Visual Studio Code.
Navigate to the tests directory inside your uscc repo, so:
```
cd ~/itp439/uscc/tests
```
The test cases for PA1 are in testParse.py. Run this with:
```
python3 testParse.py
```
It will tell you that 22 test cases fail (since you haven’t implemented anything for PA1 yet!).

Running the Unit Tests on GitHub

For grading, we will not be downloading your code from GitHub and running it locally. Instead, I’ve setup GitHub Actions so you can manually run the unit tests. It will NOT automatically run on a push. It is your responsibility to manually run it when you think you are ready. When it’s time to submit the assignment, you will submit a link to the specific GitHub Action run you want us to grade, and that’s what we will grade.

To run the Unit Tests on GitHub, do the following:

Go to your repo.
Click on the “Actions” tab and then click on the “Unit Tests (Manual)” option on the left side of the page:
From the Unit Tests (Manual) action, on the right hand side of the screen there is a “Run workflow” button, click on that to reveal this dropdown:
From this you can select both the branch or tag you want to run the workflow on (keep it at the default for now), as well as a dropdown that lets you select which PA you want to run the tests for. For now, keep it on pa1 and click “Run workflow.”
You will get a notification that the workflow has started.
After a couple of seconds, when you refresh the page you’ll see the in-progress workflow. You can click on it to watch it as it goes, if you want to.
When the workflow job finishes, click on it to go to the summary page. If you scroll down a little bit, you will see a markdown-formatted summary that says how you did and lists out the FAIL/PASS result for each test case. For each test case that fails, there will be a dropdown that lets you view the failure info for why that test failed: In this case, everything will fail (because nothing’s been implemented yet).

It is your responsibility to make sure that your code compiles and passes the unit tests on GitHub Actions. Code that doesn’t compile will get a 0.