1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
|
<html>
<head>
<title>GF Eclipse Plugin</title>
<link rel="stylesheet" type="text/css" href="http://www.grammaticalframework.org/css/style.css">
</head>
<body>
<h1>The GF Eclipse Plugin</h1>
<p>John J. Camilleri<br />
Updated: 11 June 2012</p>
<p><em>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 <a href="http://www.molto-project.eu/">MOLTO Project</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 <a href="http://www.grammaticalframework.org/demos/gfse/">GF Web IDE</a>). 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 requires some manual installation and configuration on the development machine.</p>
<h3>License</h3>
<p>The GF Eclipse Plugin is open-source under the <strong><a href="http://www.gnu.org/licenses/gpl-3.0.txt">GNU General Public License (GPL)</a></strong>.<br />
<em>The licenses that cover the rest of GF are listed <a href="http://www.grammaticalframework.org/LICENSE">here</a>.</em><br />
<em>Note that Xtext and Eclipse are released under the <a href="http://www.eclipse.org/legal/epl-v10.html">Eclipse Public License (EPL)</a>.</em></p>
<h3>Links</h3>
<ul>
<li>This document shall contain all collected information about the plugin. The most up-to-date version of this file can always be found <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin/blob/master/README.md">here</a></li>
<li>This documentation is also available at the <a href="http://www.molto-project.eu/node/1395">MOLTO Project Wiki</a>.</li>
<li>Source code repository is at <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin">github.com/GrammaticalFramework/gf-eclipse-plugin</a></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="https://github.com/GrammaticalFramework/gf-eclipse-plugin/tree/master/workspace-demo/GF%20Project">example GF projects</a> for testing out the plugin features.</li>
<li>Software update site URL for installing through Eclipse: <code>http://www.grammaticalframework.org/eclipse/release/</code></li>
</ul>
<h3>Publications</h3>
<ul>
<li><a href="http://academic.johnjcamilleri.com/presentations/2012-05%20EAMT%20poster.pdf">Poster</a> at EAMT 2012 in Trento, Italy</li>
<li><a href="http://academic.johnjcamilleri.com/papers/freerbmt2012.pdf">Paper</a> presented at FreeRBMT 2012 in Gothenburg, Sweden.</li>
</ul>
<h2>Features</h2>
<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 dependency 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), including qualified names</li>
<li>Code generation for new languages in application grammars</li>
<li>Inline documentation for function calls, overloads</li>
<li>Proper cross-reference handling with qualified names</li>
<li>Test management and testing tool</li>
<li>External library browser</li>
</ul>
<h2>Release history</h2>
<dl>
<dt><strong>19/04/12</strong></dt>
<dd>(1.5.0.x) Removed need for <code>.gfexternal</code> 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.</dd>
<dt><strong>04/04/12</strong></dt>
<dd>(1.4.3.x) Improvements to the Test Manager. Added support for arbitrary commands in launch. Made the license information clearer.</dd>
<dt><strong>22/03/12</strong></dt>
<dd>(1.4.2.x) Added wizard for context-free grammars (no syntax support, though). Context-menu option for toggling the GF Nature and Builder together. Test Manager now parses languages & parameters, and includes filtering and toggling options.</dd>
<dt><strong>14/03/12</strong></dt>
<dd>(1.4.1.x) GF source files can now be anywhere in project, not necessarily at top level.</dd>
<dt><strong>06/03/12</strong></dt>
<dd>(1.4.0.x) Test manager view. Updated launch configurations. UI improvements, new icons. Inline contextual documentation. Correct resolution of qualified identifiers. Bug fixes and some refactoring.</dd>
<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 “Clone to new language” 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 “Error Log” 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 “GF Library View”.</dd>
<dt><strong>24/11/11</strong></dt>
<dd>(1.2.0.x) with support for “Open Declaration” (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 launch 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>
<!----------------------------------------------------------------------------->
<h2>Installation & updating</h2>
<h3>System requirements</h3>
<ol>
<li><a href="http://www.eclipse.org/downloads/">Eclipse</a> 3.6 or above.</li>
<li><a href="http://www.grammaticalframework.org/download/release-3.3.3.html">GF 3.3.3</a> or above. The path to GF must be set within the plugin (see below).</li>
</ol>
<h3>Installing the plugin for the first time</h3>
<h4>Available Software Sites</h4>
<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): <code>http://download.eclipse.org/releases/indigo</code></li>
<li>Xtext: <code>http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/</code></li>
</ul>
<p>You can set these from <strong>Preferences → Install/Update → Available Software Sites</strong>.</p>
<h4>Eclipse preferences</h4>
<p>How to find the <strong>Eclipse preferences</strong> window depends on your Eclipse version and/or OS, and may be either of:</p>
<ul>
<li><strong>Window → Preferences</strong></li>
<li><strong>Eclipse → Preferences</strong></li>
</ul>
<h3>Installation</h3>
<ol>
<li>Inside Eclipse, go to <strong>Help → Install New Software</strong>.</li>
<li>Add new software site using the URL: <code>http://www.grammaticalframework.org/eclipse/release/</code></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>Window → Open Perspective → Other</strong> and choosing <strong>GF</strong>.</li>
<li>The plugin will try to determine the path to your GF executable automatically. You can check/overwrite it by going to <strong>Preferences → Grammatical Framework</strong>.
This path should include the name of the GF binary itself, e.g. <code>/home/john/.cabal/bin/gf</code> or <code>C:\Users\John\GF\gf.exe</code>.</li>
<li>By default, the <em>Library path</em> setting is set to <code>.:alltenses:prelude</code>. This is passed to GF using the <code>--path</code> flag.</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 → 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>Any folders <code>.gfexternal</code> can safely deleted as of GFEP ≥ 1.5. Using Eclipse’s <strong>Clean</strong> function from the <strong>Run</strong> menu will do this for you automatically.</li>
<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’s standard log file at <code><workspace>/.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><natures>
<nature>org.grammaticalframework.eclipse.ui.natures.projectNatureID</nature>
</natures>
</code></pre>
<h4>Builder</h4>
<p>Your <code>.project</code> file should include the GF Builder as follows:</p>
<pre><code><buildSpec>
<buildCommand>
<name>org.grammaticalframework.eclipse.ui.build.GFBuilderID</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
</code></pre>
<!----------------------------------------------------------------------------->
<h2>Getting started</h2>
<p>Some steps you can follow to get a feel of of the plugin’s features.</p>
<h3>Video tutorial</h3>
<p>A quick run through of the major features available in the GF Eclipse Plugin.</p>
<iframe src="http://player.vimeo.com/video/38768382?byline=0&portrait=0" width="693" height="512" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe>
<p><em>If the video doesn’t appear above, you can view it at <a href="https://vimeo.com/38768382">https://vimeo.com/38768382</a></em></p>
<h3>The Eclipse <em>workspace</em> and <em>project</em> concepts</h3>
<p>When you run Eclipse, it asks you to create or specify a <em>workspace</em> on your system, which is essentially the top directory that Eclipse will “see”. Any code you wish to work on inside Eclipse must reside in this workspace.
A workspace contains one or more <em>projects</em>, which may or may not be related to each other. Generally each folder under the top-level workspace directory is considered an individual project, i.e.:</p>
<pre><code>workspace/
Project1/
file1-1.gf
file1-2.gf
Project2/
subdir2-1/
file2-1-1.gf
file2-1-2.gf
file2-1.gf
file2-2.gf
</code></pre>
<p>If you open an existing folder as your workspace in Eclipse, then your folders in that workspace <strong>do not</strong> automatically become Eclipse projects.
To do this, you must follow the “Create new GF Project” wizard below, and give your project the exact name of the existing folder (e.g. <code>Project1</code> or <code>Project2</code> in the example above.)</p>
<h4>GF Nature</h4>
<p>The <em>GF Nature</em> is what makes a regular Eclipse project a <em>GF</em> project.
If you create a new GF Project from scratch then you don’t need to worry too much about them.
If you already have some project set up in your Eclipse workspace, then you will need to associate the builder with your project in order for all the GF goodness to work.
This will internally add the <em>GF Builder</em> to your project also.</p>
<p>As of 1.4.2, this can be done very easily by right-clicking on your project in the explorer and clicking <strong>Add/Remove GF Nature</strong>.
If your project has the GF icon overlayed on it, then the GF nature and builder are correctly associated with it.</p>
<p>See the <strong>project settings</strong> section above if you want to mess with your <code>.project</code> file.</p>
<h4>Metadata folders</h4>
<p>GFEP will create the following metadata directories within your project:</p>
<ul>
<li>A <code>.gfbuild</code> directory in every folder containing GF source code, containing <code>.gf-tags</code> files created using the GF <code>--tags</code> compiler flag.</li>
</ul>
<p>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.</p>
<h3>Create a new GF Project</h3>
<p>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.</p>
<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>
<h3>New module wizard</h3>
<p>Use the <strong>GF Module</strong> wizard from <strong>File → New → Other → GF Module</strong>:</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-modulewizard-1.png" alt="New module wizard" /></p>
<p>You can find some small examples <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin/tree/master/workspace-demo/GF%20Project">here</a>. Download the files and manually add them to your Eclipse workspace to experiment with some of the plugin features.</p>
<h3>Clone module wizard</h3>
<p>If you want to clone an existing module into a new language, you can now do so via the <strong>Clone GF Module</strong> wizard. This is also available as a context menu option in the <strong>Project Explorer</strong>, via <strong><Right click> → Grammatical Framework → Compile for new language</strong>:</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-clonewizard.png" alt="Clone GF module to new language wizard" /></p>
<p>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 <code>""</code>. This wizard currently only works on <code>concrete</code> and <code>instance</code> modules.</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-clonewizard-newfile.png" alt="Newly cloned file" /></p>
<h3>Workbench editor layout</h3>
<p>Use Eclipse’ own features to drag and drop your editor tabs to suit your needs.</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-editor-general.png" alt="The editor and outline view" /></p>
<h3>Outline view</h3>
<p>The <strong>Outline</strong> 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.</p>
<h3>Cross-referencing errors and warnings</h3>
<p>Notice how changing a <code>cat</code> definition for example will produce warnings and/or errors in other the modules.</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-editor-cat.png" alt="Warnings and errors in the editor" /></p>
<h3>Validation</h3>
<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>
<h4>Builder</h4>
<p>For validation to work correctly, the project’s <strong>Build Automatically</strong> 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 <em>clean</em> via <strong>Project → Clean…</strong></p>
<h3>Code formatting</h3>
<p>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>.</p>
<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>
<h3>Syntax highlighting</h3>
<p>You can change your syntax colouring styles as you wish from <strong>Preferences → Grammatical Framework → Syntax Coloring</strong></p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-syntaxcoloring.png" alt="Syntax highlighting styles" /></p>
<h3>Launch configurations</h3>
<p>Set up a launch configuration from <strong>Run → Run Configurations… → Grammatical Framework</strong>. You will see the dialog below with some fields automatically filled in for you.</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-launchconfig.png" alt="Launch configuration dialog" /></p>
<p>Run the launch config and you will see the output from the GF compiler in the console view within Eclipse.</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-compileroutput.png" alt="Output from the GF compiler" /></p>
<h4>Run As… launch shortcut</h4>
<p>Using the <strong>Run → Run As → Compile with GF</strong> shortcut will take the current selection or active editor and do one of two things:</p>
<ol>
<li>If a launch configuration already exists which the current file in its <em>Source filenames</em> field, then that config will be launch directly.</li>
<li>Otherwise, a new a launch configuration window is displayed where you will need to review and confirm the default settings before continuing.</li>
</ol>
<h3>Consoles</h3>
<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>Preferences → Grammatical Framework</strong>).</p>
<p>Additionally, every time 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>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:</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-console-terminated.png" alt="Close terminated console icon" /></p>
<p><em>The Eclipse console implementation does not support command history (up arrow) or auto-completion (tab).</em></p>
<h3><em>External Libraries</em> view</h3>
<p>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.</p>
<p>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.</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-external-libraries.png" alt="External libraries view" /></p>
<h3><em>Test Manager</em> view</h3>
<p>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 <a href="http://www.grammaticalframework.org/gf-book/">GF Book</a> (Section 10.5), the general development-test cycle (independent of GFEP) is as follows:</p>
<ol>
<li>Create a file <code>test.trees</code> which contains a bunch of abstract syntax trees, which you want to test</li>
<li>Compile your grammar and linearise the trees one by one, using some command like <code>rf -lines -tree -file=test.trees | l -table | wf -file=test.trees.out</code></li>
<li>Manually correct the output in <code>test.trees.out</code> and save it as your gold standard file <code>test.trees.gold</code>.</li>
<li>Each time you update your grammar, repeat step 2, then compare your new output against the gold standard using <code>diff</code> or some other comparison tool.</li>
</ol>
<p>The <strong>Test Manager</strong> 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:</p>
<p><img src="http://www.grammaticalframework.org/eclipse/images/eclipse-test-manager.png" alt="Test Manager view" /></p>
<p>Note that GFEP assumes the following convention:</p>
<dl>
<dt><code>*.trees</code> or <code>*.sentences</code></dt>
<dd>Test input files: trees file (for testing linearisation) and sentences file (for testing parsing)</dd>
<dt><code>*.trees.out</code> or <code>*.sentences.out</code></dt>
<dd>Corresponding output files (generated each time a test is run)</dd>
<dt><code>*.trees.gold</code> or <code>*.sentences.gold</code></dt>
<dd>Corresponding gold standard files (manually corrected from an output file)</dd>
</dl>
<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>
<p>You can set the log verbosity from <strong>Preferences → Grammatical Framework</strong>.</p>
<!----------------------------------------------------------------------------->
<h2>Common issues and fixes</h2>
<h3>No identifiers are resolved and my log contains messages saying “File Syntax.gf does not exist.”</h3>
<p>In general, this means that something is wrong with your <em>library path</em> setting.</p>
<p>GFEP attempts to compile all of your files individually with GF, which is not the usual way in which you would compile your grammar.
As a result, when looking for the RGL files, GF needs a little help via the <code>path</code> argument.</p>
<p>The normal way to do this is to specify the <em>Library path</em> setting from <strong>Preferences → Grammatical Framework</strong>, setting it to something like <code>.:alltenses:prelude</code> (this is the default setting). Note that these paths are relative to the true RGL directory, which GF should already be aware of. The value of this setting is passed to GF from GFEP using the <code>--path</code> flag.</p>
<p>The <em>Library path</em> setting is the same for all your GF projects. If you want finer-grain control over the <code>path</code> compiler option then you should use compiler pragmas in your source files, e.g.:</p>
<pre><code>--# -path=.:alltenses:prelude
</code></pre>
<p>The advantage of this method is that the information is bound to the file, so you can freely compile your modules outside of GFEP without having to specify the path as a command line option to GF.
The disadvantage is that you need to specify such a pragma in every single file (at least if you want to continue to use the GFEP).</p>
<h3>Other strange behaviour</h3>
<p>When things seem strange, the very first step is always to clean the project via <strong>Project → Clean…</strong>.
I only support the latest version of the plugin, so make sure you are up to date too.</p>
<p>If problems persist, please contact me or better yet file an issue on the GitHub issue tracker (see below).</p>
<!----------------------------------------------------------------------------->
<h2>For developers</h2>
<h3>Project setup</h3>
<p>In order to build/run the GFEP from source, you need to have the Xtext libraries available in your Eclipse workspace. You have two choices:</p>
<ol>
<li>Download the Xtext libraries from <a href="http://www.eclipse.org/Xtext/download/">http://www.eclipse.org/Xtext/download/</a> and add them to your existing Eclipse instance</li>
<li>Download a release of Eclipse packaged together with Xtext from <a href="http://xtext.itemis.com/xtext/language=en/36553/downloads">http://xtext.itemis.com/xtext/language=en/36553/downloads</a></li>
</ol>
<p>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 <code>git clone git://github.com/GrammaticalFramework/gf-eclipse-plugin.git</code> and then add the projects under the <code>workspace</code> directory to your Eclipse workspace.</p>
<h4>Xtext version</h4>
<p>GFEP currently uses Xtext 2.1.0.</p>
<h3>Running from source</h3>
<p>Once you have set up your projects (see above), you can run/debug the GFEP by following the steps <a href="http://www.eclipse.org/Xtext/documentation/2_1_0/020-domainmodel-step-by-step.php#DomainmodelWalkThrough_7">here</a>.
Note that this means you will be running <em>two</em> instances of Eclipse simultaneously; the first debugging the second.</p>
<h3>Building plugin package</h3>
<p>To package the GFEP sources as <code>.jar</code> files and install/update the GFEP in a separate Eclipse installation, do the following:</p>
<ol>
<li>Right-click on the project <code>org.grammaticalframework.feature</code> and choose <strong>Export…</strong></li>
<li>Select <strong>Plug-in Development → Deployable features</strong></li>
<li>Use the following options:
<ul>
<li>Available features: <strong>org.grammaticalframework.feature (x.y.z.qualifier)</strong></li>
<li>Destination
<ul>
<li>Directory: <strong><local directory></strong></li>
</ul></li>
<li>Options
<ul>
<li>Package as individual JAR archives
<ul>
<li>Generate metadata repository</li>
<li>Categorize repository: <strong><workspace>/org.grammaticalframework.feature/category.xml</strong></li>
</ul></li>
<li>Allow for binary cycles in target platform</li>
</ul></li>
</ul></li>
<li>Click <strong>Finish</strong> and wait for the plugin to build. You may get some errors, in which case look through the generated <code>log.zip</code> and fix them, then repeat the process.</li>
</ol>
<h3>Other notes</h3>
<p>Some have mentioned than when opening the GFEP sources, under Linux, they needed to install the following:</p>
<pre><code>sudo apt-get install appmenu-gtk
sudo apt-get install gtk2-engines-pixbuf
</code></pre>
<!----------------------------------------------------------------------------->
<h2>Evaluation & feedback</h2>
<p>Please try to use the plugin for developing your own GF projects and report any issues you come up against.
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>
<p>For all bug reports and feature requests, please use the <a href="https://github.com/GrammaticalFramework/gf-eclipse-plugin/issues">GitHub Issue Tracker</a>.</p>
<!----------------------------------------------------------------------------->
<h2>Appendix</h2>
<h3>Module types</h3>
<p>Description of the GF module types and their icons within the GF Eclipse Plugin.</p>
<table>
<thead>
<tr>
<th align="center">Icon</th>
<th align="left">Description</th>
<th align="left">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td align="center"><img src="http://www.grammaticalframework.org/eclipse/images/module-abstract.png" alt="" /></td>
<td align="left">Abstract module</td>
<td align="left"><code>abstract Foods = {...}</code></td>
</tr>
<tr>
<td align="center"><img src="http://www.grammaticalframework.org/eclipse/images/module-concrete.png" alt="" /></td>
<td align="left">Concrete module</td>
<td align="left"><code>concrete FoodsEng of Foods = {...}</code></td>
</tr>
<tr>
<td align="center"><img src="http://www.grammaticalframework.org/eclipse/images/module-resource.png" alt="" /></td>
<td align="left">Resource module</td>
<td align="left"><code>resource ResFoods = {...}</code></td>
</tr>
<tr>
<td align="center"><img src="http://www.grammaticalframework.org/eclipse/images/module-interface.png" alt="" /></td>
<td align="left">Interface</td>
<td align="left"><code>interface LexFoods = {...}</code></td>
</tr>
<tr>
<td align="center"><img src="http://www.grammaticalframework.org/eclipse/images/module-instance.png" alt="" /></td>
<td align="left">Instance</td>
<td align="left"><code>instance LexFoodsEng of LexFoods = {...}</code></td>
</tr>
<tr>
<td align="center"><img src="http://www.grammaticalframework.org/eclipse/images/module-functor.png" alt="" /></td>
<td align="left">Functor</td>
<td align="left"><code>incomplete concrete FoodsI of Foods = {...}</code></td>
</tr>
<tr>
<td align="center"><img src="http://www.grammaticalframework.org/eclipse/images/module-functor-instantiation.png" alt="" /></td>
<td align="left">Functor instantiation</td>
<td align="left"><code>concrete FoodsEng of Foods = FoodsI with (...) {...}</code></td>
</tr>
</tbody>
</table>
<h3>Build command</h3>
<p>This is the GF command run by the builder:</p>
<pre><code>gf --v=0 --tags --output-dir=.gfbuild [--path=PATH] FILE
</code></pre>
</body>
</html>
|
