<executeJdtProject>

Description

The executeJdtProject task allows you to iterate over an eclipse JDT project and execute ant tasks, e.g. for each source folder or for each output folder. Although it is possible to access the eclipse project information with the getJdtClassPath, getJdtSourcePath and getJdtSourcePath tasks, the recommended way of building JDT projects with ant4eclipse is to use the executeJdtProject task.

With the executeJdtProject task you can iterate over each source or output folder, or you can execute ant tasks once for the jdt project. Within forXYZ subelements, project information are available through several (ant) properties and references that are "passed in" automatically.

Arguments

The executeJdtProject task provides the following arguments:

Nested Elements

To iterate over source or output folders specified in a JDT project, you can define one or more nested elements. Those elements can contain several task calls, similar to a target element. The following elements are defined:

• forEachSourceDirectory: executed for each source directory
• forEachOutputDirectory: executed for each output directory
• forProject: executed once
• forEachRuntimeClasspathEntry: executed for each resolved runtime classpath entry of the project. This element supports the attribute 'reverse' that can be set to true to iterate over the classpath from its bottom to top (i.e. last entry first)

Scoped Properties

Several properties and references are "passed in", so you can access them within the forEachSourceDirectory, forEachOutputDirectory or forProject elements. The following scoped properties are available:

Scoped References

The following scoped references are available:

Example usage

The following example 'executes' a jdt project and echoes the path information for each source directory contained in the project.

<ant4eclipse:executeJdtProject workspace="${workspaceDir}"
                               projectName="${projectName}" >
 
   <!-- echo information for project -->
   <ant4eclipse:forProject>
      <echo>Executing project '${projectName}'...</echo>
      <echo>Boot class path: ${executeJdtProject.boot.classpath}</echo>	
      <echo>Relative runtime class path: ${executeJdtProject.classpath.relative.runtime}</echo>
      <echo>Absolute runtime class path: ${executeJdtProject.classpath.absolute.runtime}</echo>
      <echo>Relative compiletime class path: ${executeJdtProject.classpath.relative.compiletime}</echo>
      <echo>Absolue compiletime class path: ${executeJdtProject.classpath.absolute.compiletime}</echo>
      <echo>Default output directory: ${executeJdtProject.default.output.directory}</echo>
   </ant4eclipse:forProject>
 
   <!-- echo information for each source directory -->
   <ant4eclipse:forEachSourceDirectory>
      <echo>Source folder: ${executeJdtProject.source.directory}</echo>
      <echo>Output folder: ${executeJdtProject.output.directory}</echo>
   </ant4eclipse:forEachSourceDirectory>
 
</ant4eclipse:executeJdtProject>

<getJdtClassPath>

Description

The getJdtClassPath task resolves the class path of an eclipse project. This task reads and parses the .classpath file from the underlying eclipse project. The classpath can be resolved to ant's path type or to a string property. The classpath can be resolved in a relative (to the given workspace) or absolute manner. In case the classpath is resolved to a path type, it can be referenced using the ref-id attribute wherever a class path must be used.

Arguments

The getJdtClassPath task provides the following arguments:

Example usage

The following example resolves the class path of the project simple.java.project to the property classpath. All entries are separated by the default path separator (as defined in java.io.File.separator). You can use the pathSeparator attribute to explicitly specify a character that is used to separate the entries of the classpath::

<ant4eclipse:getJdtClassPath workspacedirectory="${workspace}"
                             projectName="simple.java.project"
		             property="classpath"
                             pathSeparator=";" >

You can also export a classpath to an ant path:

<ant4eclipse:getJdtClassPath pathId="classpath"
                             workspace="${workspace}"
                             projectName="simple.java.project" />

You can use the relative attribute to request a classpath that consists of path entries relative to the specified workspace:

<ant4eclipse:getJdtClassPath property="classpath"
                             workspace="${workspace}"
                             projectName="myProject"
                             pathSeparator=";"
                             relative="true"/>

<getJdtSourcePath>

Description

The getJdtSourcePath task resolves the source folders of an eclipse project. The source folders can be resolved to ant's path-type or to a string property. The path can be resolved in a relative (to the given workspace) or absolute manner.

Arguments

The getJdtClassPath task provides the following arguments:

Example usage

Resolving the source path to an ant path
The following example shows how to resolve the source path of an eclipse JDT project to an ant path:

<ant4eclipse:getJdtSourcePath pathId="sourcepath"
                              workspacedirectory="${workspace}" 
                              projectName="simple.java.project" />

Resolving the source path to an ant property
If you don't want to have the path as a path object but rather as a string Property, you can use the property parameter instead of the pathId argument. If you export the class path to a property, all its entries are separated by the operating systems default path separator (as defined in java.io.File.separator). You can use the pathSeparator attribute to explicitly specify a character that is used to separate the entries of the source path.

