Developer's Guide to Getting Started with IMP

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):

 http://subclipse.tigris.org/update_1.2.x

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:

• http://www.cs.cornell.edu/Projects/polyglot/eclipseUpdates/index.html
• http://lpg.sourceforge.net/updates/
• http://eclipse-imp.sourceforge.net/updates/
• http://www.meta-environment.org/updates (Used to be http://homepages.cwi.nl/~daybuild/releases/eclipse)

The last of these is for the SDF/Box support used by the source formatting functionality. You only need this if you're creating source formatting support for your language. 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 all of the 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: using Team Project Sets, or using the IMP Release Engineering Tools.

Importing using Team Project Sets

Use the project sets located at the following URLs:

• lpg.psf
• imp-core.psf
• imp-metatooling.psf
• x10dt.psf

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.

Using the IMP Release Engineering Tools

Bleeding-edge stuff, not guaranteed to work perfectly yet To pull the necessary projects into your workspace

• Use the Eclipse Update Manager to install the "IMP Release Engineering Tools" from the following update site:

http://download.eclipse.org/technology/imp/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 desired update site project by invoking "Release Engineering" -> "Retrieve Update Site Project".
  • If you're not an IMP developer (you'd know it if you were), make sure that "Use Anonymous Repository Access" is checked.
  • Make sure that the two options "Also retrieve feature projects" and "Also retrieve plugin projects" are checked.
• It will prompt you to confirm the feature and plugin projects it needs to download (one confirmation for the feature projects, one for the entire set of plugin projects).
• Repeat the above step once for each update site's worth of source.
  • [Note] you needn't pull in, e.g., the LPG source, if you don't intend to change it.
  • [Note] If you don't put the source for some dependent feature (e.g. LPG) in your workspace, you must install that feature into your Eclipse install (see above step 1.2).
• 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" and "Increment Feature Versions" functionality in the IMP Release Engineering Tools has not yet been updated to work with Subversion. [This is due to a missing bit of functionality in the Subclipse plugin.] 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.