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. See below how to do that.

Legal Issues (License)

When you contribute to the compiler or the standard libraries (that is, the frege subproject), your code falls under the unconstrained Frege BSD 3-clause license. Code that contains comments saying otherwise cannot be accepted.

Contributions to other subprojects are subject to the rules outlined there.

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 9 (or higher) JDK. A JRE is not enough, since it doesn't include the internal Java compiler tool
• 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`
  

• Since Frege is self-hosting, you do need a frege compiler to compile the frege compiler. A ready-to-use fregec.jar is located on the project's releases page. Download the latest with

  `make fetch-fregec.jar`
  

  (This uses curl - if you don't have curl installed, you'll have to download manually.)

• check if the Makefile macros JAVAC and JAVA point to the correct executables. In particular, the JAVA macro must name a java command from a Java9 SDK, while the JAVAC must be a javac from at least a Java8 SDK. (The latter is only used to compile the few Java runtime source files we have, while running the Frege compiler with the java from JDK9 will ensure that Frege generated java code is compiled with a JDK 9 compiler: unfortunately, all JDK8 distributions I know have a bug in their compiler that raises a null pointer exception on compiling a certain generated file.)

• the TARGET macro specifies the minimum JVM version the compiler (and the code it produces) can run under. It is set to 1.8 currently. If you want a compiler that can produce code that can run with Java7, set it to 1.7. Whenever you change the TARGET, a make clean is strongly advised.

Run the following command to get a compiler that runs under Java 1.8 and higher:

make runtime compiler

The build will take about 5 minutes 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.)

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

This will

• compile the part of the standard library that is not used by the compiler itself
• compile the frege tools
• compile some modules that contain only quickcheck tests, and run the tests afterwards

Finally, to produce a slim jar that can be used with the eclipse plugin and the repl

make dist

It is of course possible to do this in one go. Here is how to create a distributable frege jar for use in Java 1.7:

make TARGET=1.7 clean runtime dist

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.

My dist artefact does not contain the REPL. How comes?

For this to work, you need to git clone the frege interpreter and the frege repl projects into sibling directories of your frege clone (that is, do the git clone from the same directory you were in when cloning the frege repository).

In addition, make a subdirectory lib in your frege project and copy a jline jar there (for example, from here or here).

That's all. Your next make dist should compile and add the REPL.

I get errors when make dist compiles the REPL

You probably use a JDK that does not contain JavaFX. You can't compile the REPL this way. You have two options:

1. get yourself a JDK that does contain JavaFX
2. build a JAR without REPL by moving frege-interpreter and/or frege-repl elsewhere so that they are not siblings of frege/

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:

• start with a fregec.jar from a previous build or with make fetch-fregec.jar
• update your workspace to the latest sources with git pull
• re-build the compiler with make fregec.jar

It can take just 1 commit to cause a build failure. We experience this situation often in nightly builds. Apologies for that.

If this happens to you, please post a message in the frege news group to obtain a bleeding-edge frege compiler jar.

Patches are always welcome.

Enjoy the Frege language!