fregIDE Tutorial

This tutorial will walk you through the installation and initial project set-up.

##Introduction

The Eclipse plugin that supports Frege is called fregIDE. Don't ask how to pronounce that!

With the fregIDE, you can develop, build and run Frege programs. It supports the following:

• Enabling an existing java project to use the Frege Builder.
• Frege preferences
• Syntax/semantic coloring, including distinction between imported, top level and local names.
• Outline view
• Mouse over documentation (Mouse Over)
• Mouse over navigation (Mouse Over, Ctrl+CLick)
• Editor actions to support funny glyphs
• Live error markers in the editor
• Code completion (Ctrl+Space)
• Project build, i.e. compilation of Frege sources, takes dependencies into account.
• Compilation populates the problem view with errors, warnings and hints and the editor with persistent markers.
• Run programs through JDT Run Configurations. (Create a run configuration for a Java Application)

##Prerequisites

• JRE 1.7 (no JDK required) or higher
• Eclipse 3.7.2 (Indigo), 4.2, 4.3.2 (Kepler), 4.4.1 (Luna) Different versions may also work, listed ones are known to work.

The Frege programs developed in Eclipse will not depend on any Eclipse libraries. To run them apart from Eclipse, you'll still need Frege runtime classes. You can either use the ones that come with the Eclipse plugin (they will be in a file named fregec.jar located somewhere below the eclipse plugin directory) or download a binary compatible JAR from the Frege download page.

##Preparation

Eclipse should have the following minimum VM settings:

-Xmx512m -Xss4m -XX:MaxPermSize=128M

For more information on MaxPermSize see the Eclipse FAQ In newer versions, the eclipse.ini comes preconfigured with 256M, it is probably a good idea to leave it at that. And with Java8, this parameter is not needed anymore.

The stack space that is normally allocated by the JVM is not enough for serious work in a functional language like Frege. Hence, we require a substantial amount of stack space with -Xss from the JVM. 4 megabytes are abundand, and chosen so that source files with some ten thousand lines can be compiled.

The workspace should be configured to have all text files in UTF-8 encoding by default. The frege plugin currently does not support other encodings for frege source files. To compile frege files in different encodings, one needs to use the command line compiler with the -encoding option. However, as long as one restricts itself to ASCII, the encoding is of course immaterial.

##Installation

• Start up Eclipse.
• Open the preferences page Window -> Preferences, and go to the Install/Update section. Open the Available Software Sites page and Add... the Frege Update Site with Location http://www.frege-lang.org/fregide/. Close the preferences page. (This must be done upon first install of fregIDE only.)
• Open the installation page Help -> Install New Software
• From the drop down list near the top of the dialog window, select the Frege Update Site.
• Turn on the check box Contact all update sites during installation to find required software
• In the list box select the feature Frege IDE Support
• Click Next> to start the installation and confirm a few dialogs, license agreements and warnings because of unsigned content to complete it.
• When asked, restart Eclipse to activate the installed plugins.

##Update

An update is performed like an installation. Eclipse will recognize automatically that the plugin is updated. After Eclipse has completed and is restarted, the following must be done for each Frege Project:

• In the Project menu, make sure Build Automatically is turned off.
• In the Package Explorer, locate the old fregec.jar library shown under Referenced Libraries, right click and select menu item Build Path -> Remove from Build Path.
• Enable the Frege Builder again, this will add the new library to the project.
• Do a Clean Build to address compatibility issues. Afterwards you may turn on Build Automatically again.

##Usage

• Review the Preferences -> Frege page. Choose colors and fonts. If there is no Frege preferences page, your Eclipse instance most probably does not run with Java 1.7 or there were errors during installation of the Frege IDE.
• Create a Java project.
• From the context menu of the project, select Enable Frege Builder. This will add the fregec.jar to the Referenced Libraries of the project and enable the builder for Frege files.

Note that the order of Java and Frege builder is important for polyglot programming: If you have Java source code in the project that you are going to call from Frege, the Java builder should run first (this is the standard case). If, however, the java code calls into Frege, the build order should probaly be reversed. The build order can be changed in the project properties.

The fregec.jar that comes with the fregIDE can also be used from the commandline.

• Create a source file with extension .fr and begin editing. Please make sure you don't mix tabs and spaces.
• Code completion and content proposals (invoked normally by CTRL+Space) work the better the fewer errors are currently flagged. Please find the [details here] (https://github.com/Frege/eclipse-plugin/wiki/Content-Proposals).
• To run your program from within Eclipse, create a Run Configuration of type Java Application. The name of the main class is the module name you used in the Frege file where the main function you want to run is located. (For some mysterious reason, Eclipse cannot find this name, so you have to type it.) You may also need to give appropriate values for -Xmx and -Xss as VM arguments under the Arguments tab. Give the Run Configuration a meaningful name and run it from the Eclipse Run menu. Standard input and output will be done through the console view.

##Known Issues

Not yet implemented, but planned:

• more Editor Actions (maybe "Insert Type Signature(s)")
• QuickCheck support
• Interpreter ("scrapbook")

Not implemented, unsure whether we need it:

• text folding
• text formatting

Usage issues:

• When opening a Frege file, the plugin will type check the source code. This may take a few seconds, especially when Eclipse was just started up and the frege compiler code is not "warm" yet. Later on, you wont even notice.
• When you feel that the GUI is getting too slow, you probably have several thousand lines of source code in the editor window. Time to think about modularization!
• When editing module A that imports module B, changes in the source code of B will not be recognized until B is recompiled and the editor of A is refreshed by clicking the Refresh button in the task bar while A is active.