Install & Config Tools

There are a number of tools you’ll need installed on your computer to successfully write and test plan definitions. They are:

  • Terminal: Built-in; necessary to run the degree audit and testing tools
  • SourceTree: Connect with the repository storing all the existing plans; update it with your work.
  • Editor: Write the plan definitions
  • da-extract-transcript: Extract the transcript of an existing student for testing
  • degreeAudit: Perform the degree audit
  • da-run-tests: Run a large number of tests

This documentation covers several scenarios:

  1. Getting started with a provided virtual machine.
  2. Setting things up without a virtual machine.
  3. Creating a virtual machine for others to use.

The second and third are very similar and are really the second with notes added for the third.

At the current time we’re macOS only. Not because it won’t work on Windows or Linux but because we don’t have time to research and document more than macOS.

The images, below, are quite small. Click them for a larger version.

Using a provided virtual machine

  1. Prerequisites:
    • About this mac About this mac Ensure you have an Apple silicon Mac running Sequoia 15.5 or higher. Check the Apple menu (upper left corner of your screen) and choose “About This Mac…” to be sure. Look for “M1” or higher on the first line and “15.5” or higher on the last line.
    • You need to be able to install software. If your machine is locked down, talk to the administrator to either let you install software or to install VirtualBuddy (next step). Depending on how thoroughly it’s locked down, you may also need help moving the virtual machine into VirtualBuddy’s library.
  2. Go to https://github.com/insidegui/VirtualBuddy/releases/tag/2.0.1. Click the VirtualBuddy_v2.0.1...dmg link to download the program.
  3. Find it in the downloads folder and double-click. Drag VirtualBuddy.app to the Applications folder.
  4. Launch VirtualBuddy. It will likely display a window that says “Your Library is Empty”.
  5. Switch to Finder.
    1. Choose Go -> Go to Folder...
    2. Change the folder to /Users/USERID/Library where USERID is your home folder’s name. Hit the “Enter” key.
    3. Open Application Support and then VirtualBuddy.
    4. Copy the virtual machine image (provided by someone…) into the VirtualBuddy folder.
  6. Switching back to VirtualBuddy, the library window should no longer be empty. Double click the DegAudit tile. Then click the triangular “Play” button. You should be shown the login screen. Password is oat3.
  7. Continue with the steps in Common Stuff, below.

Setting up macOS

Set up the VM (if using)

  1. Open VirtualBuddy and click the + at the top-right corner. Select macOS Sequoia and then macOS 15.5.
  2. Name the machine degAudit.
  3. In the settings pane, reduce boot disk size to 42G.
  4. Create a folder on the host’s desktop named VirtualBuddyShared. In the VM settings, under Sharing select the folder you just created.
  5. Finish the initial machine setup. Set the “Full name”, account name, and password to “oat3”. Uncheck “Allow computer account password to be reset…”. Skip setting up an Apple Account.
  6. Remove the useless stuff from the Dock – everything but Finder, Safari, and maybe Settings.
  7. In Settings -> Wallpaper choose a non-descript colour (Space Gray?) or image so the VM can be easily differentiated from the host.
  8. The Finder should have a disk named Guest mounted. Open it and install VirtualBuddyGuest to enable some integrations with the host OS.

Safari (optional)

  1. Browse to the degree audit documentation. Bookmark it or set it as the default home page (Safari -> Settings... -> General -> Set to Current Page). Open new windows with the home page.

Terminal

  1. This should already be installed. Look in Applications and then Utilities. Drag the application’s icon to the dock so it’s easy to access later.
  2. Launch terminal. In Terminal -> Settings... -> Profiles
    1. Change Shell -> When the shell exits to “Close if the shell exited cleanly”.
    2. Change Window -> Window Size to 120 x 32.
    3. Close the settings window.

Create Directories and Environment Variables

