Difference between revisions of "EDT:Developer's Guide to Getting Started on EDT"

From Eclipsepedia

Jump to: navigation, search
m
(Step 2. Loading the EDT source)
 
(4 intermediate revisions by 2 users not shown)
Line 17: Line 17:
 
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.
 
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" IDE For Java EE Developers package, which you can download from [http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/heliossr2 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.
+
We assume you will be working with the [http://www.eclipse.org/downloads/packages/release/indigo/sr2 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.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.
+
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.
  
At this point, we assume you have Eclipse 3.6 running and are ready to populate it with lots of EDT source.....
+
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.
  
== Step 2. Loading the EDT source ==
+
At this point, we assume you have Eclipse 3.7 running and are ready to populate it with lots of EDT source.....
Open the CVS Repository Exploring perspective. 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:
+
  
:'''Contributors should use''' :pserver:anonymous@dev.eclipse.org:/cvsroot/tools
+
== Step 2. Loading the EDT source ==
:'''Committers should use'''  :extssh:@dev.eclipse.org:/cvsroot/tools
+
  
 +
Open the Git Repository Exploring perspective.  In the Git Repositories tab, paste the URI of our repository:
  
'''Note''' that if you are a committer, you will need to change the user and password fields to use the credentials given to you by Eclipse.
+
:'''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
  
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 repository and you should have an entry for HEAD;  expand it and locate the EDT source which is contained in a folder labeled "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.  
+
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.
  
[[Image:Edt_loading_via_CVSRepositories.png|385px|Illustration of loading EDT source via the CVS Repository Exploring perspective.]]
+
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 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....
+
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 ==  
 
== Step 3.  Setting up a Launch Configuration ==  
Line 66: Line 66:
 
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.   
 
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".  
+
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.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.   

Latest revision as of 12:59, 3 August 2012

Contents

[edit] 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

[edit] 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.

[edit] 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.....

[edit] 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....

[edit] 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

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.