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 already know ...

• how to run the java command in a command line window

Working with Frege at the command line

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 contains 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 (it is ok if the version numbers you see are greater than the ones shown here):

$ 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

Source Code

Use your preferred editor to create some frege code in a text file with the extension .fr. Or simply use one of the small example programs that can be found in the Frege project:

curl https://raw.githubusercontent.com/Frege/frege/release22/examples/SimpleIO.fr >SimpleIO.fr

Compilation

Let's compile this:

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

Some explanations are in order here:

• The -Xss1m protects us from stack overflows by telling the JVM to use more stack space than usual. The amount of 1 megabytes should be sufficient even for large source files.

• The target directory must be specified with the -d option. (It defaults to the current working directory.) Note that when you set up every project directory like explained above, you can make the following a shell alias that works in every project:

  alias fregec='java -Xss1m -jar fregec.jar -d build'

• 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 path of the source file may or may not 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 target directory.

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.

Run

Let us see what we have after compilation:

$ tree    ### windows users fire up explorer instead
.
├── build
│   └── examples
│       ├── SimpleIO$1$1.class
│       ├── SimpleIO$1.class
│       ├── SimpleIO$1Fprompt_17336$1.class
│       ├── SimpleIO$1Fprompt_17336.class
│       ├── SimpleIO.class
│       ├── SimpleIO$IJ.class
│       ├── SimpleIO$IJ$eofƒ5207be3f.class
│       ├── SimpleIO$IJ$_mainƒ52393afc.class
│       └── SimpleIO.java
├── fregec.jar -> /home/ingo/Downloads/frege3.22.367-g2737683.jar
└── SimpleIO.fr

As explained above, the output of the compiler depends on the module name, not on the file name. So, what is the module name then and where does it come from?

To see this, display the SimpleIO.fr file and notice the line

module examples.SimpleIO where

near the top. So, the module name is apparently examples.SimpleIO in this case.

Here is another way to find this out. We got a file named

build/examples/SimpleIO.java

(Mentally) remove the .java and the target directory build/, it remains:

examples/SimpleIO

Now replace all slashes (or backslashes) with ., and you're done!

Why should one even care about module names?

Because the name of the java class the Frege compiler produces will be the same as the module name. And we need to tell java which class to run. Hence, to run some Frege program, we need to know its module name.

Here we go:

$ java -Xss1m -cp build:fregec.jar examples.SimpleIO
Enter a number: 35
35 is odd.
Enter a number: 9999999999999999999999999999999999999998
9999999999999999999999999999999999999998 is even.
Enter a number: ^D Good bye. See you again.

This will work 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 :

Again, experienced LINUX users will notice that the following is a candidate for a shell alias:

alias frege='java -Xss1m -cp build:fregec.jar'

This alias will work like

frege my.mod.Name

in all project directories set up in the way explained, and it will run the named class/module.

What else can we do?

QuickCheck

Frege, like Haskell, has a property based test system known as QuickCheck. A property is some law or invariant you think should always hold, and you simply write it in the source code. Later, you can ask QuickCheck to test those properties with random input values.

To test the properties contained in a module, compile the module and then run the QuickCheck tool. Our example program contains a property that says that all integer numbers are either even or odd:

p_test = property $ \(n::Integer) -> odd n ^^ even n

We can test all properties defined in module examples.SimpleIO at once with

$ java -cp build:fregec.jar frege.tools.Quick -v examples.SimpleIO
examples.SimpleIO.p_test: +++ OK, passed 100 tests.
Properties passed: 1, failed: 0

This tells us that there was a property p_test that passed 100 tests.

Documentation

We can generate a documentation from any module, which will also include the texts you wrote in your documentation comments. Try it out with:

$ mkdir doc
$ java -cp build:fregec.jar frege.tools.Doc -d doc examples.SimpleIO
$ google-chrome doc/examples/SimpleIO.html 

Writing documentation comments is rewarding: not only do you make your machine generated documentation really useful. The documentation comments are also used by other tools, like the eclipse-plugin that shows the documentation for an item when you hover over its name. This works even in a source file that imported the module containing the documented item, and even if the source code isn't available, without any extra effort. All you have to do is to provide a bit of documentation along with your code.

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 yet 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).

As a suggestion, you could go through LYAH, but use the Frege command line or online interpreter for the exercises. Please see the wiki page that is dedicated to this topic.

If, OTOH, you are fluent in Haskell, be sure to make yourself familiar with the "JVM ecosystem" as far as you need it and check out the differences between Frege and Haskell.

In any case, feel welcome and we hope to hear from you in the chat room or the newsgroup, whose links you can find on the main page for the repository. Please don't hesitate to ask any questions!