EPIC - Developer's Guide

Table of Contents

1. Setting Up the Development Environment
Hacking EPIC in 15 Minutes
Installing the Eclipse SDK and EPIC
Installing the ANTLR Plug-In
Creating a New Workspace
Configuring CVS Repository Access
Choosing a Branch
Checking out the Projects
Importing External Plug-ins
Creating a Launch Configuration
2. Coding Conventions
3. Creating Unit Tests
4. Updating Documentation
5. Preparing a Release
6. References

This document introduces new developers to the EPIC project. It also serves as a place for documenting the established development process and the more important design and implementation decisions. It is intended as a supplement to the inline (JavaDoc) documentation found in the source code.

We assume that the reader is familiar with Java in general and the Eclipse IDE (more precisely, JDT) in particular. Familiarity with Eclipse plug-in development and best practices is important if you wish to contribute larger features. However, it should not be necessary to help us diagnose bugs. Also, getting involved in EPIC development can be a great opportunity to learn about programming plug-ins.

This chapter explains how to set up a new workspace for debugging EPIC and modifying its source code. You can either follow the steps exactly or adjust them to match your own environment. We provide two routes: a quick one for the impatient, and a thorough one for the responsible.

EPIC ships with complete source code. If you wish to debug now, or try a quick fix, this short list of steps is for you:

  1. Install the ANTLR plug-in through its update site - follow installation instructions.

  2. Install the version of EPIC that you wish to hack (you probably already have).

  3. Set the default compiler compliance level to 1.4, both for the source code and for class files (WindowPreferences..., then JavaCompiler).

  4. Choose FileImport..., then External Plug-ins and Fragments, then Projects with source folders.

  5. From the left pane, choose org.epic.* plug-ins, click Add, then Finish. You now have EPIC's source code in your workspace.

  6. Choose Toggle ANTLR project nature from the context menu on the project org.epic.perleditor.

  7. Choose ProjectClean... and select org.epic.* projects. This step should build all projects without errors.

  8. Choose RunDebug..., create a launch configuration of type Eclipse Application, point it to some workspace and click Debug. You can now change the EPIC code and see the results immediately in the launched workbench. For some changes, relaunching the workbench is required.

  9. If you wish to distribute your changes (e.g., install them in your real workbench), right-click on plugin.xml in each of the plug-ins and choose PDE ToolsCreate Ant Build File... from the context menu. This will create a build.xml file. Right-click on it, choose Run AsAnt Build... and select the target named zip.plugin. This will create an archive which you can unzip under $ECLIPSE_HOME/plugins as a replacement for the original version shipped with EPIC (which you have to delete manually). Run Eclipse with the option -clean to complete the installation. Congratulations, you are now running your own version of EPIC.

If you would like to contribute your modifications to the project, a bit more preparation is in order. Forget the above steps and read on.

The first step is to install Java and Eclipse. This might come as a surprise because you must already have done it if you are using EPIC. However, there is a catch: EPIC's code is meant to remain compatible with the Eclipse 3.1.x series. While it will compile and run fine using Eclipse 3.2 or later, there is a danger of introducing backwards incompatible changes if you modify the source code. Therefore, it is recommended to use Eclipse 3.1.2 during development. Download and install it if you are serious about contributing to EPIC. If you just wish to debug, 3.2 will do.

What about Java? The source code of EPIC currently requires a JDK 1.4-compliant compiler (because of the assert keyword). Importantly, it does not require JDK 1.5; none of the new language features are used. To honour this convention, you may need to modify JavaCompiler preferences under WindowPreferences....

Finally, install the version of EPIC which you are going to work on, following the normal install procedure described in the User's Guide. Even though you will download source code from the CVS, having EPIC installed comes handy when you wish to import and modify the relevant Eclipse plug-ins.

Switch to the CVS Repository Exploring perspective and set up a new repository. The settings are typical for a SourceForge project and can be found here. After creating the repository item, browse into HEAD to see all EPIC subprojects. Some of these subprojects are no longer maintained and irrelevant. The following table describes the current and important ones. You will definitely want to check out the first four:

This step is optional. During development of EPIC, you will be soon stepping through Eclipse code using the Java debugger. Quite likely, you will also wish to modify the Eclipse code from time to time during your debugging sessions. Finally you might want to step through or modify ANTLR code on which EPIC parser is based. All these tasks are supported by having the plug-ins referenced by EPIC in the workspace as projects with source code.

In order to import the referenced projects, proceed as follows:

  1. (Optionally) Turn off automatic builds (ProjectBuild automatically). We are going to import many projects at once. If your workbench does not have enough available memory (512 MB recommended), you may experience OutOfMemoryErrors if the complete build executes automatically.

  2. Choose FileImport..., then External Plug-ins and Fragments.

  3. On the next screen, under Import As, choose Projects with source folders. Keep other options unchanged.

  4. On the next screen, select all EPIC projects (org.epic.*) in the left pane and click the Add button. Then, click Required Plug-ins. Remove the EPIC projects from the right pane. In the effect, only the plug-ins which are required by EPIC remain in the right pane to be imported.

  5. Add org.antlr from the left pane for import. This plug-in is not required by EPIC, but useful to keep in the workspace as a source code location for debugging. (If you try stepping into the ANTLR code, you will be asked to provide a source code location; choose org.antlr/src-antlr then.)

  6. Click Finish to start the import. This process takes a while.

  7. If you turned off automatic builds in the first step, now is time to build the imported projects - individually or in groups. After all projects have been built, it is safe to turn automatic builds back on.

During development, we want to be able to modify the source code in the workspace and immediately see the effects of our changes in another Eclipse workbench. We also want to be able to set breakpoints in the source code and have that other workbench stop execution at them, report values of variables to the debugger, etc. Both goals are accomplished by creating a launch configuration of type Eclipse Application. Essentially, the workbench instance which operates on the workspace with EPIC's source code is used to launch and debug another workbench instance, which uses its own workspace elsewhere in the file system. Because we also imported Eclipse's own source code into the host workspace in the previous step, we now have full control over the execution of the hosted workbench.

To create a launch configuration for the hosted workbench, proceed as follows:

  1. Choose RunRun....

  2. Under Configurations, choose Eclipse Application and click New.

  3. Under Workspace Data, enter the path to the workspace which should be used by the hosted workbench. If the path points to a non-existing folder, this folder will be created, just like when starting Eclipse normally.

  4. Under VM Arguments, enter -ea to enable assertions, and any other arguments (for example, to increase the memory heap size).

  5. Click Run to start the workbench. Alternatively, apply changes and close the window and choose RunDebug... to launch the workbench in debug mode.

After a short while, another workbench will open. This workbench is running EPIC code from the host workspace. When in debug mode, changes made in the code will become immediately visible (subject to restrictions of the JVM).

This step concludes setting up the basic development environment. You are now able to modify and debug EPIC code. However, in order to verify the quality of your contributions, you should also set up the test environment and add unit tests along with your features or bug fixes. At the very least, you should run the existing unit tests before committing changes to CVS (or submitting patches) in order to protect EPIC against regression bugs (breaking of previous functionality). This topic is described in Chapter 3, Creating Unit Tests.