Jump to: navigation, search

Difference between revisions of "AJDT Developer FAQ"

Line 6: Line 6:
  
 
Your contributions to the AJDT project are strongly welcomed! You can create a patch that fixes a bug or provides an enhancement and submit it to the AJDT developers either as an attachment to a bug in Bugzilla, or as an attachment to a post to the newsgroup or developer mailing list. You can also contribute sample code showing interesting uses of AspectJ, by adding entries to the example plug-in. All contributions must be made available under the [http://www.eclipse.org/legal/termsofuse.php terms of the Eclipse website] see the Eclipse [http://www.eclipse.org/legal/legalfaq.php#contributions contribution and participation FAQ]. Sorry, but for legal reasons we are unable to accept patches emailed directly to developers, and will normally ask you to resubmit these either via Bugzilla or the mailing list. AJDT development is run as a meritocracy, developers who have a track record of submitting good patches can become committers on the project.  
 
Your contributions to the AJDT project are strongly welcomed! You can create a patch that fixes a bug or provides an enhancement and submit it to the AJDT developers either as an attachment to a bug in Bugzilla, or as an attachment to a post to the newsgroup or developer mailing list. You can also contribute sample code showing interesting uses of AspectJ, by adding entries to the example plug-in. All contributions must be made available under the [http://www.eclipse.org/legal/termsofuse.php terms of the Eclipse website] see the Eclipse [http://www.eclipse.org/legal/legalfaq.php#contributions contribution and participation FAQ]. Sorry, but for legal reasons we are unable to accept patches emailed directly to developers, and will normally ask you to resubmit these either via Bugzilla or the mailing list. AJDT development is run as a meritocracy, developers who have a track record of submitting good patches can become committers on the project.  
 +
 +
===Setting up your workspace for AJDT===
 +
 +
You need to start with a version of Eclipse that contains the RCP tools, which can be obtained on the [http://www.eclipse.org/download Eclipse downloads page].  Many of the plugins which implement AJDT contain aspects, and so are AspectJ projects themselves. This means that you first need to install a recent build of AJDT into your development environment from the update site or zip file.
 +
 +
Although not required, we recommend that you use a version of Eclipse that mirrors the version of AJDT that you are developing for.  So, use an Eclipse 3.5 to develop AJDT targeting Eclipse 3.5. 
 +
 +
AJDT provides optional Mylyn integration.  If the target install of your Eclipse does not contain Mylyn, you will have errors in the ''org.eclipse.ajdt.mylyn.ui'' bundle.  Unless you are actively developing Mylyn support, you can safely close that bundle.
 +
 +
The next step is to actually check out the source code.
 +
  
 
=== Where will I find the source for AJDT? ===
 
=== Where will I find the source for AJDT? ===
Line 17: Line 28:
 
+ Wait...  
 
+ Wait...  
  
[[Image:Ajdt35ProjectSet.psf]]
+
[[Image:Ajdt35ProjectSet.psf|alt=ajdt 35 team project set]]
  
[[Image:Ajdt36ProjectSet.psf]]
+
[[Image:Ajdt36ProjectSet.psf|alt=ajdt 36 team project set]]
  
<br> Relevant packages under “AJDT_src” Description Plugins org.aspectj.ajde The AspectJ compiler and related classes org.aspectj.runtime The AspectJ runtime classes packaged in a jar file org.aspectj.weaver The AspectJ weaver packaged in a jar file org.eclipse.ajdt.core Non-UI parts of AJDT org.eclipse.ajdt.core.tests AJDT Core tests org.eclipse.ajdt.examples AspectJ examples plug-in org.eclipse.ajdt.mylyn.ui AJDT-Mylyn connector org.eclipse.ajdt.mylyn.ui AJDT-Mylyn connector tests org.eclipse.ajdt.pde.build Headless build plugin. This is used by the headless build process to build AJDT. org.eclipse.ajdt.source Source code for AJDT plug-ins - only populated by the build process. Includes visualizer source code org.eclipse.ajdt.ui.tests AJDT UI Tests org.eclipse.ajdt.ui The AJDT UI plug-in org.eclipse.aspectj The branding plug-in org.eclipse.contribution.visualiser The Visualiser plug-in org.eclipse.contribution.visualiser.tests Visualiser tests org.eclipse.contribution.weaving.jdt JDT Weaving plugin. This plugin contains zips of the Equinox Aspects project that is unzip and added to the update site during the build process. AJDT 1.6+ org.eclipse.contribution.weaving.source JDT Weaving plugin source code. AJDT 1.6+ org.eclipse.contribution.xref.core The Cross References plug-in (non-UI) org.eclipse.contribution.xref.core.tests Tests for the above org.eclipse.contribution.xref.source The Cross References source code. AJDT 1.6+ org.eclipse.contribution.xref.ui The Cross References UI plug-in org.eclipse.contribution.xref.ui.tests Tests for the above Features org.eclipse.ajdt-feature The AJDT feature org.eclipse.contribution.weaving-feature Eclipse Weaving service feature (includes JDT Weaving). AJDT 1.6+ org.eclipse.contribution.xref-feature The Cross References feature org.eclipse.aspectj.feature-tests The test feature/td&gt; Other UpdateSite Non-Java project used to build an update site
 
 
<br>
 
 
=== What do the version numbers mean? ===
 
 
Each Eclipse point release has a corresponding AJDT point release. Eclipse 3.1 requires AJDT 1.3, Eclipse 3.2 requires AJDT 1.4, Eclipse 3.3 requires AJDT 1.5, Eclipse 3.4 requires AJDT 1.6, and Eclipse 3.5 requires AJDT 1.7. Future releases are expected to follow the same numbering system.
 
 
In the CVS repository, each point release of AJDT has its own branch. To do development on a particular version, you must check out the appropriate branch. See How can I connect the AJDT CVS repository? and I am looking for the AJDT branch 1.X in the CVS repository, but I can't find it. What gives? for more details/p&gt;
 
 
<br>
 
  
 
=== How can I connect the AJDT CVS repository and download? ===
 
=== How can I connect the AJDT CVS repository and download? ===
  
Use the following credentials to connect to the repository anonymously: connection type: pserver user: anonymous password: &lt;blank&gt; host: dev.eclipse.org path: /cvsroot/tools If you are connecting to the repository from Eclipse, do the following: Start with a clean workspace under Eclipse 3.3, 3.4, or 3.5 Open the CVS Repository Exploring perspective. Right-click on the CVS Repositories view. Click “New” &gt; “Repository Location”. Fill in the blanks using the above credentials. Click “Finish”. Use the CVS Repositories view to navigate to HEAD/org.eclipse.ajdt/AJDT_src.
+
Use the following credentials to connect to the repository anonymously:  
 +
+ connection type: pserver  
 +
+ user: anonymous  
 +
+ password: ''blank''
 +
+ host: dev.eclipse.org
 +
+ path: /cvsroot/tools  
  
<br> I am looking for the AJDT branch 1.X in the CVS repository, but I can't find it. What gives? Each point version of AJDT has its own branch in the CVS repository. It may not be initially visible if you are browsing the repository through Eclsipe.  
+
Note that this may not be necessary if you are using one of the team project set files above.
  
To discover a branch, do the following:
+
=== Launching AJDT ===
  
Right-click on the org.eclipse.ajdt Select “Configure Branches and Versions...” In the dialog that opens navigate to AJDT_src/org.aspect.ajde/.project Various tags should appear in the right hand side of the dialog Press “Add Checked Tags”, then “OK” Back in the CVS Repositories view you should now be able to navigate to Branches/ajdt1_6/org.eclipse.ajdt ajdt1_6/AJDT_src How do I setup an AJDT development environment in Eclipse? There are three stages to this: building AJDT, running the correctness tests, and creating an Eclipse update site. The first two stages are sufficient for most purposes.
+
+ Create a file called ''config.ini'' and save it somewhere in your workspace
 +
+ Add the following contents to the file:
  
=== Building AJDT ===
+
osgi.framework.extensions=org.eclipse.equinox.weaving.hook
 +
 +
aj.weaving.verbose=true
 +
org.aspectj.weaver.showWeaveInfo=true
 +
org.aspectj.osgi.verbose=true
  
Many of the plugins which implement AJDT contain aspects, and so are AspectJ projects themselves. This means that you first need to install a recent build of AJDT into your development environment from the update site or zip file.  
+
The first line ensures that the weaving service is properly hooked into the osgi runtime and the next three lines adds extra logging information to the console.
  
Note also that in order to build AJDT from source you will probably need to increase the memory available to Eclipse. This is typically done by passing something like “-vmargs -Xmx512m” to the Eclipse launcher.  
+
+ Create a new ''Eclipse Application'' launch configuration.
 +
+ Go to the ''Plugins'' tab
 +
+ In the ''Launch with'' drop down, select ''plugins selected below only''
 +
+ In the list box below, find ''org.eclipse.equinox.weaving.aspectj''
 +
+ Change ''auto-start'' to ''true'' for that bundle
 +
+ In the ''Configuration'' tab, select ''Use an existing config.ini as a template''
 +
+ Choose the config.ini you created above.
 +
+ Click ''Run''
  
See How can I connect the AJDT CVS repository? for instructions on how to download the projects from CVS.  
+
If weaving is enabled, you should see the following lines in your console view soon after launching:
 +
[org.eclipse.equinox.weaving.hook] info adding AspectJ hooks ...
 +
[org.eclipse.equinox.weaving.aspectj] info Starting AspectJ weaving service ...
  
If you are using Eclipse 3.5 you now need to switch to the “ajdt1_7” branch in CVS. See I am looking for the AJDT branch 1.X in the CVS repository, but I can’t find it. What gives? for information on how to discover this branch.  
+
After that, you should see many more weave-info messages as the JDT Weaving service spits out weaving messages to the console. If you do not see these messages, then JDT Weaving is not enabled. It is possible to do some meaningful development work with AJDT with JDT weaving disabled, but some tests will fail and you will not be able to take advantage of AJDT's integration with JDT.
  
Eclipse 3.4 uses HEAD.
+
== Launching AJDT Tests ===
  
If you are using Eclipse 3.3 you need to switch to the “ajdt1_5” branch instead.  
+
There are three top-level test projects:
 +
+ ''org.eclipse.ajdt.core.tests'': the AJDT core tests
 +
+ ''org.eclipse.ajdt.ui.tests'': the UI tests for AJDT, the visualizer, and the cross references view
 +
+ ''org.eclipse.contribution.weaving.jdt'': the Weaving tests for the JDT weaving service
  
If you are using Eclipse 3.2 you need to switch to the “ajdt1_4” branch instead. Note that AJDT 1.4 is only lightly supported now (i.e., there is no ongoing development and only major bugs will be fixed).
+
To run these tests, create a new ''JUnit Plugin Test'' debug configuration and choose one of the projects above. Then follow the instructions in the ''Launching AJDT'' section to ensure that JDT weaving is enabled when running your tests.
 
+
Select the following projects, right-click and select “Check out” from the context menu:
+
 
+
org.aspectj.ajde, org.aspectj.runtime, org.aspectj.weaver, org.eclipse.ajdt.core, org.eclipse.ajdt.examples, org.eclipse.ajdt.ui, org.eclipse.contribution.visualiser, org.eclipse.contribution.xref.core, org.eclipse.contribution.xref.ui, org.eclipse.contribution.weaving.jdt. Eclipse will build the projects as you import them, after which should you be ready to run the plugins inside Eclipse:
+
 
+
Switch to the Java Perspective if you are not already in it... From the run menu select “Run...” For Eclipse 3.4, choose AJDT 1.6 Weaving For Eclipse 3.5, choose AJDT 1.7 Weaving Click “Run”. The reason for using predefined launchers is that in order to enable JDT Weaving, a custom config.ini is required. If weaving is not enabled at startup or if there are any other problems with the runtime workspace, open up the custom config.ini (org.eclipse.contribution.weaving.jdt/config.ini) and make sure the entries align with your version of Eclipse. You may need to edit the version number on the osgi.bundles line. If you continue to have problems, please send a message to the mailing list. Running the correctness tests  
+
 
+
The next step is to add the test projects. These can be used to verify that everything is okay with your environment and configuration, plus of course to verify the integrity of any changes you might make. Switch back to the CVS perspective and check-out the following projects:
+
 
+
org.eclipse.ajdt.core.tests org.eclipse.ajdt.ui.tests org.eclipse.ajdt.ui.visual.tests org.eclipse.contribution.visualiser.tests org.eclipse.contribution.xref.core.tests org.eclipse.contribution.xref.ui.tests org.eclipse.contribution.weaving.tests Note that since many of these tests will only pass if JDT Weaving to be enabled, special launch configurations are provided:
+
 
+
All Weaving Tests---runs the JDT Weaving tests AllUITests_MaxPermSize---runs the AJDT UI tests AllCoreTests No UI---runs the core tests Some UI Tests---runs a sub-set of the UI tests as specified in the java file SomeUITests.java. Edit this file to run any sub-set of the UI tests. Some Random Test case---allows you to run any single test case of AJDT. Edit this launch configuration to specify a project and a test case inside of it. Useful if you are checking only a single test, but don't want to generate a new, custom launch config for it. If you have any problems with the launch configurations, please send a note to the mailing list.  
+
  
 
=== Trouble Shooting ===
 
=== Trouble Shooting ===
  
If you are having problems starting your runtime workspace or running the tests, specifically, if Eclipse is in an infinite restart loop (see (Bug 235006), then try the following:
+
If you are having problems starting your runtime workspace or running the tests, specifically, if Eclipse is in an infinite restart loop, see {{bug|235006}}.
  
Edit org.eclipse.contribution.weaving.jdt/config.ini and comment the line: osgi.framework.extensions=org.eclipse.equinox.weaving.hook Run Eclipse (this will run Eclipse with JDT Weaving disabled). Some tests will fail and some functionality will not work, but it is possible to test some things in this mode. Shut down Eclipse Uncomment the line from config.ini Restart Eclipse Now you&amp;srquo;re ready to start enhancing the plugins by adding to or extending the code in your projects - just use run (or debug) to try out your changes. When you have a patch to submit to the project, go to the “Team&amp;lrquo; item in the project context menu and select “Create Patch...”. Naturally the correctness tests should also be run, and new tests written to accompany fixes or new features.  
+
Ask any more questions on the AJDT mailing list. We are happy to help out.
  
 
=== How can I package my sample code for contribution to the examples plug-in? ===
 
=== How can I package my sample code for contribution to the examples plug-in? ===
  
The org.eclipse.ajdt.examples plugin contains various sample projects which are made available under the Examples category of the New wizard, from where they can be imported into your workspace as AspectJ projects. It is easy to add new samples to this plugin, as follows:  
+
The ''org.eclipse.ajdt.examples'' plugin contains various sample projects which are made available under the Examples category of the New wizard, from where they can be imported into your workspace as AspectJ projects. It is easy to add new samples to this plugin, as follows:  
 
+
+ Create a jar file containing your source code, and at least one build configuration file. Place this in the archive folder of the examples plugin. + Add an entry to the plugin.xml file for your sample project, by copying one of the existing entries. + Change the src attribute of the import element to refer to your jar file, and change the title, description, pagetitle, and pagedescription property names as appropriate, and add corresponding entries to the plugin.properties file. + Change the build attribute to refer to your default build configuration file. Your project may contain more configurations but the one specified here will be the one used to initially build the project. + Optionally, you can specify an open attribute to the projectsetup element, which refers to a file, such as a README file, which is opened after the project has been imported to the workspace.
+
  
<br>
+
+ Create a jar file containing your source code, and at least one build configuration file. Place this in the archive folder of the examples plugin.
 +
+ Add an entry to the plugin.xml file for your sample project, by copying one of the existing entries.
 +
+ Change the src attribute of the import element to refer to your jar file, and change the title, description, pagetitle, and pagedescription property names as appropriate, and add corresponding entries to the plugin.properties file.
 +
+ Change the build attribute to refer to your default build configuration file. Your project may contain more configurations but the one specified here will be the one used to initially build the project.
 +
+ Optionally, you can specify an open attribute to the projectsetup element, which refers to a file, such as a README file, which is opened after the project has been imported to the workspace.
  
 
=== How can I build tools which extend AJDT? ===
 
=== How can I build tools which extend AJDT? ===

Revision as of 13:50, 31 May 2010

AJDT is changing rapidly and so some of this document may be out of date. If you find anything that is out of date or you have any problems following these instructions, please send a note to the AJDT mailing list. We are a friendly bunch and want to encourage new developers to contribute to AJDT.

There are many ways to contribute to AJDT even if you are not developing code: answering questions (or asking them) on the mailing list, raising bugs and feature requests, submitting documentation and sample programs, and generally being a constructive member of the community. These are all ways you can help AJDT and AspectJ grow. Of course, we also appreciate code contributions.

How can I contribute to the AJDT project?

Your contributions to the AJDT project are strongly welcomed! You can create a patch that fixes a bug or provides an enhancement and submit it to the AJDT developers either as an attachment to a bug in Bugzilla, or as an attachment to a post to the newsgroup or developer mailing list. You can also contribute sample code showing interesting uses of AspectJ, by adding entries to the example plug-in. All contributions must be made available under the terms of the Eclipse website see the Eclipse contribution and participation FAQ. Sorry, but for legal reasons we are unable to accept patches emailed directly to developers, and will normally ask you to resubmit these either via Bugzilla or the mailing list. AJDT development is run as a meritocracy, developers who have a track record of submitting good patches can become committers on the project.

Setting up your workspace for AJDT

You need to start with a version of Eclipse that contains the RCP tools, which can be obtained on the Eclipse downloads page. Many of the plugins which implement AJDT contain aspects, and so are AspectJ projects themselves. This means that you first need to install a recent build of AJDT into your development environment from the update site or zip file.

Although not required, we recommend that you use a version of Eclipse that mirrors the version of AJDT that you are developing for. So, use an Eclipse 3.5 to develop AJDT targeting Eclipse 3.5.

AJDT provides optional Mylyn integration. If the target install of your Eclipse does not contain Mylyn, you will have errors in the org.eclipse.ajdt.mylyn.ui bundle. Unless you are actively developing Mylyn support, you can safely close that bundle.

The next step is to actually check out the source code.


Where will I find the source for AJDT?

AJDT source is held in the Eclipse CVS repository under /cvsroot/tools, see the root of the AJDT source tree online. AJDT is organized in subdirectories under org.eclipse.ajdt. The main source tree is in the “AJDT_src” subdirectory. Currently, the HEAD of this directory contains source code targeting Eclipse 3.6 (Helios). There are branches called e35 and e34 targeting Eclipse 3.5 and 3.4 respectively.

The following Team Project Set files are available for Eclipse 3.6 and 3.5. To retrieve the source code for AJDT: + Download the appropriate file + In your Eclipse workspace, select File -> Import -> Team project set + Select the file + Wait...

File:Ajdt35ProjectSet.psf

File:Ajdt36ProjectSet.psf


How can I connect the AJDT CVS repository and download?

Use the following credentials to connect to the repository anonymously: + connection type: pserver + user: anonymous + password: blank + host: dev.eclipse.org + path: /cvsroot/tools

Note that this may not be necessary if you are using one of the team project set files above.

Launching AJDT

+ Create a file called config.ini and save it somewhere in your workspace + Add the following contents to the file:

osgi.framework.extensions=org.eclipse.equinox.weaving.hook

aj.weaving.verbose=true
org.aspectj.weaver.showWeaveInfo=true
org.aspectj.osgi.verbose=true

The first line ensures that the weaving service is properly hooked into the osgi runtime and the next three lines adds extra logging information to the console.

+ Create a new Eclipse Application launch configuration. + Go to the Plugins tab + In the Launch with drop down, select plugins selected below only + In the list box below, find org.eclipse.equinox.weaving.aspectj + Change auto-start to true for that bundle + In the Configuration tab, select Use an existing config.ini as a template + Choose the config.ini you created above. + Click Run

If weaving is enabled, you should see the following lines in your console view soon after launching:

[org.eclipse.equinox.weaving.hook] info adding AspectJ hooks ...
[org.eclipse.equinox.weaving.aspectj] info Starting AspectJ weaving service ...

After that, you should see many more weave-info messages as the JDT Weaving service spits out weaving messages to the console. If you do not see these messages, then JDT Weaving is not enabled. It is possible to do some meaningful development work with AJDT with JDT weaving disabled, but some tests will fail and you will not be able to take advantage of AJDT's integration with JDT.

Launching AJDT Tests =

There are three top-level test projects: + org.eclipse.ajdt.core.tests: the AJDT core tests + org.eclipse.ajdt.ui.tests: the UI tests for AJDT, the visualizer, and the cross references view + org.eclipse.contribution.weaving.jdt: the Weaving tests for the JDT weaving service

To run these tests, create a new JUnit Plugin Test debug configuration and choose one of the projects above. Then follow the instructions in the Launching AJDT section to ensure that JDT weaving is enabled when running your tests.

Trouble Shooting

If you are having problems starting your runtime workspace or running the tests, specifically, if Eclipse is in an infinite restart loop, see bug 235006.

Ask any more questions on the AJDT mailing list. We are happy to help out.

How can I package my sample code for contribution to the examples plug-in?

The org.eclipse.ajdt.examples plugin contains various sample projects which are made available under the Examples category of the New wizard, from where they can be imported into your workspace as AspectJ projects. It is easy to add new samples to this plugin, as follows:

+ Create a jar file containing your source code, and at least one build configuration file. Place this in the archive folder of the examples plugin. + Add an entry to the plugin.xml file for your sample project, by copying one of the existing entries. + Change the src attribute of the import element to refer to your jar file, and change the title, description, pagetitle, and pagedescription property names as appropriate, and add corresponding entries to the plugin.properties file. + Change the build attribute to refer to your default build configuration file. Your project may contain more configurations but the one specified here will be the one used to initially build the project. + Optionally, you can specify an open attribute to the projectsetup element, which refers to a file, such as a README file, which is opened after the project has been imported to the workspace.

How can I build tools which extend AJDT?

See: Developer's guide to building tools on top of AJDT and AspectJ.