Getting Started

This document gets you started with the command line version of the Frege compiler. If you prefer an IDE, you may want to read the wiki of the Eclipse plugin.

##Prerequisites

• computer with 256MB memory available to user processes. For compiling very large programs (like the yacc generated parser of the frege compiler, approx. 1800 functions on 40000 lines), 3 to 4 times more memory will be needed.
• 50MB disk space for the unpacked downloads.
• a Java 7 compatible JDK
• Compiler developers will need perl, make and berkeley yacc - look for byacc, pbyacc or byaccj.

##Compile, run and document Frege programs

• Download the latest frege3.xx.vvv.jar from the downloads tab, and rename it to fregec.jar
• Use your preferred editor. There is some support for Frege in UltraEdit and jEdit, see the examples/ source directory.
• In the examples/ subdirectory of the source tree you also find some small programs to play with.
• Customize your command-line window so that it can display unicode characters. (on Windows, try: chcp 65001)
• Make sure the JDK7 java compiler is in the path: javac -version
• Make sure the JDK7 java launcher is in the path: java -version
• Display usage page of the Frege compiler: java -jar fregec.jar -help
• Make a subdirectory to hold Frege generated classes: mkdir build
• Compile your program (the -Xss1m protects us from getting stack overflow exceptions and should be sufficient even for large source programs):

java -Xss1m -jar fregec.jar -d build test.fr

• Neither the source code file nor the fregec.jar have to reside in the current directory. Of course, if they don't, the compile command above must be adapted accordingly.
• Unlike in java, the source path does not have to match the module name. However, when the modul name is x.y.Z, the class file goes into build/x/y/Z.class, where build is the (already existing) directory specified with the -d option, which is the current directory by default. You'll also find the intermediate java file in build/x/y/Z.java, just in case you're interested to see really incomprehensible java code - please protect children and young programming adepts from looking at it.
• If your program contained a main function, you can now run it with the following command where Test is the package or module name. Under Linux, write : instead of ; to separate class path components:

java -cp build;fregec.jar Test

• Generate a documentation for your module or for any other module from the fregec.jar:

java -cp build;fregec.jar frege.tools.Doc Test

##Recompile the Compiler (Unix)

This is only necessary if you are about to contribute. 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
• 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 should look like

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

Run the following command:

make frege.mk && make -f frege.mk runtime compiler

The build will probably take no less than 30 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

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 -f frege.mk fregec.jar

The 3 builds are necessary for the following reason: The first build uses the old compiler to build a compiler that incorporates your changes. The second build uses the changed compiler and tries to build another 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.