Jump to: navigation, search

Developer's Guide to Getting Started with IMP

Revision as of 20:08, 28 April 2008 by Rfuhrer.watson.ibm.com (Talk | contribs) (Building a Release Image for the Update Site)

Building IMP from Source

Get Subclipse

If you don't yet have Subclipse (a Subversion client) installed in your Eclipse, do so now from the following update site (i.e. click "New Remote Site..." in the "Search for new features to install" dialog, and enter the following URL):


Install the necessary IMP-related features into Eclipse

Use the Eclipse Update Manager to install Polyglot, LPG, and IMP, if you haven't yet done so, from the following update sites:

You can install them all in one shot. See here for more detailed installation instructions, but note that those instructions say to install each feature separately, which isn't actually necessary. Just create the 3 remote sites and then proceed with the installation.
N.B.: Note that on Linux (and perhaps MacOS X), the installed LPG generator binary sometimes doesn't get marked as executable, so you may have to "chmod +x" it yourself.

Check the LPG executable path

Check the LPG executable path, and make sure that it points to an existing binary for the platform you're running on. Go to the Preferences dialog, and select the LPG page. The appropriate path will look something like: ${pluginLoc:lpg.generator.win32_x86}/lpgexe/lpg-win32_x86.exe or ${pluginLoc:lpg.generator.macosx_x86}/lpgexe/lpg-macosx_x86.exe

N.B.: We will very soon have a way of specifying an appropriately platform-independent location for the executable binary that will not require any user intervention in the normal case. It will look something like ${pluginResource:lpg.runtime/lpgexe/lpg-${os}_${arch}}

Set the LPG include path

Set the LPG include path to point at both the base LPG templates and the IMP/LPG templates by using something like the following in the LPG preferences page: ${pluginResource:lpg.runtime/templates};${pluginResource:org.eclipse.imp.lpg.metatooling/templates} For now, our advice is to set this preference at the "workspace level", so as to avoid having to set it for each of the projects that contains an LPG grammar. (As of this writing, those projects are org.eclipse.imp.lpg.runtime, org.eclipse.imp.prefspecs, and org.eclipse.imp.xform. There are a few other projects in source control that contain LPG grammars but are not yet distributed as part of any feature, including org.eclipse.imp.box, org.eclipse.imp.java.core, org.eclipse.imp.leg, and org.eclipse.imp.presentation.)

Load the IMP source into your workspace

There are 2 ways to proceed:

It's generally a good idea to set up your SSH keys before importing the project sets, so as to avoid being asked for passwords as the import proceeds.

  • Use the IMP Release Engineering Tools to pull the necessary projects into your workspace (bleeding-edge stuff, not guaranteed to work):
    • Use the Eclipse Update Manager to install the "IMP Release Engineering Tools" from the following update site:

http://orquesta.watson.ibm.com/eclipse/updates/releng/ You can install this at the same time as the previous ones, if you didn't already have them installed. Now:

    • Retrieve the update site project by invoking "Release Engineering" -> "Retrieve Update Site Project".
    • Retrieve the features by invoking "Release Engineering" -> "Retrieve Features from Repository".
    • Retrieve the plugins belonging to the features by invoking "Release Engineering" -> "Retrieve Plugins from Repository".
    • Hopefully everything should build properly. If not, jump up and down and stamp your little feet and say "I could use a beer right about now" REALLY LOUD.

At some point, the release tooling will provide a single command to do this, once we're confident that it all works as it should.

Run LPG manually on each grammar file (if needed)

Sometimes the LPG builder doesn't run automatically on each grammar file after the project is imported from the source repository as it should. If this happens, you'll see numerous errors relating to missing parser, lexer and AST (Abstract Syntax Tree) classes.

Select the grammar file in the Package Explorer, and invoke "lpg" from the Tool Launch menu (which is next to the Run/Debug menus in the Java perspective).

Here are the grammar files as of this writing:

  • org.eclipse.imp.box/src/org/eclipse/imp/box/parser/BoxParser.g
  • org.eclipse.imp.java.core/src/org/eclipse/imp/java/parser/JavaParser.g
  • org.eclipse.imp.leg/src/org/eclipse/imp/leg/parser/LegParser.g
  • org.eclipse.imp.lpg.runtime/src/org/eclipse/imp/lpg/parser/LPGParser.g
  • org.eclipse.imp.lpg.runtime/src/org/eclipse/imp/lpg/parser/GJavaParser.g
  • org.eclipse.imp.prefspecs/src/org/eclipse/imp/prefspecs/parser/PrefspecsParser.g
  • org.eclipse.imp.presentation/src/org/eclipse/imp/presentation/parser/ImppParser.g
  • org.eclipse.imp.x10dt.formatter/src/org/eclipse/imp/x10dt/formatter/parser/Pattern-X10.g
  • org.eclipse.imp.xform/src/org/eclipse/imp/xform/pattern/parser/ASTPatternParser.g

Note that you shouldn't have to do this for the X10 compiler itself, since the X10 team has the habit of checking in the generated parser/lexer implementation files.

Building a Release Image for the Update Site

Please note that the "Tag Features" functionality in the IMP Release Engineering Tools has not yet been updated to work with Subversion. You'll have to do that step manually if your plugins reside on a Subversion repository.

  • Make sure all feature and plugin projects are up to date with source control
  • Invoke "Release Engineering" -> "Increment Feature Versions". This will increment the versions of any plugins that have changed since the last release, and update the plugin and feature manifests accordingly. This will warn you if any workspace files are "dirty" (have uncommitted changes).
  • Invoke "Release Engineering" -> "Tag Features" (currently CVS only).
  • Invoke "Update Site Project Set" to add the latest feature versions to the update site.
  • Invoke "Release Engineering" -> "Publish Release" (currently a no-op). This will scp the update archive to the appropriate place on the update site server, and run the appropriate script to extract the archive onto the web server's update site pages.