Skip to content

fregIDE Tutorial

Jump to bottom Edit New page
Ingo Wechsung edited this page Mar 12, 2018 · 15 revisions

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.8 (no JDK required) or higher
  • Eclipse 4.3.2 (Kepler), 4.4.1 (Luna), 4.5 (Mars), 4.5.1 (Mars.1), 4.7.2 (Oxygen.2) 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.

You should be able ...

  • to start up eclipse.
  • select the Java perspective
  • create a fresh Java project
  • create source files in the project

Preparation

eclipse.ini

Eclipse should have the following minimum VM settings:

-Xmx512m -Xss4m

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.

Here is the relevant section of my eclipse.ini (the last six lines):

-vmargs
-Dosgi.requiredJavaVersion=1.8
-Xss4m
-Xms400m
-Xmx2048m

For more help on configuring eclipse see the eclipse wiki. Note that the eclipse.ini settings are effective only on the next start of eclipse.

Workspace

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.

To check this setting, click Window in the main menu, then select Preferences in the sub-menu. Expand the General category, and select Workspace (the last sub-item, usually). Check the Text file encoding options in the lower left of the property sheet.

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/ (or, if that doesn't work https://raw.githubusercontent.com/Frege/frege.github.com/master/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.
  • In the list box expand the category Frege IDE Support and select the latest version of Frege Development Do not use items from any other category, unless advised otherwise.
  • 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

Update from an earlier version (<= 3.23.343)

Follow the migration guide.

First, try replacing the fregec.jar

Most of the time you want to spare yourself the hassle of plugin-upgrading, when all you want are the latest Frege language features, bug fixes, etc.

As there is little, if any, actual change in the plugin code itself anymore, you may get away with replacing the fregec.jar. For this, download the latest or build your own from HEAD, and copy it to

.../plugins/frege.ide_3.*/lib/

while eclipse is stopped and where ... denotes your eclipse installation directory. You may want to save the old one, in case something goes wrong. (To find out the exact path of the fregec.jar your eclipse plugin is using, look under Referenced Libraries in the Project Explorer.)

If the new fregec.jar is not compatible with the eclipse plugin, you'll get strange errors in the Error Log, there is no syntax highlighting, building the project is not working, etc. In this case, you may restore your previous fregec.jar, or go on with updating.

If that didn't work ....

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:

  • before the update 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.

This is needed because the link to fregec.jar under Referenced Libraries will still point to the previous fregec.jar. As of recently, the plugin checks for this and will flag errors so that you can't compile with a bad setup, which has led to numerous errors and confusion in the past.

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.8 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 (New 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.
  • When you save your file (Ctrl+S), it will get compiled (unless you have turned off Build Automatically for the project). Check the Problems view for errors, warnings and hints. Most of the time when you don't have red marks in the editor window before saving, the compilation will succeed.
  • 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:

  • QuickCheck support
  • Interpreter ("scrapbook")

Not implemented, unsure whether we need it:

  • text folding
  • text formatting

Usage issues:

  • When you get no syntax coloring, make sure in Windows -> Preferences -> General -> Editors -> File Associations that the file type .fr is associated with the "Impulse Editor". Close the editor tab and open it again.
  • 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.
  • Sometimes, it happens that some error markers persist even if you did correct everything. This is especially an issue with Build Path problems (i.e. wrong fregec.jar, etc.). If nothing else helps, open Navigator View, go to the output directory (most often bin/), refresh it and then delete everything beneath. Restart Eclipse and do a clean build.
Add a custom footer
Add a custom sidebar
Clone this wiki locally