<ant4eclipse:getJdtSourcePath property="sourcepath"
                              workspacedirectory="${workspace}" 
                              projectName="simple.java.project" />

Resolving relative pathes: The entries of the paths are absolute paths by default. You can use the boolean relative argument to receive a path that consists of pathentries that are relative to the project directory.

<ant4eclipse:getJdtSourcePath property="sourcepath"
                              workspacedirectory="${workspace}" 
                              projectName="simple.java.project"
                              relative="true" />

<getJdtOutputPath>

Description

The getJdtOutputPath task resolves the output folders of an eclipse project. The output folders can be resolved to ant's Path-type or to a string property. The path can be resolved in a relative (to the given workspace) or absolute manner.

Arguments

The getJdtOutputPath task provides the following arguments:

Example usage

Resolving the default output folder to a path
The following example resolves the default output path of the project simple.java.project to a path with the id defaultoutpath:

<ant4eclipse:getJdtOutputPath workspacedirectory="${workspace}"
                              projectName="simple.java.project"
		              pathId="defaultoutpath" />

Resolving the default output folder to a property
If you don't want to have the path as a path object but rather as a string property, you can use the property parameter instead of the pathId argument:

<ant4eclipse:getJdtOutputPath workspacedirectory="${workspace}"
                              projectName="simple.java.project"
		              property="defaultoutpath" />

If you export the classpath to a property, all its entries are separated by the operating systems default path separator (as defined in java.io.File.separator). You can use the pathSeparator argument to explicitly specify a character that is used to separate the entries of the classpath.

Resolving a specific output folder to a property
The following example shows how to resolve the output folder for a specific source folder (e.g. 'src2'):

<ant4eclipse:getJdtOutputPath workspacedirectory="${workspace}"
                              projectName="simple.java.project"
		              property="outpath" 
                              resolve="forSourceFolder"
		              sourceFolder="src2" />

<installedJREs>

Description

The installedJREs type allows you to define several Java Runtime Environments (JREs) that are available in your build environment. Ant4Eclipse uses these definitions to resolve the so called Java System Library that is part of each JDT-based project. To define a JRE, you just have to provide a name and the path to the JRE. Ant4Eclipse automatically detects the version of the defined JRE as well as the corresponding JARs. It is also possible to define a default JRE. If you haven't chosen a specific JRE in the build path of your project, the default JRE will be taken.

Note: Please make sure that your JREs have the same names as defined in your eclipse IDE (Window->Preferences..., Java->Installed JREs). Otherwise Ant4Eclipse may is not able to resolve the JRE System Library of a given project.

Arguments

The installedJREs datatype provides the following arguments:

Nested Elements

A JRE must be defined using the nested jre element that allows the following arguments:

Example usage

Let's say you're generally using the following VM's in your Eclipse environment (the VM's are configured within Eclipse under Preferences->Java->Installed JREs):

• JRE 1.4 named as JDK_1_4 (C:\jdks\jdk1.4.2)
• JRE 1.5 named as JDK_1_5 (C:\jdks\jdk1.5.0)
• JRE 1.6 named as JDK_1_6 (C:\jdks\jdk1.6.0)

Now you have JRE 1.4 as the default one but some projects do require 1.5 or 1.6. This can be configured using the following setup:

<ant4eclipse:installedJREs default="JDK_1_4">
    <jre id="JDK_1_4" location="C:\jdks\jdk1.4.2"/>
    <jre id="JDK_1_5" location="C:\jdks\jdk1.5.0"/>
    <jre id="JDK_1_6" location="C:\jdks\jdk1.6.0"/>
  </ant4eclipse:installedJREs>

That would make the JDKs JDK_1_5 and JDK_1_6 available for projects that have the corresponding org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/<id> entry in their .classpath file and JDK_1_4 available for projects that
have the org.eclipse.jdt.launching.JRE_CONTAINER on their classpath.

<userLibraries>

Description

The userLibraries type allows you to define pathes from an eclipse user librariies configuration. This is necessary if you use user libraries in a class path that must be resolved by ant4eclipse.

This type reads an exported user libraries definition file and creates an appropriate path instance for each defined library, containing all pathes of the library. The created path instances gets an id assigned that follows the naming schema 'org.eclipse.jdt.USER_LIBRARY/name of the library'.

To use this type, you first have to export the userdefined libraries from eclipse: to do so, use the Export..."-Feature in the preference dialog ("Window->Preferences...", then "Java->Build Path->User Libraries"). The exported file can easily included in your buildfile by using this type.

This way these entries can be resolved and used by the other Ant4Eclipse tasks.

Arguments

The userLibraries datatype provides the following arguments:

Example usage

To import user libraries file 'myUserLibraries.xml' that has been exported by eclipse previously:

<ant4eclipse:userLibraries userlibraries="${basedir}/../myUserLibraries.xml"/>

<buildJdtProject>

Description

