This repository contains the specifications for the three lab exercises for the Compilers module.
The three exercises are:
1 - Lexers and regular expressions (due Tue 07 Feb at 23:59).
2 - Parsers and ASTs (due Tue 21 Feb at 23:59).
3 - Code Generation (due Tue 07 Mar at 23:59).
[Note: the deadlines were extended by one week on 24 January for two reasons: (1) because the first lab was timetabled before the relevant lecture, which made it rather harder for students to make much progress, and (2) because of the delays caused by the UCU strike on 23 January.]
The primary purpose of the lab exercises is to ensure that everyone learns the basic skills needed for the coursework. They are not designed to be too challenging, but they do require you to get to grips with several tools and concepts that you will need later.
The three exercises are equally weighted, and are together worth 20% of your Compilers mark (and hence 10% of your overall IAC mark).
The exercises will be marked in a largely automated fashion. I will compile your code and run it against a collection of my own inputs. Please note that it is very important to test that your code compiles and runs correctly. Failure to do so could result a mark of zero for that exercise.
Feedback will be largely in terms of what doesn't work, if anything. I hope to provide feedback within ten working days. You are also encouraged to seek informal feedback on your code from the teaching assistants and from your peers.
The target environment for the labs (and the coursework) is Ubuntu 22.04. It is strongly suggested that you do your final testing before each submission in this environment, otherwise you are likely to hit incompatibility problems, which may mean your program won't build in my test environment. Those using Mac OS should watch out in particular, as the build environment is often subtly different.
If you want to work on your own machine, you can install a version of Ubuntu quite easily. For this, we recommend 3 options:
A guide to each of the installations is found below.
Requirements:
This repository contains a Dockerfile, which is a script that sets up a blank Ubuntu 22.04 environment, and then installs all the tools that the lab exercises require. If you configure your testing environment to match the Dockerfile script, you should be fine.
You can enter the virtual machine described by the Dockerfile by going to the directory that contains the Dockerfile and running the following series of commands. First, create the virtual machine "image" by running (in Terminal on Mac, or Powershell on Windows):
docker build -t "compilers_labs" .
(The . at the end is part of the command, by the way. It tells Docker to look in the current directory for the Dockerfile script.) Then create a "container" so that you can enter the virtual machine by running (in Terminal on Mac, or Powershell on Windows):
docker run --rm -it -v "${PWD}:/code" -w "/code" --name "compilers_labs_machine" compilers_labs
You are now in an Ubuntu 22.04 shell with all the required tools installed. (By the way, the -it flag instructs Docker to create a shell through which you can interact with the virtual machine. The -v "${PWD}:/code" and -w "/code" flags mean that your host machine's files are accessible to your virtual machine under the /code path in the Docker container.) Note that you should only work under the /code path as the rest of the container filesystem is temporary, meaning it is removed when you exit the Docker container.
When you're finished, you can leave the shell by typing:
exit
If you want to clean up, you can remove the container you created by typing:
docker ps -a
docker rm compilers_labs_machine
and then removing the image by typing:
docker images
docker rmi compilers_labs
If you are also using VS Code, and have the Dev Containers extension, you can develop directly inside the container by using the .devcontainer/devcontainer.json file. Make sure that this .devcontainer folder is in the same directory as your Dockerfile, then press View -> Command Palette in VS Code and search for >Dev Containers: Reopen in Container.
Requirements:
This repository contains a Vagrantfile, which is a script that sets up a blank Ubuntu environment, and then installs all the tools that the lab exercises require. To start a virtual machine (VM) using Vagrant, follow these steps.
-
Open a shell in this directory.
-
Run
vagrant upto download, install, and configure the VM. -
Run
vagrant sshto log into the VM. -
Run
cd /vagrant: This will put you in the same directory, with your host files shared with the VM.
You can then use command line build tools in the VM, while editing the source files in your host editor.
If you want to stop the machine,
-
Run
exitto exit the session, -
Run
vagrant haltto shut down the virtual machine.
If you later run vagrant up again, it will not need to download the VM from scratch.
Check which version of WSL you're using by running lsb_release -d and check that it's at least Ubuntu 22.04. Once you're on the correct version, simply ensure you have all the right packages installed by running:
sudo apt-get install -y lsb-release g++ gdb make dos2unix git bison flex qemu
From here you should be good to go!
A private repository has been created for you, which you can clone using the following command (but replace ${LOGIN} with your college login):
git clone https://github.com/LangProc/langproc-2022-lab-${LOGIN}.git
You will need to use a personal access token (PAT) to authenticate yourself. You can set up a token by following these instructions. Alternatively, you could clone the repository using SSH, having set up an SSH key by following these instructions.
You are free to include any files you wish in your repository, such as notes. However, try not check in compiled programs or large binary files. Repositories should contains the sources and instructions for binaries, but git does not deal well with binary files. Most repositories should contain a .gitignore file, which gives patterns for files that should not be committed. There is one included here which covers a few things, but feel free to add other temporary and binary files that your system might produce.
You are encouraged to commit (and push) to your repository regularly. This is for two reasons:
- If you lose your laptop, you only lose the work you have done since your last push.
- An independently verifiable history of commits allows you to make a strong case that you have not plagiarised your work.
Moreover, when it comes to working in pairs for the coursework, regular commits (and pushes) will help to reduce the severity of merge conflicts.
If there are any changes to the specification (e.g. bugs or updates), you can incorporate them into your version by pulling again from the specification repo. First you need to make sure it is included as a "remote":
git remote add spec https://github.com/LangProc/langproc-2022-lab.git
If you now list the remotes, you should see both "origin" (your private repo), and "spec" (the specification repo):
git remote -v
You can now integrate changes from the specification repo by pulling from it:
git pull spec main
If you have changed a file that also changed in the specification, then you may need to commit locally first. Look carefully at any incoming changes due to the pull, and make sure you want to accept them.
Submission of code is via your git repository. Make sure you have committed and pushed to GitHub all the files that your project needs. You are strongly encouraged to clone it into a different directory and then test again, just in case you are relying on something that wasn't committed.
Once your code is committed, note the commit hash of your current revision:
git log -1
This will produce something like:
ubuntu@ubuntu-xenial:/vagrant$ git log -1
commit 94d8419b20c78da86415bea7236d3719915977a3
Author: John Wickerson <j.wickerson@imperial.ac.uk>
Date: Mon Jan 07 14:26:40 2018 +0000
All tests passing.
The commit hash of this revision is 94d8419b20c78da86415bea7236d3719915977a3 which is a cryptographic hash over all the files in your repository, including the history of all the files. The hash produced on your local machine will also match the hash calculated by GitHub.
So take your hash (and just the hash), and submit it via Teams. Even if GitHub goes down, you can later on prove that the existence of your hash in Teams means you must have done the work associated with the hash. The hash in Teams will also be the exact revision of your repository that will get checked out of GitHub and tested. So you can carry on editing and modifying the repository, but only the commit with the hash submitted to Teams will be tested.
To summarise:
-
Test your code on your machine.
-
Commit your code to your local repo.
-
Note the commit hash (
git log -1). -
Push the code to GitHub.
-
Check that the commit hash in the GitHub website matches your local hash.
-
Strongly recommended: clone your code to a completely different directory, and test it again.
-
Submit the hash via Teams.
You can repeat this process as many times as you want, up until the deadline.
The exercises were devised by David Thomas (course lecturer until 2017-18), and are nowadays maintained by John Wickerson. Thanks to Yann Herklotz, James Nock, Simon Staal, and Shuyuan Liu for suggesting various improvements.