From 28020fdf80f30604f511d0686f5ec929b24dd9d9 Mon Sep 17 00:00:00 2001 From: "john.j.camilleri" Date: Fri, 11 Jan 2013 10:18:13 +0000 Subject: [PATCH] GFEP: update readme for 1.5.2 release --- eclipse/index.html | 121 +++++++++++++++++++++++++++++++-------------- 1 file changed, 84 insertions(+), 37 deletions(-) diff --git a/eclipse/index.html b/eclipse/index.html index 1cf1240d5..500525c50 100644 --- a/eclipse/index.html +++ b/eclipse/index.html @@ -10,13 +10,13 @@

The GF Eclipse Plugin

-

John J. Camilleri
Updated: 10 January 2013

+

John J. Camilleri
Updated: 11 January 2013

The research leading to these results has received funding from the European Union's Seventh Framework Programme (FP7/2007-2013) under grant agreement no. FP7-ICT-247914 (the MOLTO Project).

Introduction

The aim behind developing a desktop IDE for GF is to provide more powerful tools than may be possible and/or practical in a web-based environment (the GF Web IDE). In particular, the ability to resolve identifier cross-references and browse external libraries quickly during development time is one of the primary motivations for the project.

The choice was made to develop this desktop IDE as a plugin for the Eclipse Platform as it emerged as the most popular choice among the GF developer community. Support for the platform is vast and many tools for adapting Eclipse to domain-specific languages already exist. Unlike the zero-click Web IDE approach, using the GF Eclipse plugin requires some manual installation and configuration on the development machine.

License

-

The GF Eclipse Plugin is open-source under the GNU General Public License (GPL).
The licenses that cover the rest of GF are listed here.
Note that Xtext and Eclipse are released under the Eclipse Public License (EPL).

+

The GF Eclipse Plugin is open-source under the GNU General Public License (GPL).
The licenses that cover the rest of GF are listed here. Xtext and Eclipse are released under the Eclipse Public License (EPL).

Release history

-

10/01/13 : (1.5.2.x) New option for specifying build files.

+

11/01/13 : (1.5.2.x) New option for specifying build files.

12/06/12 : (1.5.1.x) Support for scoping when library sources not available. Performance and implementational improvements to External Library View.

19/04/12 : (1.5.0.x) Removed need for .gfexternal folder. Much improved "External Libraries" view allows you to search in current scope. Memory usage improvements in scoping implementation. Validation now occurs on file open. Re-added GF Library Path field in preferences.

04/04/12 : (1.4.3.x) Improvements to the Test Manager. Added support for arbitrary commands in launch. Made the license information clearer.

