View source for 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

== 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 Eclipse 3.6 "Helios", which you can download from here.   Eclipse isn't typically installed (especially since developers often have different versions of Eclipse on their system);  it's just a zipfile that you unzip somewhere in your filesystem.

If you already have Eclipse 3.6, you can use that as-is 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.

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

== Step 2.  Loading the EDT source == 
At this point, you need to understand that working on EDT is the same as for any other Eclipse project, and which is described in the [http://www.eclipse.org/projects/dev_process/development_process_2010.php  Eclipse Development process];  briefly, there are contributers and committers.   Contributers may work anonymously and are free to modify the source to do anything they'd like, whereas committers have been granted authority to work on EDT source as well as to integrate contributer's changes.

Access the CVS Repository Exploring by going to Window --> Open Perspective -> CVS Repository Exploring.   In the CVS Repositories tab, click on the Add CVS Repository button on the toolbar.  In the Host location field, simply paste the appropriate repository location string -- Eclipse will then populate the rest of the fields correctly:

:'''Contributers should use''' :pserver:anonymous@dev.eclipse.org:/cvsroot/tools
:'''Committers should use'''   :extssh:@dev.eclipse.org:/cvsroot/tools


'''Note''' that if you are a commiter, you will need to change the user and password fields to use the credentials given to you by Eclipse.

At this point, you should have an entry in the CVS repositories labeled with the repository location information you just entered (above) from which you should be able to browse the source.  Expand the respoitory and you should have an entry for HEAD;  expand it and locate the EDT source which is contained in a folder labled "org.eclipse.edt".  Expand that and you'll see a collection of top-level folders like core, debug, gen, and more..... Each of these contains the plugin projects that we wish to load.  Start by expanding "core" and selecting all of the plugin folders underneath it;  right-click on the selection and choose "Check out" to load those projects into your Eclipse workspace.  Repeat for all of the peers of "core" (like "debug", etc.) to load the rest of the plugins. 

[[Image:Edt_loading_via_CVSRepositories.png|385px|Illustration of loading EDT source via the CVS Repository Exploring perspective.]]

You can now close the CVS Repository Exploring perspective or simply switch back to the Java perspective -- you should see a large number of projects 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:+UnlockDiagnosticVMOptions -XX:+UnsyncloadClass -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 poweful 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 [http://www.eclipse.org/projects/dev_process/development_process_2010.php  Eclipse Development process] -- it's strongly recommended that you read that prior to beginning any real EDT development.

Discussions and announcements for the EDT developers use the edt-dev mailing list, at [http://dev.eclipse.org/mailman/listinfo/edt-dev 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/ https://bugs.eclipse.org/bugs/].  Our "product" in Bugzilla is EDT.

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 http://www.eclipse.org/projects/project_summary.php?projectid=tools.edt].

== 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.