Working on the compiler with Eclipse (and Frege plugin)

Preparations

First, fork the Frege/frege repo (or clone it and create a fresh branch to work on, if you have write access). Make a fregec.jar as outlined in the Contributing to frege wiki.

Install the plugin, as described in the tutorial.

Setting up the project

Make a new java project, and call it compiler, for example. The project directory does not have to be the forked/cloned frege repository! In fact, I assume in the following that you create your project in a separate directory, like ~/workspaces/compiler. Enable the frege builder for the compiler project. Then, from the main menu, select "Windows" -> "Preferences" and bring up the "Frege" preferences.

In the text field labeled "Prefix", enter the following:

compiler:my

The string before the semi-colon must be equal to the project name! This tells the compiler to prepend my to each module (that is: generated or imported java class) name that it encounters, but only in the compiler project.

This is necessary, because the build path has both the fregec.jar and the classes compiled within eclipse. One of them will be first. If it is the fregec.jar you'll never see the changes you've made in some module. OTOH, if the bin\ directory comes first, the compiler running on behalf of the plugin might take its classes from there, which may result in various JVM errors like "method blah-blah not found" (making it impossible to work).

After that, add a directory to the src/ directory, right click src/ in the project explorer, "New" -> "Folder" (not "Source Folder"!!!), in the dialog click "Advanced", check radio button "Link to alternate location" and browse to the frege/ directory within your fork. For example, if you forked/cloned into ~/repos, you want ~/repos/frege/frege

Now do the same for ~/repos/frege/tests

When automatic build is turned on, eclipse will now compile every .fr file it finds below the src/ folder. This is in and of itself of no value, but cannot be avoided. Later on, it is useful. For example, when your changes break something in modules that depend on the module you are changing, you'll get the corresponding errors in the error view when you save, as everything that depends on the changed module will be recompiled.

You can now make changes, browse the code, etc.

Several files in below the tests/ folder will have compilation errors. Don't care.

Tips for your workflow

Create some test code in tests/comp or tests/nocomp or both.

The former is for code that should compile with your changes, the latter for code that should not compile (anymore) with your changes.

Now implement the change you wanted. Once your compiler changes are type checking, go back to the command line, and do the following:

cd ~/repos/frege              # go to forked/cloned directory
java -jar fregec.jar -d build -O -make frege.compiler.Main   # make a compiler with your changes

This should only compile the modules that you changed, and the ones that depend on them. Once compilation is ok, you can do test compile your test modules:

java -cp build frege.compiler.Main tests/comp/Yourtest.fr    # compile your test cases

If you think you're done,

make fregec.jar

If this actually works, including the quickcheck tests that are invoked, commit your changes, push and create your pull request.

Promote source code changes to eclipse

Whenever you pull, or check out another branch, you might want to tell eclipse that the code has changed. To do that, right click the src/ folder in the project menu and select "Refresh". The builder will take care of the changes.

Module and File names

While the batch compiler doesn't care much about file names, the eclipse-plugin builder will go wrong if the module name does not match the source file path and base name. On case sensitive file systems, a module like foo.bar.Baz must live in a file whose path relative to the src/ directory is foo/bar/Baz.fr.

When the builder is out of luck

The builder is a bit sensitive with refactoring that include

• changing the module name/file name of a .fr file.
• moving a source file to another subdirectory, even if the module name was correctly adjusted

If you see error messages referring to modules that should not exist anymore, it is time to clean the project, which results in a full rebuild.

Also, the following happens sometimes when you start up eclipse and open an editor: There will be an error marker near the top, and the error message tells something like it couldn't find Int (or something like this). It seems like under mysterious circumstances eclipse just removes the classes below bin\ that start with the configured prefix. Again, this can only be repaired through cleaning the project.