NoteFollowing a national ballot, the union, UCU, that represents staff in the higher education sector has called a strike on three days in late November, and also "action short of a strike" during a period that starts on Wednesday, 23 November. During this period, colleagues are invited to take various actions, including abstaining from voluntary activities. I view the maintenance of Spivey's Corner as an activity I undertake voluntarily and not part of any contract of employment, and I cannot guarantee that it will remain accessible during the period of the dispute. In addition, some materials on the site may pertain to lectures that are cancelled by myself or others as part of the strike, and we are asked not to make them available online. Further details of the reasons for the strike and how it affects teaching in Oxford are on a brief FAQ page.
Git cheat sheet
This page contains everything you need to know to use the Git version control system for the labs in the Compilers course. Material for the labs is provided in a public, read-only Git repository.
- You will begin by cloning the repository into your home directory.
- Then you can work on the labs by editing the files locally.
- As you work, you may like to check in your changes to your local repository in order to keep track of what you've done.
- At any point, you can check the status of files you have changed, view a log of what you have checked in, and compare the state of your work with the checked-in version or with original code provided for the lab.
- If there are bug fixes or additions to the lab materials during the course, you can get them by pulling and merging changes from the public repository.
One element of a typical workflow is missing in the lab setup: because each person is doing the exercises independently, we omit the step where you push your changes back to the public repository.
The minimum you will need to do is clone the public repository to begin the labs, and produce some diff listings as a part of your report on the assignment. Anything more is entirely optional.
The lab materials are provided in a Git repository on Mike's college computer, the same machine that hosts Spivey's Corner. To begin the labs, you should issue the command,
$ git clone http://spivey.oriel.ox.ac.uk/git/compilers.git
This will create a directory named
compilers with subdirectories corresponding to the Keiko virtual machine and to the four lab exercises, among others, all containing the files that make up the lab materials.
Like all commands that interact with Git, this one begins with
git – the chemical symbol for Linus – and then the name of the specific operation that is needed, in this case
The clone command given above depends on Mike's computer being available, and that will not be true forever. As an alternative, you can clone a Git repository maintained in the Computer Science department:
$ git clone https://gitlab.cs.ox.ac.uk/mike/compilers.git
Your next act, as suggested in the lab manual, will be to change to the subdirectory
compilers/keiko and build the software that supports the virtual machine:
$ cd compilers/keiko $ make
compilers created by the
clone command contains the subdirectories you can see, plus one hidden subdirectory
compilers/.git; it is in this subdirectory that Mercurial keeps a complete copy of the repository that you cloned, together with any changes or additions you make.
After you have done some editing, the command
$ git status
lists the files in your current directory that do not agree with the latest state of the repository. The output might look like this:
On branch master Your branch is up to date with 'origin/master'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: kgen.ml Untracked files: (use "git add <file>..." to include in what will be committed) inicheck.ml no changes added to commit (use "git add" and/or "git commit -a")
This means that the file
kgen.ml has been modifed since the last check-in, and there is a file
inicheck.ml that Git knows nothing about. If there are no changes since the most recent check-in, then
hg st produces no output.
git status shows modified or new files in the current directory, then we can record these changes in the repository. It's first necessary to record the changed files in the "staging area" by giving the command
$ git add .
This will record both the changed files and the new ones so that they are committed in the next step. After this command, using
git status will show the files as changes to be committed.
The files are actually committed with the command
$ git commit -m "log message"
log message represents a brief comment you should write, describing the changes you are checking in. Larger projects typically have conventions that demand longer and more explicit comments with every check-in; then it is more convenient to omit the comment from the command line, and have Git start an editor for you to type as long a comment as is needed. But, for us, a few words on the command line are sufficient.
It's a good idea to check in the main part of each lab exercise before starting on the next one, and to check in again when you have finished everything for an exercise. At that point, you can pull and merge any updates that have been made to the lab materials (see below).
Git records your name next to each change you check in, and that means the
git commit command needs to know it. You need to create a file in your home directory called
.gitconfig and in it put the following text:
[user] name = Fred Bloggs email = firstname.lastname@example.org
(substituting, of course, your real name and e-mail address for the strings
Fred Bloggs and
email@example.com). After you've created this file, the unix command
ls will not show it, because of the long-standing unix convention that files with names starting with a dot are not listed. But the file does exist, and you can see it listed, together with no doubt 1001 other such hidden files, by giving the command
$ git log
will show a list of checked-in revisions, starting with the lab materials as you inherited them and showing also any revisions you have checked in.
hg diff command can be used to compare any two revisions of your project or some of its files. The simplest use is the command
$ git diff .
This compares the current directory in the working copy with the latest check-in. Example output:
diff --git a/lab2/kgen.ml b/lab2/kgen.ml index f4efc9a..b55be31 100644 --- a/lab2/kgen.ml +++ b/lab2/kgen.ml @@ -69,9 +69,9 @@ let rec gen_stmt = SEQ [CONST 0; GLOBAL "lib.newline"; PCALL 0] | IfStmt (test, thenpt, elsept) -> let lab1 = label () and lab2 = label () and lab3 = label () in - SEQ [gen_cond test lab1 lab2; - LABEL lab1; gen_stmt thenpt; JUMP lab3; - LABEL lab2; gen_stmt elsept; LABEL lab3] + SEQ [gen_cond test lab2 lab1; + LABEL lab1; gen_stmt elsept; JUMP lab3; + LABEL lab2; gen_stmt thenpt; LABEL lab3] | WhileStmt (test, body) -> let lab1 = label () and lab2 = label () and lab3 = label () in SEQ [JUMP lab2; LABEL lab1; gen_stmt body;
(The lines marked
- have been removed and replaced by those marked
Also useful in the labs is the command
$ git diff -r origin/basis .
This compares the working copy with the original source code, bookmarked as
origin/basis, showing exactly the changes you have made. The bookmark
origin/basis is always updated to point to the unmodified source without your changes, even if you have merged in changes to the lab materials after starting work on a lab.
Pulling and merging changes
If we need to fix bugs in the lab materials during term, or to add more example programs, then the changes will be added to the public repository for you to pull in and merge with your own changes. If the need arises, we'll help you with the process, and fill in some basic instructions here.