Contributing to Frege

You can contribute to Frege in many ways as outlined on the home page.

For contributions to the core, you need to know how to compile the compiler.

Here is how to do that.

Prerequisites

• computer with plenty of memory available to user processes. For rebuilding the compiler, experience shows that you should give no less than 2G heap, unless you want to give the garbage collector a hard time.
• 50MB disk space for the unpacked downloads.
• a Java 7 or Java 8 JDK. A JRE is not enough, we need javac
• In addition, you need perl, make and berkeley yacc - look for byacc, pbyacc or byaccj.

Recompile the Compiler (Unix)

The compiler build environment, scripts, tools and the Makefile were originally running on Windows 7, but development shifted more and more to a more developer friendly OS, and at some point no effort was put anymore in keeping up Windows compatibility. However, if you manage to get the tools (nmake, perl, pbyacc, find, grep) it should be not too hard to adapt the Makefile - it is then mostly a matter of getting the path separator right.

Recompiling the compiler is only necessary if you are about to contribute to the compiler itself or the standard library. In this case, you are expected to make sure that you are able to re-compile the compiler and that a clean build will be possible after you changed something.

• get the source distribution with

  `git clone https://github.com/Frege/frege.git`
  

• cd to the checked out directory and make subdirectories build, dist and doc if not present already.

• Download the latest frege3.xx.vvv.jar and place it in the working directory under the name fregec.jar (Yes, Frege is self hosting, and so you need a frege compiler to compile the frege compiler ...)

• check if the Makefile macros JAVAC, YACC and JAVA point to the correct executables

• the Makefile macro JAVA defines the property -Dfrege.javac. You can specify here a different path for the java compiler that is to be called from the frege compiler. For example, suppose you need JDK 6 for your daily work, so that java and javac call the JDK 6 binaries. You could then rename or alias the JDK 7 binaries with java7 and javac7. In this case, settings could look like

    JAVAC=javac7
    JAVA=java7 "-Dfrege.javac=javac7 -J-Xmx512m"

or, better yet

  JAVA=java7 "-Dfrege.javac=internal -J-Xmx512m"

For this to work, the java7 command must be the one from the JDK. In the JRE, the internal java compiler is not available.

If you work with JDK7 or JDK8, the standard settings in the Makefile should be fine.

Run the following command:

make runtime compiler

The build will take a while and consists of the following main steps:

• compilation of the compiler sources and library sources needed in the compiler with fregec.jar
• compilation of the same with the compiler built in the first step
• compilation of the sources with the compiler built in the second step

(It is normal when the CPU utilization goes to 100% for a while even if you have many cores - the compiler will compile a bunch of source files in parallel.)

Please Note: Sometimes the internal java compiler throws the follwoing exception:

An exception has occurred in the compiler (1.8.0_40-internal). Please file a bug at the Java Developer Connection (http://java.sun.com/webapps/bugreport)  after checking the Bug Parade for duplicates. Include your program and the following diagnostic in your report.  Thank you.
java.lang.IllegalArgumentException 
    at java.nio.Buffer.position(Buffer.java:244)
    at com.sun.tools.javac.util.BaseFileManager.makeByteBuffer(BaseFileManager.java:306)

In that case, the build fails, of course. Usually, one can fix it by just repeating the make. I have filed a bug report in early March 2015, but guess what happened since then ... nothing. If you have a fix for this, please let us know!

The result will be a bunch of class files below the build directory. You can now run the compiler with

java -cp build frege.compiler.Main -version

To make a new fregec.jar from the fresh compiler, run

make fregec.jar

The 3 builds are necessary for the following reason: The first build uses the old compiler in fregec.jar to build a compiler that incorporates your changes. The second build uses the changed compiler and tries to build a second compiler. If this works, and the second compiler itself can successfully create the 3rd compiler and if that one produces the same code as the second one (for a test program, say, where you test the new features), then (and only then) it is reasonable to assume that you didn't break anything.

When recompiling doesn't work

Because the Frege compiler is self hosting, it cannot be guaranteed at all times that you can do the following:

• download fregec-3.x.y.jar
• checkout the latest sources
• compile the compiler

Unfortunately. (Sometimes even when the HEAD is just 1 commit ahead.) Sorry. This is also the reason why the nightly build is often broken.

If that happens to you, please post a message in the news group and we will happy to get you a bleeding edge compiler.