EDT:Developer's Guide to Getting Started on EDT

Objective

Working through the steps of this document will result in the following:

• a new development environment populated with the EDT source
• the ability to run EDT, with or without the Eclipse debugger
• an understanding of how the source is structured

Team Communication

Discussions and announcements for the EDT developers use the edt-dev mailing list, edt-dev@eclipse.org. You can subscribe to edt-dev and read its archive at http://dev.eclipse.org/mailman/listinfo/edt-dev. All committers and contributors should subscribe to edt-dev.

Bugs and enhancements are tracked in Bugzilla, at https://bugs.eclipse.org/bugs/. Our "product" in Bugzilla is EDT.

You need to understand that working on EDT is the same as for any other Eclipse project, as described in the Eclipse Development process; briefly, there are committers and contributors. Everyone can view the source code and make changes to a local copy, but only a committer can make changes to the code in the repository. A contributor's changes can be attached to a bug or enhancement in Bugzilla, to be reviewed and integrated into the repository by a committer.

A list of the committers, and other information about the EDT project, can be found at http://www.eclipse.org/projects/project_summary.php?projectid=tools.edt.

Step 1. Setting up Eclipse

For brevity, we'll describe just one or two ways to setup Eclipse -- there are of course many more ways but here's the most common approach.

We assume you will be working with the Eclipse 3.7 "Indigo" IDE For Java EE Developers package. Eclipse is in a zipfile that you unzip somewhere in your filesystem.

If you already have Eclipse 3.7, you can use that but you may want to have a separate workspace for EDT. Just click File --> Switch Workspace --> Other; change the workspace directory to whatever you'd like and click OK.

We use the UTF-8 encoding for all of our files. Set your workspace's Text File Encoding preference to UTF-8. The preference is on the General > Workspace preference page.

At this point, we assume you have Eclipse 3.7 running and are ready to populate it with lots of EDT source.....

Step 2. Loading the EDT source

Open the Git Repository Exploring perspective. In the Git Repositories tab, paste the URI of our repository:

Contributors should use git://git.eclipse.org/gitroot/edt/org.eclipse.edt.git

Committers should use ssh://@git.eclipse.org/gitroot/edt/org.eclipse.edt.git

The Clone Git Repository dialog will appear. (If you are a committer, enter your username and password here.) Press Next and choose the branch called master. Press Next again. Be sure the destination directory is set properly. It identifies where your working copy of the files from Git will be stored. Don't put them under your Eclipse workspace directory. Press Finish when you're done.

At this point, you should have an entry in the Git repositories labeled with the repository location information you just entered. Now you can get the code out of the repository. Right-click on the repository and choose Import Projects. Press Next on the dialog that appears (accepting the default choice "Import existing projects"). You will see a large number of projects. Select them all and press Finish.

You can now close the Git Repository Exploring perspective or simply switch back to the Java perspective -- you should see all of the projects you just loaded. You could of course start browsing around the source, but first let's get EDT running....

Step 3. Setting up a Launch Configuration

Eclipse uses "launch configurations" to understand how to run the applications you're developing in the Eclipse workbench. These are quite powerful, and in fact, you can create launch configurations that run another instance of Eclipse! Since EDT is Eclipse-based, this is exactly what we want. It can get a little confusing, but it's pretty simple: We have a dev-time instance of Eclipse in which we work with the EDT source, and we have a run-time instance that we launch when we're ready to exercise EDT and perhaps debug EDT source.

In Eclipse, click the Debug button on the toolbar (or click Run --> Debug Configurations....):

• In the tree on of configuration types on the left, select "Eclipse Application"
• Click on the new button
• Name your launch configuration, perhaps something like "EDT"
• Under "Program to Run", select "Run a product" and choose "org.eclipse.platform.ide"
• Click on the Arguments tab
• Enter these program arguments:

-os ${target.os} -ws ${target.ws} -arch ${target.arch} -nl ${target.nl} -consoleLog

• Enter these VM arguments:

-Dosgi.requiredJavaVersion=1.5 -Xms40m -Xmx768m -XX:PermSize=256m -XX:MaxPermSize=256m

Step 4: Running EDT

Simply click on the drop-down next to the Debug icon on your toolbar to access the list of defined launch configurations; you should see the one you created in the previous step (e.g., "EDT"). Click that to start EDT.

After a few moments, depending on the speed of your system, you should see the Eclipse banner as your run-time instance starts up. Once Eclipse finishes launches, you're running EDT! You might try to create a new EGL project and enter some EGL source. You might also examine the properties for your new project -- especially the EGL Compiler page to see how generators are chosen and configured.

Step 5. Understanding the EDT Codebase

As you might expect from an Eclipse-based project, EDT is comprised of a large number of "plugins" that provide various functions, written entirely in Java. At its core, EDT's goal is to provide a development experience for writing, maintaining, and debugging EGL source, so some of these plugins implement an EGL compiler. Since EGL can be translated to an arbitrary set of target languages, the compiler doesn't produce machine code or bytecodes, but instead produces "IR" files, which encode the EGL source into a MOF-based data structure. This is what is passed to a generator, whose goal is to translate that MOF-based model of the EGL source into sourcecode for some target language; EDT has generators for Java and JavaScript (and others can be added). Since EDT is meant to be extensible, these generators themselves must be extensible and this is supported with a unique system of templates (implemented in Java) that output target source given some element in the EGL MOF model. Finally, there's also a set of plugins which extend the Eclipse IDE to integrate the EGL compiler and generators and also provide things like EGL preferences and editor support for EGL.

Given this overview of the EDT codebase, let's briefly look at how it's mapped into plugins; the following list isn't meant to be exhaustive -- there are just too many plugins -- but it's meant to give you a sense for the major components of EDT and the plugin(s) in which they are implemented. Again, this is just to help you get oriented with the EDT codebase, not provide a detailed map.

All of EDT's plugins begin with the prefix "org.eclipse.edt".

• org.eclipse.edt.compiler.* Implements the EGL compiler which turns EGL source files into XML-encoded IR files; these "Intermediate Representation" files are data structures capturing the compiler's understanding of the EGL source.

• org.eclipse.edt.debug.* Implements the EGL debugger which leverages the powerful Eclipse debugger for use with EGL applications.

• org.eclipse.edt.gen.java.* Implements the Java generator for deriving Java source from EGL source.

• org.eclipse.edt.gen.javascript.* Implements the JavaScript generator for deriving JavaScript source from EGL source.

• org.eclipse.edt.ide.* Covers all EGL support in the runtime workbench and includes such things as the EGL perspective, editor support for EGL, EGL property pages and preferences, etc.

• org.eclipse.edt.mof.* Implements an abstract model to represent the compiler's understanding of EGL source.

• org.eclipse.edt.runtime.* Implements EGL runtimes for supported target languages.

Step 6. Developing on EDT

Developing for EDT is the same as for any other Eclipse project, and which is described in the Eclipse Development process -- it's strongly recommended that you read that prior to beginning any real EDT development.

Conclusion

The next steps are up to you and whatever your goals are. If you need further guidance, you might ask one of the EGL contributors. Depending on what you need to do, you might also experiment with running EDT under the Eclipse debugger and setting various breakpoints; as always, one way to really understand some new code is to just step through it in the debugger.