Using Geany (Compilers)
For the lab exercises, I've suggested that you use the simple editor/IDE called Geany that adapts well to many programming languages, including OCaml. You're (of course) free to use any other editor or programming environment you choose, although I suggest you choose one that integrates well with using Make to compile multi-file programs, and is able to parse compiler error messages in the standard unix format and take you to the relevant line of source.
To use Geany effectively on multi-file programs, it's best to set the program up as a Geany project, with rules and build settings specific to the project. I've provided a script to set up a project for each lab exercise, and to allow projects to be opened by double-clicking on the project file. A section towards the end of this article gives instructions for setting things up.
Editing and building
You should start Geany (after installing the project files) by double-clicking on the file in one of the lab directories: for example, to begin work on Lab one, find the file lab1/lab1.geany
in the file manager and double-click on it. The Geany window will open, with a list of files belonging to the project in the left-hand sidebar, and probably one or more files open in the editing area. You can double-click on other files in the list to open them for editing too, in multiple tabs.
When you have made the changes you want, you can compile and link the whole compiler by choosing the menu item Build>Make. This invokes Make on the project Makefile, and the commands that are run appear in a panel at the bottom of the window. If there are any errors, then the command Build>Next error lets you work through them, finding the line in your source code where the error was reported.
The projects are set up so that you can choose Build>Make test to run test cases for the compiler. The results are shown in a new window: you can scroll to see all of them, and press Return
to close the window when you are finished.
Version control
Geany has a plugin for version control that is installed for you. This provides a menu Tools>Version Control>... with several useful commands. Among them, you will find ...>Directory>Diff to show the changes made in the current directory, and ...>Commit to commit the changes you have made. You can either commit changes after completing each lab, or select the files to commit so as to separate your work for each lab exercise.
It's possible to select the changes shown after ...>Directory>Diff and paste them into a newly created file in order to save them. Alternatively, you could invoke hg diff
from the command line to capture the difference listing in a file – you don't have to use Geany for everything.
Setting up projects
I've provided a script that sets up Geany projects for each lab exercise. To invoke it, change to the compilers
directory and run the shell command
$ setup/install
It's not necessary to do this if you are not going to use Geany, because the files and settings it installs are specific to Geany and irrelevant to other editors. The setup script generates files named lab1/lab1.geany
, etc., in each lab directory. It also adjusts a few other settings to make Geany more suitable (in my opinion) for the kind of project we will be pursuing:
- Disable the option "Load files from last session". It's convenient for us to start Geany from a project file, which keeps its own set of open files.
- Disable the beep that plays when a build is finished. Builds will be fast enough for us that there's no need to go into the kitchen to make coffee while they work, and so no need for a beep to call us back.
- Enable the Project Organizer plugin that provides a list of project files in the left sidebar, and set the sidebar to display that list; also the GeanyVC plugin that provides simple version control actions, using Mercurial or Git as the back-end.
If you disagree with me about these settings, you can easily put them settings back.
After invoking setup/install
, you will be invited to log out and log back in again, so that the settings that were made have a chance to take effect: specifically, an association is added between project files and the Geany application, and logging in afresh forces this association to be noticed.
Geany project files contain absolute pathnames that work well if you keep them all in the same global directory, but less well if they live in scattered directories with the source code, as seems appropriate for us. This also makes it hard to store project files in a version control system meaningfully. My solution to this dilemma is to provide template project files (in directory setup
) and a shell script setup/genproj
that installs the templates in the directories lab1
to lab4
, filling in the appropriate pathnames. That script is invoked from setup/install
, but can be invoked again later to regenerate the project files if anything goes amiss.
Tabs and spaces
A particularly vexing issue when programs are edited with multiple tools at different times is the interpretation of tab characters. The issue arises because some programming environments like to interpret a tab as a single step of indentation for whatever programming language is in use (typically two spaces in the case of OCaml), and others make a tab count for a fixed eight spaces, and format the indentation of each line by using tabs as much as possible, then following them with a few spaces if needed. All this, combined with the fact that disk space is now ridiculously cheap, makes tabs in source code more trouble than they are worth. I've arranged for all tabs to be expanded in the lab materials as you receive them, so that they should look the same whatever editor you use. The settings for Geany installed in the project files should mean they continue to look reasonable when edited, on screen and in listings.
An additional irritant is the absurd syntax of Makefiles, where an initial tab on a line of text marks it as containing a shell command for building a file, rather than a rule saying what files depend on what others. This leading tab must be a tab, and not the equivalent number of spaces. Whatever editor you use, it's wise to be very careful when editing the Makefile for one of our lab exercises. Naturally enough, the general rule that files in the lab materials contain no tabs is relaxed for Makefiles.