Table of Contents
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.
Table of Contents
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:
Install the ANTLR plug-in through its update site - follow installation instructions.
Install the version of EPIC that you wish to hack (you probably already have).
Set the default compiler compliance level to 1.4, both for the source code and for class files (→ , then → ).
Choose External Plug-ins and Fragments, then Projects with source folders.→ , then
From the left pane, choose org.epic.* plug-ins, click, then . You now have EPIC's source code in your workspace.
Choosefrom the context menu on the project org.epic.perleditor.
Choose→ and select org.epic.* projects. This step should build all projects without errors.
Choose→ , create a launch configuration of type Eclipse Application, point it to some workspace and click . You can now change the EPIC code and see the results immediately in the launched workbench. For some changes, relaunching the workbench is required.
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 → from the context menu. This will create a build.xml
file. Right-click on it, choose → 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
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
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 → preferences under → .
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.
To compile the source code of the EPIC editor (org.epic.perleditor project), you will need the (free) ANTLR plug-in. Follow the installation instructions from its web site.
You may wish to create a new workspace in which to keep EPIC projects (→ ). The full-blown development environment includes the source code of Eclipse's own required plug-ins and takes up almost 150 MB of disk space. Operating in a dedicated workspace is a good idea for the following reasons:
You can throw it away easily.
There is no risk of messing up your existing projects.
You can set up workspace-wide preferences just for EPIC.
Running (and debugging) multiple versions of EPIC is easier with 1 version per workspace.
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 is the main project, which contains the editor and most views.
This is the second most important project, which contains the debugger. Without this project, launching Perl scripts would not be possible.
This project implements the RegExp Plug-In.
|org.epic.doc||This project contains the online and offline documentation, including the User's and Developer's Guide.|
|org.epic.perleditor-test||This project contains the automated unit test suites, see Chapter 3, Creating Unit Tests.|
|org.epic.feature.main||This project contains the EPIC feature definition and is only relevant for preparing releases, see Chapter 5, Preparing a Release|
|org.epic.website||This project contains the entire contents of the EPIC web site.|
Before checking out any of the above projects, you must choose which branch to check out from. EPIC development proceeds in two branches:
The HEAD branch contains the 'testing' version of EPIC. This branch is intended to receive all bug fixes and new features. While it might be considered a 'development' branch, it should not be used to check in unfinished (untested) or broken code because its content is periodically released to end users. If you wish to debug a problem or get involved in general, this is the branch to check out.
The 'stable' branch contains the 'stable' version of EPIC. This branch is intended to only receive 'safe' bug fixes, that is, ones for which the risk of breaking existing functionality is minimal. Check out this branch if you wish to contribute a bug fix (actually, you should also incorporate your bug fix into HEAD).
All projects except org.epic.website contain both the HEAD and the 'stable' branch, which was created at the project level. If the 'stable' branch is not visible under Branches in the CVS Repositories view, choose Refresh Branches from the context menu to make it appear.
Having configured the CVS access, go ahead and check out the projects which you are interested in. Select Check Out As... from the context menu and then Checkout as a project in the workspace. The project name should be kept unchanged.
If the option Build automatically is checked in menu Project, the compilation will start immediately after checkout. However, it does not hurt to select all the checked out projects after you are done and use → to get a clean build. There should be some warnings, but no errors reported after this step.
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:
(Optionally) Turn off automatic builds (→ ). 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.
Choose External Plug-ins and Fragments.→ , then
On the next screen, under Import As, choose Projects with source folders. Keep other options unchanged.
On the next screen, select all EPIC projects (org.epic.*) in the left pane and click thebutton. Then, click . 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.
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;
Clickto start the import. This process takes a while.
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:
Under Configurations, choose Eclipse Application and click .
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.
Under VM Arguments, enter
-ea to enable assertions, and any other
arguments (for example, to increase the memory heap size).
Clickto start the workbench. Alternatively, apply changes and close the window and choose → 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.