Open terminal. Execute the following commands. Particularly for the longer ones, you may want to copy and paste.

  1. cd
  2. mkdir -p .oat/keys/public
  3. You’ll need to get a file named _degAudit.pkcs8 from one of the OAT developers. Put it in .oat/keys/private. If you’re setting up a VM, this is probably easiest to do via the shared folder. If you are doing this in a VM, be sure you trust the people you distribute the VM to!
  4. mkdir -p oat/bin
  5. mkdir oat/oat-plandefs
  6. echo "export OAT_HOME=/Users/oat3/oat" >> .zshenv
  7. echo "export PATH=$PATH:/Users/oat3/oat/bin" >> .zshenv
  8. echo "export DEGREE_AUDIT_PLANS=${OAT_HOME}/oat-plandefs" >> .zshenv
  9. source .zshenv
  10. curl https://cs.uwaterloo.ca/~cs-oat/bin/da-download-scripts --output oat/bin/da-download-scripts
  11. chmod u=rx oat/bin/*
  12. rehash
  13. da-download-scripts
  14. rehash

Java

All we need is the run-time, but I can’t find a way to get it installed on a Mac VM. So we install the whole JDK.

  1. https://download.oracle.com/java/21/latest/jdk-21_macos-aarch64_bin.dmg
  2. Find it in Downloads. Open it. Run the installer.
  3. Test your work so far. Go to the terminal and enter da-extract-transcript 20192274. It should show lots of lines, the last few of which are:
    "component_code" : "LEC",
    "course_grade" : "80",
    "grading_basis_code" : "NUM",
    "earn_credit" : true,
    "include_in_gpa" : true,
    "requirement_designation" : null,
    "student_take_units" : 0.5,
    "attempt_class" : "PASS"
  } ]
}

Editor (VS Code)

  1. Go to https://code.visualstudio.com. Click the “Download for macOS” button.
  2. When it’s finished, go to Downloads and drag it into the Applications folder.
  3. Find it in Applications and drag it to the dock for easy access later.
  4. Follow instructions to Launch VS Code from the command line. You’ll need to authorize a couple of actions.
  5. At some point you’ll see a dialog asking “Do you trust the authors of the files in this folder?”. Hopefully you can honestly click the button “Yes, I trust the authors”.
  6. You’ll also see a “Get started with VS Code” tab. Close it with the X in the tab that says “Welcome” at the top of the window.
  7. Install the “Compare Folders” extension. Go to “Code -> Settings -> Extensions” and search for “Compare Folders” in the marketplace. Install it. This is useful for comparing actual and expected output of tests and updating expected as necessary.

Python3

SourceTree requires python3. This approach gets it without installing all of the command-line tools.

  1. Visit https://www.python.org/downloads/macos/.
  2. Click the first “Download” link under “Stable Releases”.
  3. Find the package in Downloads; doubleclick to open and install.

SourceTree

This is the most complicated one… It’s connecting you to all of the plans that have already been defined and providing the means to add your work to it.

Download SourceTree

  1. Browse to https://www.sourcetreeapp.com. Click the “Download free” button. Click through several dialogs to download it.
  2. Open your downloads folder and move the application into your Applications folder. It does not have an installer.
  3. Find SourceTree in Applications and drag it to the dock.

If you’re preparing a VM, this is the place to stop – before configuring access to the repo with passwords and stuff. If you’re setting up a machine for yourself, continue on with Common Stuff.

Common Stuff

Configure SourceTree

Connect to GitLab

  1. Go to git.uwaterloo.ca and log in using your UW credentials. You should see “Welcome to GitLab, NAME”.
  2. An administrator (eg Byron) will need to add you to the project (Manage -> Members).
  3. After the administrator adds you, you will receive an invitation via email. Click the link. You will likely need to log into GitLab again. You should then see something like GitRepo GitRepo

Clone the Repository

  1. Wait until you’ve accepted the invitation to the GitLab project.
  2. Launch SourceTree.
  3. It will invite you to connect to BitBucket. Just click Continue.
  4. In Preferences, check “Set global author details” and fill in your name and email address. This is so we can see who made which changes in the plan definitions.
  5. In the following dialog, click “New…” and choose “Clone from URL”. connect connect
  6. A additional dialog will appear: connect connect
  7. Fill in:
    • Source URL: https://git.uwaterloo.ca/oat/oat-plandefs.git
    • Destination Path: /Users/oat3/oat/
    • Name: oat-plandefs
  8. connect connectA dialog box asking for authentication details will have popped up. Fill in your UW credentials. Note that it’s userid/username, NOT email address. Click OK and then Clone.
  9. history history After a brief delay, you should see a window titled “oat-plandefs”. Click the “History” tab on the left and see the entire history of the degree audit plan definitions!

Addenda

Documentation specifically for the first set of plan writers for while we were hashing this all out.

  1. Install the “Compare Files” extension in VS Code:
    1. Open VS Code. In the menus, select “Code -> Settings -> Extensions”.
    2. Search for “Compare Files”