Revision as of 15:39, 2 January 2014

This wiki discusses the steps to add a new version of Apache Ant to the Eclipse platform. The intended audience is committers, but everyone is free to contribute versions.

How it works

Eclipse consumes Apache Ant from Orbit as a 'normal' Eclipse bundle rather than try to integrate Apache Ant as-is. Below is a quick overview of the process, with the following sections providing more details.

A quick overview of the process:

• Ant is taken from Apache site and converted to the Orbit bundle format.
• A CQ is opened to get legal approval to use the new version
• Once approved, the new version is added to Orbit
• Smokes testing and test builds are done
• Assuming no problems - the platform is updated

Creating the Orbit bundle

The first step is to create the new Orbit bundle that can be used in your workspace (or installed in your host) to test with. This section assumes you are familiar with the terminology of Eclipse bundles, using the PDE tools, testing / running JUnit tests and have read the relevant how-tos from the Orbit wiki about adding / configuring bundles.

The bundle

The best way to see the expected shape of the Ant bundle is simply to look at an older (or current) version used by Eclipse. You can grab an older version from the CVS repository, but you will have to rename it in your workspace (or its name will collide with the new version you are trying to create). At the time of this writing the version used in Eclipse is 1.9.2, so you will want to check out the 1_9_2 branch of Ant from orbit.

Once in your workspace, the bundle will look like the following:

The important parts to note in the bundle are:

• about_files - contain all of the license files directly from Apache
• bin - contains all of the script files from the binary distribution of Apache Ant
• etc - contains all of the styles sheets for Ant tasks
• lib - contains all of the jar files from the binary distribution of Apache Ant
• source-bundle - contains the Orbit-formatted source bundle, whose content come from the source distribution of Apache Ant (more on this later)

The remainder of the files / folders are standard Eclipse bundle files which don't require special mention. Any of them that requires editing will be mentioned in the following sections.

Grab the new Apache Ant version

The first step to creating our new orbit bundle is grabbing the binary and source distributions of Apache Ant.

They can be found on their respective download pages:

• binary distributions
• source distributions

Once you download the two versions, extract them some where convenient. Also take note the Apache download page mentions you might need special steps to extract the distributions due to really long file names.

Create the workspace bundle

With the latest version of Apache Ant acquired and an old version of the Ant bundle to compare to, lets create the new version in our workspace. A note here: it is a good idea to have no other bundles open in you workspace while you are working on Apache Ant. The reason for this is that Apache Ant is a low-level bundle and bringing it into your workspace / editing it seems to cause confusion in your target platform. So best to just keep all you other bundles closed while you create the new version.

Lets go:

1. Create the org.apache.ant bundle
2. Fill in the MANIFEST.MF information as required. 'Id' is org.apache.ant, 'version' is 1.9.3_qualifier (for example), 'name' is Apache Ant and 'provider' is Eclipse Orbit. Make sure to also externalize these values for translation (you can use the PDE wizard for this).
3. Add a bundle dependency on org.eclipse.osgi in the MANIFEST.MF (do not include version constraints on it)
4. Add a BREE of J2SE-1.5 in the MANIFEST.MF and click the update classpath settings link.
5. Copy the /about.html file from the old version to the new version. Open it and change the date to the current date (update the copyright as needed).
6. Copy all of the files from the .settings folder of the old version into the .settings folder of the new version
7. Create /about_files, /bin, /etc, /lib, /source-bundle and /source-bundle/libsrcfolders
8. Copy the /MANIFEST.MF/eclipse.inf file from the old version to the new version
9. Edit the build path properties and set the default output folder to be org.apache.ant/bin-generated
10. Copy the build.properties from the old version to the new version (update the copyright as needed)

Thats it! At this point we have the complete bundle shape, all that remains is to add the updated Ant libraries / files.

Update the binary parts

First we will start with updating the binary parts of the bundle. This involves copying files from the binary distribution of Ant. To simplify the steps I will assume the root of the binary distribution of Apache Ant to be /binary. So for example when I talk about copying a file from the bin folder I will refer to it like: /binary/bin.

Lets go:

1. Copy all of the files from the /binary/bin folder to the /bin folder of the project. These are a bunch of *.sh, *.pl, *.py, *.bat and *.cmd files.
2. Copy all of the *.xsl files from /binary/etc to the /etc folder of the project. DO NOT copy the jar file.
3. Copy the /binary/etc/checkstyle folder (and all of its contents) to the /etc folder of the project.
4. Copy all of the jar files from /binary/lib to the /lib folder of the project. DO NOT copy any of the pom files or anything else, only the jar files.
5. Open the MANIFEST.MF editor and go to the Runtime page. Now using the Add... button in the Classpath section, add all of the jar files from the /lib folder to the classpath. Once that is done, use the Add... button in the Exported Packages section to export all of the org.apache.tools.* packages.
6. Now open the .classpath file to confirm it contains all of the library entries like: <classpathentry exported="true" kind="lib" path="lib/ant.jar"/>
7. Open the project Java build pat properties and go to the Libraries tab. Confirm all of the libraries are there. For each one of the libraries we want to make sure the source path is correct - to do so expand each library and edit the source attachment value. Each value is from the workspace and points to /org.apache.ant/source-bundle/libsrc. After you are done setting the source paths, go to the Order and Export page and confirm all of the Ant libraries are checked (if not, do so).
8. Reopen (or go to) the MANIFEST.MF editor and on the overview page hit the update classpath settings link. Now open the .classpath file and confirm you have all of the library entries like the following: <classpathentry exported="true" kind="lib" path="lib/ant.jar" sourcepath="source-bundle/libsrc"/>

If everything checks out with the manifest and classpath, then we are done. If not go back through the steps to confirm they are all done.

Update the source parts

Creating the CQ

Testing and Test builds