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. Limited support is also available for IntellijIDEA.

There is also special support for build systems like maven, leinigen, and gradle. See the related projects.

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 or Java 8 JDK.

You should know ...

• how to run the java command
• in particular, what the significance of the classpath is.

##Compile, run and document Frege programs

Preparations

Download the latest frege3.xx.vvv.jar from the releases page. It is most convenient to have that jar in the working directory when working on the command line, so in the following we assume that you made a copy or a link with the name fregec.jar.

Next, you may want to customize your command-line window so that it can deal with UTF-8 and can display unicode characters (on Windows, try: chcp 65001). All output from Frege programs will usually be UTF-8 encoded. Linux users should be fine as long as the command

echo $LANG

outputs something that cantains the string UTF-8. (If you don't understand this paragraph, carry on, but be prepared to see some funny glyphs in your terminal from time to time.)

We will need some directory where we store the compilation results. It is customary in the java world to name this build, classes or bin. We will refer to this directory as the target directory and call it build:

mkdir build

Finally, to check your installation make sure everything is in place and java, javac and the Frege compiler can be started. Here is a sample session:

$ tree
.
├── build
└── fregec.jar -> /home/ingo/Downloads/frege3.22.367-g2737683.jar
1 directory, 1 file
$ java -version
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)
$ javac -version
javac 1.7.0_51
$ java -jar fregec.jar -version
3.22.367-g2737683
$ echo $LANG
en_US.UTF-8

• Use your preferred editor to create some frege code.

• In the examples/ subdirectory of the source tree you also find some small programs to play with. In the follwoing, we will assume you choose to compile and run the examples/SimpleIO.fr program.

• Make sure the JDK7 or JDK8 java compiler is in the path: javac -version

• Make sure the JDK7 or JDK8 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 examples/SimpleIO.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 may or may not have to match the module name. However, irrespective of the source file name, when the module name is x.y.Z, the class file will go 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. This is a temporary file never used or looked at again by Frege, and will get overwritten on the next compiler run.

• The name of the class you want to run is the module name from your frege source. Check out the examples/SimpleIO.fr file and notice the line module examples.SimpleIO where near the top. So, what we need to run in this case is examples.SimpleIO: java -cp build:fregec.jar examples.SimpleIO
• This works the same way for any compiled frege module that has a main function.
• Windows users take care: upper/lowercase is significant in class names. And also, the separator for class-path elements is ; instead of :
• If your program contains QuickCheck properties, you can now check them: java -cp build:fregec.jar frege.tools.Quick 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

Where to go from here?

It depends a bit. If you are familiar with the JVM but don't know any language from the Haskell family you'll probably want to learn a bit Haskell. Yes, indeed! I promise that most of what you learn will work in Frege also and the rest with little modifications (we speak of the language, mind you, not of tools like cabal, hackage, and so on). Try it out, for example by going through LYAH, but using the Frege command line or online repl.

... to be continued ...