gf-core/eclipse/index.html

<h1>The GF Eclipse Plugin</h1>

<p>John  J. Camilleri<br />
Updated: 8 Feb 2012</p>

<p><em>The research leading to these results has received funding from the European Union&#8217;s Seventh Framework Programme (FP7/2007-2013) under grant agreement n° FP7-ICT-247914.</em></p>

<p><em>This documentation is also available at the <a href="http://www.molto-project.eu/node/1395">MOLTO Project Wiki</a>.</em></p>

<h2>Introduction</h2>

<p>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.</p>

<p>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 (GFEP) will require some manual installation and configuration on the development machine. Thus the GFEP is aimed more at seasoned developers rather than the curious GF newbie.</p>

<p>The starting point for the GFEP is using the <a href="http://www.eclipse.org/Xtext/">Xtext DSL Framework</a> for Eclipse. By converting the GF grammar into the appropriate Extended-BNF form required by the LL(*) ANTLR parser, the framework provides a good starting point for future plugin development, already including a variery of syntax checking tools and some cross-reference resolution support. The specific requirements of the GF language, particularly in the way of its special module hierarchy, mean that significant customisations to this generated base plugin are needed.</p>

<p>The GFEP is being developed by  as part of Work Package 2 of the <a href="http://www.molto-project.eu/">MOLTO Project</a>.</p>

<h3>Links</h3>

<ul>
<li>This document shall contain the most up-to-date information about the plugin. The most up-to-date version of this file can always be found in the source-code repository at <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin/blob/master/README.markdown">https://github.com/GrammaticalFramework/gf-eclipse-plugin/blob/master/README.markdown</a></li>
<li>Source code repository is at <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin">https://github.com/GrammaticalFramework/gf-eclipse-plugin</a> (do not try to run the plugin from source; please only use the packaged releases).</li>
<li>For reporting bugs and requesting features, please use the <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin/issues">GitHub Issue Tracker</a></li>
<li>Here are some <a href="http://www.grammaticalframework.org/eclipse/examples/">example GF projects</a> for testing out the plugin features.</li>
<li>Software update site URL for installing through Eclipse: <a href="http://www.grammaticalframework.org/eclipse/release/">http://www.grammaticalframework.org/eclipse/release/</a></li>
</ul>

<hr />

<h2>Features</h2>

<h3>Implemented</h3>

<ul>
<li>Syntax highlighting and error detection</li>
<li>Code folding, quick block-commenting, automatic code formatting</li>
<li>Definition outlining, jump to declaration, find usage</li>
<li>Warnings for problems in module dependancy hierarchy</li>
<li>Launch configurations, i.e. compilation directly from IDE</li>
<li>Use GF Shell from within Eclipse</li>
<li>Auto-completion for declared identifiers</li>
<li>Background compilation (shallow) using project builder</li>
<li>Support for <em>Open Declaration</em> (F3)</li>
<li>Code generation for new languages in application grammars</li>
</ul>

<h3>Near-term</h3>

<ul>
<li>Built-in library browser (in particular for GF resource grammar library)</li>
<li>Inline documentation for function calls, overloads</li>
<li>Quick-fix suggestions for syntax and naming errors</li>
<li>Code generation for concrete/instance modules</li>
<li>Grouping of concrete syntaxes by language, fast switching and linked navigation</li>
</ul>

<h3>Long-term goals</h3>

<ul>
<li>Test-suite functionality</li>
<li>Treebank management and testing</li>
<li>Provide a single platform for developing and using embedded grammars</li>
<li>Integration with ontology engineering tools</li>
</ul>

<hr />

<h2>Major release history</h2>

<dl>
<dt><strong>07/02/12</strong></dt>
<dd>(1.3.0.x) Re-written underlying GF grammar.</dd>

<dt><strong>02/02/12</strong></dt>
<dd>(1.2.5.x) Hugely improved scoping performance. New &#8220;Clone to new language&#8221; wizard. Improved code formatting. More efficient builder. Removed library path preference. GF runtime is now automatically found.</dd>

