Software setup

From Compilers
Jump to navigation Jump to search

For the practical assessment, you will need to check out sources using Mercurial or Git, to compile and run OCaml programs, and to assemble and run ARM code output by your compiler. For this, it is in practical terms necessary to use some kind of Unix environment, either with QEMU to emulate the ARM, or on a machine with a real ARM processor.

The sections of this page set out the viable options.

Install Linux on a PC

I use both Debian and Ubuntu. If you use either of them, or have another Debian-based distribution, then you can set up the software you need with these commands:

$ sudo apt-get install mercurial mercurial-git gcc tcl ocaml-nox
$ sudo apt-get install qemu-user gcc-arm-linux-gnueabihf

This installs:

  • Mercurial for version control, with the hg-git extension to access Git repositories.
  • GCC to compile the Keiko assembler and runtime system.
  • TCL, needed to generate the Kieko interpreter from an abstract description.
  • OCaml, needed to compile the compilers written in the course. (The -nox variant does not include the libraries needed for writing X Window applications in OCaml, which are irrelevant to the course.)
  • The user-mode parts of QEMU, needed to run ARM code output by the Lab 4 compiler.
  • The ARM version of GCC, needed to compile the startup and library code that goes with our compiler output. This brings with it the ARM assembler and linker. Gnueabihf denotes the calling convention used on the Raspberry Pi: it is the Gnu variant of the ARM Extended Application Binary Interface with Hardware Floating-point. There.

You will then have an environment that approximates closely the setup we have in the software lab. If you want to continue to use Mike's Pi server for testing, you will need a copy of the file /users/mike/pi/guest_rsa from the lab machines: it is a cryptographic key that will enable you to connect to the server using ssh. Put the file in the tools subdirectory after cloning the repository.

Install Linux under VirtualBox

You can make your own VirtualBox image on Windows or a Mac by following these steps.

  • Install VirtualBox.
  • Create a new machine for Linux / Ubuntu 64-bit. (32-bit will also work, but recent versions of Ubuntu are not published in a 32-bit version.)
  • Install a suitable Linux distribution: I suggest Xubuntu, a version of Ubuntu with a lightweight desktop, because full Ubuntu is a bit too demanding of the emulated graphics hardware to work well.
  • Install optional software as detailed above.

There's a page with detailed instructions and screenshots.

(I tried making a 'virtual appliance' that you just need to unpack and use, but the resulting file was too large to be downloaded conveniently, and there were too many variables – keyboard layout, VirtualBox versions, etc. – to make installing it any easier than the procedure above.)

Get a Raspberry Pi

This is perhaps the most satifying option, as you can run your compiler output on a real ARM chip; our compilers generate code using the ARMv6l instruction set that is compatible with all Pi's from the mark 1 onwards. On the other hand, I have always found QEMU to be a perfectly faithful simulation of the ARM for programs that work, though once or twice I have seen it run on and produce (nonsense) output where a real ARM would segfault.

You can plug the Pi into a keyboard and HDMI monitor, or do as I do and connect to it over the network with ssh. To install the needed software, you need just the command,

$ sudo apt-get install mercurial tcl ocaml-nox

If you like, you can read my notes on setting up a Raspberry Pi.

Use a Macintosh

The lab materials work well on a Mac with the help of MacPorts. You can set things up by following these steps:

  • Install MacPorts itself following the instructions at This involves installing Apple XCode and its command-line components, which will also be needed later.
  • Install the needed components with sudo port install mercurial ocaml.

You can now download and compile the lab software just as under Linux, and Labs 1, 2 and 3 will work perfectly.

It is possible to build the compiler for Lab4, but without the ARM version of GCC or QEMU installed, you will not be able to test locally the code output by the compiler. Options for testing the code include the following.

  • Use make test2 to test on my remote Raspberry Pi. To do this, you must first obtain the authentication key guest_rsa (see the relevant FAQ entry).
  • Use make test3 to test by connecting to the Software Lab machines. To do this remotely, you will need to connect to the Oxford VPN first, because the Lab machines don't allow SSH access from outside the Oxford network. If you forget to connect to the VPN, the symptom is that the process will just hang. It's also more convenient if you set up SSH access via an authentication key, because then you won't have to type your password each time you want to test.

In theory, versions of GCC for the ARM and QEMU exist for the Mac, but getting them to work and to work together may be more trouble than it's worth. If you do decide to try it, note that it is gcc-arm-linux-gnueabihf that you need, and not gcc-arm-none-eabi, which is designed for programming ARM-based microcontrollers on the bare metal (like the micro:bit that's used in the Digital Systems course).

Use Windows

Dominik Koller writes: In Windows 10, you can use the Linux Subsystem to run a shell and Linux software without installing a second operating system or virtual machine.

  • Follow these instructions to set up the Linux Subsystem.
  • Dominik suggests installing Ubuntu via the Microsoft Store
  • Your subsystem is now an App in Windows which you can run like a terminal.
  • In the subsystem, install optional software as detailed above.

Some notes for a Stanford course might also be helpful. [It would be good to have confirmation whether QEMU works for emulating the ARM hardware later in the course – Mike (talk)]

When editing files in Windows and compiling them with the tools we are building in the course, you need to make sure the files use Unix line endings (simple line feed, LF) instead of default Windows line endings (carriage return line feed, CRLF). You should change this in the text editor you are using in Windows.

It's possible to build the Oxford Oberon-2 Compiler (also written in OCaml, and also targetting Keiko) on earlier versions of Windows with the help of Cygwin, a Windows environment that simulates Unix without the kernel support Microsoft added in Windows 10. But the number of special tricks and workarounds needed to get this to work is formidable. Adding QEMU into the mix takes us beyond Advanced Spells and Potions into the territory of Defence Against the Dark Arts. All told, it's probably simpler just to go with VirtualBox.