This macro builds an Eclipse Java (JDT) project. It reads all informations needed to build the project (classpath, project directory structure, compiler settings etc) from the standard eclipse configuration files like .classpath and .settings-files. The project is compiled using the Eclipse java compiler.

Important: This task is implemented as an Ant macro. To use this task, you have to import the file 'a4e-jdt-macros.xml' in your build file.

Arguments

The buildPlugin task provides the following arguments:

A note on compiler settings: You should either use defaultCompilerOptionsFile or targetLevel/sourceLevel. If you both the defaultCompilerOptionsFile takes precedence over the targetLevel/sourceLevel-argument.

Lifecycle hooks

To allow the user of ant4eclipse to add additional build steps to the build process, the buildJdtProject macro defines the following lifecycle hooks that are implement as macro elements.

Scoped properties

The following scoped properties are available within the lifecycle hooks:

Scoped references

The following scoped references are available:

Example usage

The following example builds the jdt project with the project name 'example-project'. It will use the java version 1.5 if there is no project specific compiler settings file inside the project:

<buildJdtProject workspaceDirectory="${workspaceDirectory}" 
  projectName="example-project"
  targetLevel="1.5"/>

This example uses the jdtProjectFileSet in the finish phase to build a jar containing the project's classes that have been built:

<buildJdtProject workspaceDirectory="${workspaceDirectory}" 
  projectName="example-project"
  targetLevel="1.5">
  <finish>
    <jar destfile="c:/example-project.jar">
      <ant4eclipse:jdtProjectFileSet
        workspaceDirectory="${workspaceDirectory}"
        projectName="${buildJdtProject.project.name}"/>
    </jar>
  </finish>		
</buildJdtProject>

<jdtClassPathLibrary>

Description

The jdtClassPathLibrary datatype can be used to define class path libraries (aka class path containers).

Note: Registering class path libraries manually should be used as the last resort to define class path libraries.

Arguments

The jdtClassPathLibrary datatype provides the following arguments:

Nested Elements

You can use any file resource collection to define a class path library. Please take a look at ant's documentation for further information about file resource collections.

Example usage

The following example defines a class path library named 'myClassPathLibrary':

<ant4eclipse:jdtClassPathLibrary name="myClassPathLibrary">
  <fileset dir="D:/test" />
</ant4eclipse:jdtClassPathLibrary >

The following examples defines the class path library 'org.eclipse.jdt.junit.JUNIT_CONTAINER/3':

<ant4eclipse:jdtClassPathLibrary name="org.eclipse.jdt.junit.JUNIT_CONTAINER/3">
  <fileset dir="C:/eclipse-3.5/plugins/org.junit_3.8.2.v20090203-1005"/>
</ant4eclipse:jdtClassPathLibrary >

<jdtClassPathVariable>

Description

The jdtClassPathVariable type allows you to define class path variables. The definition of class path variables is necessary if you want to resolve a JDT project with a class path variable entry.

A class path variable can be added to a project's class path. It can be used to define the location of a JAR file or a directory that isn't part of the workspace.

Arguments

The jdtClassPathVariable type provides the following arguments:

Usage examples

<ant4eclipse:jdtClassPathVariable name="ECLIPSE_HOME" path="/usr/eclipse34" />
<ant4eclipse:jdtClassPathVariable name="MY_VAR" path="/my/path" />
<ant4eclipse:jdtClassPathVariable name="MY_VAR_2" path="/my/path/myjar.jar" />

<jdtProjectFileSet>

Description

The jdtProjectFileSet works like the 'regular' Ant FileSet. It lists all resources from all source and/or output folders of a jdt project. It can be used whereever Ant supports a Resource Collection, for example in the jar or copy tasks.

Arguments

The jdtProjectFileSet type defines the following attributes:

Nested Elements

The jdtProjectFileSet supports include and exclude sub-elements that can be used to specify which resources should (not) be included in the result. Both sub-elements support a name attribute that must be set to the pattern.

Example usage

The following code creates a jar file that contains the contents of all output folders of a project

<jar destfile="r:/my-project.jar">
  <ant4eclipse:jdtProjectFileSet workspaceDirectory="${workspaceDirectory}" 
    projectName="my-project"/>
</jar>

This examples creates a source jar of a project:

<jar destfile="r:/my-project-sources.jar">
  <ant4eclipse:jdtProjectFileSet workspaceDirectory="${workspaceDirectory}" 
    projectName="my-project" includeSourceFolders="true" includeOutputFolders="false"/>
</jar>

Copies all non-java resources from both source and output folders of a project:

<copy todir="c:/resources">
  <ant4eclipse:jdtProjectFileSet workspaceDirectory="${workspaceDirectory}" 
    projectName="my-project" includeSourceFolders="true" includeOutputFolders="true">
    <exclude name="**/*.java"/>
  </ant4eclipse>
</copy>