<dt><strong>23/01/12</strong></dt>
<dd>(1.2.4.x) Logging is now done to the Eclipse Platform Log (use &#8220;Error Log&#8221; view). Tested with Eclipse 3.6.2. Bug fixes.</dd>

<dt><strong>11/01/12</strong></dt>
<dd>(1.2.3.x) Updated to use Xtext 2.1.0. Links to external files now moved into new &#8220;GF Library View&#8221;.</dd>

<dt><strong>24/11/11</strong></dt>
<dd>(1.2.0.x) with support for &#8220;Open Declaration&#8221; (F3) function, including for external libraries.</dd>

<dt><strong>18/11/11</strong></dt>
<dd>Third BETA (1.1.0.x) released, overhauled to take advantage of new compiler features. Tag-based scoping with caching for better performance. Interactive console (GF Shell) for luanch configs.</dd>

<dt><strong>11/10/11</strong></dt>
<dd>Second BETA (1.0.0.x) released, with improved support for qualified names, local variable bindings, selective inheritance, module outlining, and launch configurations. Also new GF Project type.</dd>

<dt><strong>01/10/11</strong></dt>
<dd>Initial BETA released.</dd>
</dl>

<hr />

<h2>Installation &amp; updating</h2>

<h3>System requirements</h3>

<ol>
<li>The plugin makes use of the newest GF features, and <strong>requires the latest developer version of GF</strong> to be installed on your system (instructions <a href="http://www.grammaticalframework.org/download/index.html">here</a>).
<em>Specifically, you need a version of GF which supports the &#8220;&#8212;tags&#8221; flag, added in November 2011.</em></li>
<li>Paths to GF must be set within the plugin (see below). This means:

<ul>
<li>you don&#8217;t necessarily need to have GF in your <code>PATH</code> environment variable</li>
<li>you can use a separate GF installation for GFEP if you wish</li>
</ul></li>
<li>The plugin was developed using Eclipse 3.7. It has been successfully installed on Eclipse as low as 3.6.2.</li>
</ol>

<h3>Installing the plugin for the first time</h3>

<p><strong>Note about Available Software Sites</strong></p>

<p>In order for dependencies to be satisfied, you need to ensure that your Eclipse has the following update site URLs set:</p>

<ul>
<li>Eclipse releases (change version name to match): <a href="http://download.eclipse.org/releases/indigo">http://download.eclipse.org/releases/indigo</a></li>
<li>Xtext: <a href="http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/">http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/</a></li>
</ul>

<p><strong>Steps for installation</strong></p>

<ol>
<li>Inside Eclipse, go to <strong>Help &rarr; Install New Software</strong>.</li>
<li>Add new software site using the URL: <a href="http://www.grammaticalframework.org/eclipse/release/">http://www.grammaticalframework.org/eclipse/release/</a></li>
<li>Select the <strong>GF Eclipse Plugin</strong>, and make sure the <strong>Contact all update sites during install to find required software</strong> option is checked.</li>
<li>Click Next, accept the license agreement and install.</li>
<li>Accept the prompt warning that the software is unsigned.</li>
<li>Restart Eclipse when prompted.</li>
</ol>

<h4>Settings</h4>

<ol>
<li>Add the GF perspective by clicking <strong>Open Perspective &rarr; Other</strong> and choosing <strong>GF</strong>.</li>
<li>The plugin will try to determine the path to your GF executable automatically. You can always check/overwrite it by going to <strong>Window &rarr; Preferences &rarr; Grammatical Framework</strong>.  </li>
<li>You can also adjust the verbosity level of the GFEP console log in the preferences window.</li>
</ol>

<h3>Updating the plugin</h3>

<ol>
<li>In Eclipse, go to <strong>Help &rarr; Check for updates</strong>.</li>
<li>Any available updates will appear in the dialog. Select them and follow the usual steps.</li>
</ol>

<h4>Deprecated stuff</h4>

<ul>
<li>If your project has a folder named <code>(External)</code> you can safely delete this <strong>via the Eclipse Project Explorer</strong>. It is no longer used in GFEP >= 1.2.3</li>
<li>If your workspace contains a log file <code>gfep.log</code> then you can safely delete it from your system. As of version 1.2.4, GFEP uses Eclipse&#8217;s standard log file at <code>.metadata/.log</code></li>
</ul>

<h3>Project settings</h3>

<p>Although the plugin should take care of your project settings for you, in case anything gets messed up you can always correct them manually as follows:</p>

<h4>Project nature</h4>

<p>Your <code>.project</code> file should include the GF Project Nature as follows:</p>

<pre><code>&lt;natures&gt;
  &lt;nature&gt;org.grammaticalframework.eclipse.ui.natures.projectNatureID&lt;/nature&gt;
&lt;/natures&gt;
</code></pre>

<h4>Builder</h4>

<p>Your <code>.project</code> file should include the GF Builder as follows:</p>

<pre><code>&lt;buildSpec&gt;
  &lt;buildCommand&gt;
      &lt;name&gt;org.grammaticalframework.eclipse.ui.build.GFBuilderID&lt;/name&gt;
      &lt;arguments&gt;
      &lt;/arguments&gt;
  &lt;/buildCommand&gt;
&lt;/buildSpec&gt;
</code></pre>

<hr />

<h2>Getting started</h2>

<p>Some steps you can follow to get a feel of of the plugin&#8217;s features.</p>

<ul>
<li>Create a new <strong>GF Project</strong>.</li>
</ul>

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-projectwizard-1.png" alt="New project wizard" />
<img src="http://www.grammaticalframework.org/eclipse/images/eclipse-projectwizard-2.png" alt="New project wizard" /></p>

<ul>
<li>Create some new modules using the <strong>GF Module</strong> wizard from <strong>File &rarr; New &rarr; Other &rarr; GF Module</strong>:</li>
</ul>

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-modulewizard-1.png" alt="New module wizard" /></p>

<p><em>If asked whether you want to add the <strong>Xtext nature</strong> to your project, you can safely say <strong>No</strong> (this prompt has been removed in newer versions).</em></p>

<ul>
<li><p>You can find some small examples at <a href="http://www.grammaticalframework.org/eclipse/examples/">http://www.grammaticalframework.org/eclipse/examples/</a>. Download the 
files and manually add them to your Eclipse workspace to experiment with some of the plugin features.</p></li>
<li><p>You can change your syntax colouring styles as you wish from <strong>Window &rarr; Preferences &rarr; Grammatical Framework &rarr; Syntax Coloring</strong></p></li>
</ul>

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-syntaxcoloring.png" alt="Syntax highlighting styles" /></p>

<ul>
<li>Use Eclipes&#8217; own features to drag and drop your editor tabs to suit your needs. Notice the <strong>Outline</strong> view in the bottom-right offers a quite overview of your module structure. Clicking any of the terms will make your cursor jump to that point in the file.</li>
</ul>

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-editor-general.png" alt="The editor and outline view" /></p>

<ul>
<li>Note how changing a <code>cat</code> definition for example will produce warnings and/or errors in other the modules.</li>
</ul>

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-editor-cat.png" alt="Warnings and errors in the editor" /></p>

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

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-before-format.png" alt="Before auto-formatting" /> <img src="http://www.grammaticalframework.org/eclipse/images/eclipse-after-format.png" alt="After auto-formatting" /></p>

<ul>
<li>Set up a launch configuration from <strong>Run &rarr; Run Configurations&#8230; &rarr; Grammatical Framework</strong>. You will see the dialog below with some fields automatically filled in for you. </li>
</ul>

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-launchconfig.png" alt="Launch configuration dialog" /></p>

<ul>
<li>Run the launch config and you will see the output from the GF compiler in the console view within Eclipse.</li>
</ul>

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-compileroutput.png" alt="Output from the GF compiler" /></p>

<h3>Usage hints &amp; issues</h3>

<h4>Consoles</h4>

<p>The plugin provides its own console view named <em>GFEP Log</em>, which shows log messages based on the <strong>Log Level</strong> preference (<strong>Window &rarr; Preferences &rarr; Grammatical Framework</strong>).</p>

<p>Additionally, everytime a grammar is <strong>Run</strong> a <em>new</em> console is opened to display the output. This console may also serve as the interactive GF Shell, depending on the <strong>Interactive Mode</strong> checkbox in your <strong>Run Configuration</strong>.</p>

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

<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-console-icon.png" alt="Display Selected Console icon" /></p>

<p><em>The Eclipse console implementation does not support command history (up arrow) or auto-completion (tab).</em></p>

<h4>Logs</h4>

<p>You can set the log verbosity from <strong>Window &rarr; Preferences &rarr; Grammatical Framework</strong>.</p>

<h4>Validation</h4>

<p>For validation to work correctly, the project&#8217;s <strong>Build Automatically</strong> option should be turned on.</p>

<p>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.</p>

<p>Sometimes you may get an entire file marked with errors, even though in fact there is only a single error which is causing the internal builder to fail. In such cases referring to the <strong>Problems</strong> view should help you locate the cause. This issue is particularly relevant when changes made to one module may induce errors in its descendants (e.g. renaming a parameter in a resource module). This behaviour will hopefully be improved in future versions.</p>

<hr />

<h2>Evaluation &amp; feedback</h2>

<p>Please try to use the plugin for developing your own GF projects and report any issues you come up against.</p>

<p>For all bug reports and feature requests please use the GitHub Issue Tracker at <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin/issues">https://github.com/GrammaticalFramework/gf-eclipse-plugin/issues</a>.</p>

<p>Do not hesitate to let us know how you think the plugin can be improved!</p>

<h3>Criteria</h3>

<p>As part of the evaluation of the GF Eclipse Plugin, feedback (both negative and positive) on the following would be appreciated:</p>

<ol>
<li>Issues encountered with installation</li>
<li>Incorrect support of GF syntactic constructs, module hierarchy system</li>
<li>Performance issues (speed, resources footprint)</li>
<li>General intuitiveness of the UI</li>
<li>Feature wish-list</li>
<li>Compatibilities / conflicts with other Eclipse plugins</li>
</ol>

<h3>Logs</h3>

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

<ol>
<li>By opening the <strong>Error Log</strong> view in Eclipse</li>
<li>Accessing the file directly at <code>workspace/.metadata/.log</code></li>
</ol>