@@ -106,7 +106,7 @@
  • You can also adjust the verbosity level of the GFEP console log in the preferences window.
    • -Plugin preferences window

    Plugin preferences window

    +Plugin preferences window

    Plugin preferences window

    Updating the plugin

      @@ -139,8 +139,9 @@

      Specifying build files (guided build)

      As of GFEP ≥ 1.5.2, you are now able to explicitly which modules in your GF project should be built by the builder. This would normally contain your "top-level" modules. This can be done right-clicking on your project in the Project Explorer and choosing Properties → GF Build Settings. From here you simply tick which modules in your project the GF builder should compile:

      -Project-specific build settings

      Project-specific build settings

      +Project-specific build settings

      Project-specific build settings

      +

      When doing this, GFEP will never attempt to compile any other files in the project. Whenever you add a new top-level module or change your module hierarchy, be sure to check these build settings again.

      Getting started

      @@ -175,33 +176,33 @@

      These can be removed manually at any time, as they will always be regenerated as necessary. You will probably want to ignore these directories in your version control system.

      Create a new GF Project

      If you have a folder in your workspace which you want to convert into a GF Project, then you can select it from the drop-down. This folder will then appear as an Eclipse project in your workspace.

      -

      New project wizard New project wizard

      +

      New project wizard New project wizard

      New module wizard

      Use the GF Module wizard from File → New → Other → GF Module:

      -New module wizard

      New module wizard

      +New module wizard

      New module wizard

      You can find some small examples here. Download the files and manually add them to your Eclipse workspace to experiment with some of the plugin features.

      Clone module wizard

      If you want to clone an existing module into a new language, you can now do so via the Clone GF Module wizard. This is also available as a context menu option in the Project Explorer, via <Right click> → Grammatical Framework → Compile for new language:

      -Clone GF module to new language wizard

      Clone GF module to new language wizard

      +Clone GF module to new language wizard

      Clone GF module to new language wizard

      This will create and open a new module with the relevant replacements made. Note how in this case string constants are replaced by the empty string "". This wizard currently only works on concrete and instance modules.

      -Newly cloned file

      Newly cloned file

      +Newly cloned file

      Newly cloned file

      Workbench editor layout

      Use Eclipse' own features to drag and drop your editor tabs to suit your needs.

      -The editor and outline view

      The editor and outline view

      +The editor and outline view

      The editor and outline view

      Outline view

      The Outline view in the bottom-left offers a quite overview of your module structure. Clicking any of the terms will make your cursor jump to that point in the file.

      Cross-referencing errors and warnings

      Notice how changing a cat definition for example will produce warnings and/or errors in other the modules.

      -Warnings and errors in the editor

      Warnings and errors in the editor

      +Warnings and errors in the editor

      Warnings and errors in the editor

      Validation

      The in-editor validation sometimes needs to be triggered/updated by a keystroke. If you can still see errors which you believe should be correct, try adding a space character to ensure the validation is re-triggered.

      @@ -210,20 +211,20 @@

      For validation to work correctly, the project's Build Automatically option should be turned on. Each time you save a file (or some other change occurs in your project), the builder should get triggered which re-compiles any GF files which have changed. If the builder does not seem to get triggered, try to run a clean via Project → Clean...

      Code formatting

      Use the built-in code formatter to tidy your code automatically. Right-click in the editor and choose Format or use the keyboard shortcut Ctrl+Shift+F.

      -

      Before auto-formatting After auto-formatting

      +

      Before auto-formatting After auto-formatting

      Syntax highlighting

      -

      You can change your syntax colouring styles as you wish from Preferences → Grammatical Framework → Syntax Coloring

      +

      You can change your syntax colouring styles as you wish from Preferences → Grammatical Framework → Syntax Colouring

      -Syntax highlighting styles

      Syntax highlighting styles

      +Syntax highlighting styles

      Syntax highlighting styles

      Launch configurations

      Set up a launch configuration from Run → Run Configurations... → Grammatical Framework. You will see the dialog below with some fields automatically filled in for you.

      -Launch configuration dialog

      Launch configuration dialog

      +Launch configuration dialog

      Launch configuration dialog

      Run the launch config and you will see the output from the GF compiler in the console view within Eclipse.

      -Output from the GF compiler

      Output from the GF compiler

      +Output from the GF compiler

      Output from the GF compiler

      Run As... launch shortcut

      Using the Run → Run As → Compile with GF shortcut will take the current selection or active editor and do one of two things:

      @@ -236,18 +237,18 @@

      Additionally, every time a grammar is Run a new console is opened to display the output. This console may also serve as the interactive GF Shell, depending on the Interactive Mode checkbox in your Run Configuration.

      Eclipse does not make it obvious when multiple console windows open; click on the Display Selected Console button to switch between open consoles:

      -Display Selected Console icon

      Display Selected Console icon

      +Display Selected Console icon

      Display Selected Console icon

      If the process associated with a console window has terminated, it will be indicated in the upper-left corner as below. Such console windows can then be closed using the grey cross button:

      -Close terminated console icon

      Close terminated console icon

      +Close terminated console icon

      Close terminated console icon

      The Eclipse console implementation does not support command history (up arrow) or auto-completion (tab).

      External Libraries view

      This view is automatically populated with a list of all the external modules referenced by the current file. Double-clicking on any item provides a quick way of opening GF files which are imported into your grammar from outside your Eclipse project, for example the GF Resource Grammar Library.

      This view also provides a text box for searching within the current module's scope, as shown in the image below. Clicking the small arrow on the right-hand side of the view provides options for case sensitive and/or regular-expression based search.

      -External libraries view

      External libraries view

      +External libraries view

      External libraries view

      Test Manager view

      This feature works together with the launch configurations to make the process of running regression tests on your grammars quick and easy. As described in the GF Book (Section 10.5), the general development-test cycle (independent of GFEP) is as follows:

      @@ -259,12 +260,31 @@

    The Test Manager view follows this same pattern but provides a convenient graphical interface for running your test cases and also for looking at the output, just using a few clicks:

    -Test Manager view

    Test Manager view

    +Test Manager view

    Test Manager view

    Note that GFEP assumes the following convention:

    -

    *.trees or *.sentences : Test input files: trees file (for testing linearisation) and sentences file (for testing parsing)

    -

    *.trees.out or *.sentences.out : Corresponding output files (generated each time a test is run)

    -

    *.trees.gold or *.sentences.gold : Corresponding gold standard files (manually corrected from an output file)

    + + + + + + + + + + + + + + + + + + + + + +
    ExtensionDescription
    *.trees or *.sentencesTest input files: trees file (for testing linearisation) and sentences file (for testing parsing)
    *.trees.out or *.sentences.outCorresponding output files (generated each time a test is run)
    *.trees.gold or *.sentences.goldCorresponding gold standard files (manually corrected from an output file)

    Logs

    The GFEP writes to the Eclipse platform log. This can be accessed in two ways:

      @@ -301,13 +321,40 @@

      In both cases make sure you get the correct version of Xtext (see below). Once you have Xtext set up, you can clone the repository locally with the following command:

      git clone git://github.com/GrammaticalFramework/gf-eclipse-plugin.git

      You can then add the projects under the workspace directory to your Eclipse workspace, by using the File → Import... wizard. The individual projects are:

      -

      org.grammaticalframework.eclipse : Main plugin which covers all parsing and linking behaviour.

      -

      org.grammaticalframework.eclipse.ui : Covers all UI aspects of the plugin. Depends on org.grammaticalframework.eclipse (but the opposite is not true).

      -

      org.grammaticalframework.eclipse.tests : Contains unit tests for the plugin. Not required for running the plugin.

      -

      org.grammaticalframework.eclipse.ontology-grammar : GF Ontology Grammar Plugin for Eclipse, developed separately by Ontotext AD.

      -

      org.grammaticalframework.feature : Feature project for the GF Eclipse Plugin. Exports org.grammaticalframework.eclipse and org.grammaticalframework.eclipse.ui.

      -

      org.grammaticalframework.feature.ontology-grammar : Feature project for the GF Ontology Grammar Plugin. Exports org.grammaticalframework.eclipse.ontology-grammar.

      -

      org.grammaticalframework.updatesite : Update site project which exports both feature projects under the same category.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      NamespaceDescription
      org.grammaticalframework.eclipse.uiCovers all UI aspects of the plugin. Depends on org.grammaticalframework.eclipse (but the opposite is not true).
      org.grammaticalframework.eclipse.testsContains unit tests for the plugin. Not required for running the plugin.
      org.grammaticalframework.eclipse.ontology-grammarGF Ontology Grammar Plugin for Eclipse, developed separately by Ontotext AD.
      org.grammaticalframework.featureFeature project for the GF Eclipse Plugin. Exports org.grammaticalframework.eclipse and org.grammaticalframework.eclipse.ui.
      org.grammaticalframework.feature.ontology-grammarFeature project for the GF Ontology Grammar Plugin. Exports org.grammaticalframework.eclipse.ontology-grammar.
      org.grammaticalframework.updatesiteUpdate site project which exports both feature projects under the same category.

      Extra dependencies for unit testing project

      The unit testing project (org.grammaticalframework.eclipse.tests) has an extra requirement for the library org.eclipselabs.xtext.utils.unittesting, which you will probably get complaints about when importing your projects into Eclipse. You only need to worry about this if you want to run the unit tests; otherwise you can ignore these errors. You can get more information about this library here, or just install it in Eclipse directly using the following update site URL: http://xtext-utils.eclipselabs.org.codespot.com/git.distribution/releases/unittesting-0.9.x/

      Xtext version

      @@ -355,37 +402,37 @@ sudo apt-get install gtk2-engines-pixbuf - + Abstract module abstract Foods = {...} - + Concrete module concrete FoodsEng of Foods = {...} - + Resource module resource ResFoods = {...} - + Interface interface LexFoods = {...} - + Instance instance LexFoodsEng of LexFoods = {...} - + Functor incomplete concrete FoodsI of Foods = {...} - + Functor instantiation concrete FoodsEng of Foods = FoodsI with (...) {...}