Difference between revisions of "AJDT Developer FAQ"

Revision as of 14:12, 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.

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

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> Other UpdateSite Non-Java project used to build an update site

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>

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 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” > “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.

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.

To discover a branch, do the following:

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.

Building AJDT

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.

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.

See How can I connect the AJDT CVS repository? for instructions on how to download the projects from CVS.

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.

Eclipse 3.4 uses HEAD.

If you are using Eclipse 3.3 you need to switch to the “ajdt1_5” branch instead.

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

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

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:

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

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.