General Submission Instructions

The first assignment will come with some base code and examples to get you started, but you’ll be responsible for building most of your compiler, as well as the build setup and writing tests. You can arrange the code and repo more or less to your liking, but there are a few requirements for submissions.

• Everything must be built when you type make. Remember that your environment variables, shell aliases, etc. will not be available for other people, so be sure that your Makefile doesn’t rely on customizations in your .bashrc file. The same goes for installed programs, you should only use GCC, Flex, etc. as specified in the assignment pages.
• Running make must put an executable called bminor at the root of your repo. Each assignment page will specify what arguments are required to call it. Note that your compiler should support all previous modes, so e.g. the -scan flag should still work for the parser assignment.
• All your tests must be in the tests/student/ directory. Each assignment has its own subdirectory. As mentioned on the assignment pages, good*.bminor should exit successfully, while bad*.bminor should exit with failure.
• Do not commit compiled object files, generated C code/headers, etc. These should all be created fresh when you type make. Typing make clean in a freshly cloned repo should be a no-op. (Using .gitignore files is a good idea!)

GitHub Classroom

For this course, we’ll be using GitHub Classroom for the code assignments. If you’ve never used Git before, you might want to read about the core concepts. If you just want a quick tutorial on the main commands you’ll need, you should start here. There’s plenty more Git documentation online:

• The Git Book
• GitHub Guides
• Cheat Sheet for Common Operations
• Command Reference
• Online Simulator/Tutorial

You can also get help on the command line by typing git help or read the manual for a specific subcommand by typing e.g. git help commit.

For each assignment, you’ll have a Git repo hosted on GitHub. Feel free to use GitHub features like branches and issues as you like. You can keep work-in-progress code or other changes on separate branches. When it’s time to submit your assignment, push your code to the master branch of the assignment repo. After the deadline passes, you can continue to push commits to the repo if you want. Any such changes will not be graded.

Only the commit on the master branch when the assignment is due will be graded!

Each phase of the compiler (scanner, parser, etc.) will have its own assignment repo. The simplest approach is to clone each assignment repo and copy your previous code in. Alternatively, you could set up Git Remotes for all the assignments.

Make sure you push your code to the correct repo!

For example, don’t push your parser code to the scanner repo, it will not be graded.

Setting Up Your First Assignment

When starting each assignment, you’ll follow the same basic steps.

1. Click the instructor-provided invite link. If you don’t have a GitHub account you’ll be prompted to create one.
2. After signing in, accept the permissions for GitHub Classroom. You should only need to do this once.
3. Next, click Accept this assignment.
4. You’ll need to choose your ND user name from the list. You should only have to do this once. If you can’t find your ID or run into problems, just click Skip and contact the TA.
5. GitHub Classroom will set up your personal assignment repo. The landing page will give you a link to access it.
6. Finally, clone the repo.

Cloning Your First Assignment Repo

After setting up your assignment repo on the website, it’s time to clone it locally and start working. You can clone via either HTTPS or SSH. (If you don’t know what this means, use HTTPS.)

Rather than creating a separate repo for each assignment, we’ll use a single local repo with a remote for each assignment. This way, there’s no need to copy over previous work every time. Instead, you’ll simply push the same commits to each assignment repo and then add your new changes. Since we’ll be adding multiple remotes for the different assignments, you should use something other than the default remote name, origin. We’ll call the remote for the first assignment scanner. Subsequent assignments will each have a corresponding remote, e.g. parser, codegen, etc. When cloning the repo, make sure to specify the remote name to use.

git clone -o scanner https://github.com/dthain-courses/scanner-trshaffer.git

You’ll need to use your own assignment URL of course. At this point, you’re ready to start working. Use git add to stage your changes and then git commit to record the state of the repo. It’s recommended that you commit early and often so you can look at the history, roll back changes, and so on.

After you’ve made some commits locally, you can push your code to GitHub. The assignment repo works the same as a normal repo on GitHub. When it comes time to push your code, you’ll need to specify the branch and remote explicitly.

git push scanner master

You should visit the web page for this assignment repo to see your commits, just to be sure that everything is correctly pushed to GitHub. Keep pushing code as you work, and at the deadline the commit on the master branch on GitHub will be captured.

Submitting Subsequent Assignments

For each subsequent assignment, you’ll get another invite link which will create another assignment repo for you. There’s no need to clone each into a separate local repo. You’ll simply add all the assignment repos as remotes.

Git can tell you about a repo’s configured remotes.

$ git remote -v
scanner https://github.com/dthain-courses/scanner-trshaffer.git (fetch)
scanner https://github.com/dthain-courses/scanner-trshaffer.git (push)

Assuming you already followed the invite link and set up the repo for your parser, add it as a remote for the same repo.

git remote add parser https://github.com/dthain-courses/parser-trshaffer.git

You should now have an additional remote.

$ git remote -v
scanner https://github.com/dthain-courses/scanner-trshaffer.git (fetch)
scanner https://github.com/dthain-courses/scanner-trshaffer.git (push)
parser  https://github.com/dthain-courses/parser-trshaffer.git (fetch)
parser  https://github.com/dthain-courses/parser-trshaffer.git (push)

You can commit your work on the parser as usual, building on the same commit history as the previous assignment(s). When you’d like to push your code, simply specify which remote to use.

git push parser master

This should push your code to the assignment repo for the Parser assignment without changing the other repos on GitHub. Again, make sure you push to the correct repo for the assignment! You should check the repo web page on GitHub to be sure. Since you’re using the same local repo, there’s no need to manually copy code from assignment to assignment. This approach allows you to maintain a single history of commits for the entire development of your compiler.

Example Submission

Here’s an example command line session to clone a repo, add a file called bminor.c, commit, and push. Again, you’ll need to fill in your own user name and assignment, but this should get you started.

git clone -o scanner https://github.com/dthain-courses/scanner-trshaffer.git
# 1
git status     # 2
git add bminor.c
git commit -m 'Start on bminor.c'    # 3
git log    # 4
git push scanner master

1. Write changes to bminor.c from your favorite text editor.
2. Git will show you any changed files. we’ll assume you only want to commit bminor.c.
3. If you don’t specify -m, git will open a text editor and ask you for a commit message.
4. Git will show you the commit history of your repo. You should see the commit message from the previous step. As you make more commits, they’ll appear here.

At this point, your changes should be visible on your repo’s web page. Since this example didn’t involve multiple branches, everything is on the master branch. At the assignment deadline your submission will be the most recent git push, so this example would be enough to submit bminor.c for grading. You can commit and push as often as you’d like before the deadline.