<hasNature>

Description

The hasNature condition is an Ant condition that can be used to check if a project has a specific nature. Natures are used to assign specific behaviour to Eclipse projects. Java projects for example have the nature 'org.eclipse.jdt.core.javanature'.

The hasNature condition can be used with ant's native condition and waitfor tasks (see Condition Task). It can also be used with the if-task from the ant-contrib project to create build steps that check whether a project has some specific nature.

Arguments

The hasNature datatype provides the following arguments:

Example usage

The following example checks if the project with the name 'simple.java.project' has the nature 'org.eclipse.jdt.core.javanature':

<antcontrib:if>
    <ant4eclipse:hasNature workspacedirectory="${workspace}"
                           projectname="simple.java.project"
                           nature="org.eclipse.jdt.core.javanature" />
   <antcontrib:then>
     ...
   </antcontrib:then>
 </antcontrib:if>

<hasBuildCommand>

Description

The hasBuildCommand condition is an Ant condition that can be used to check if an Eclipse project has a specific build command. An Eclipse project can have several build command assigned to it. Those build commands are normally executed after a file has been saved (incremental build) or when a full build is initiated (Project -> Clean...) (manual build). A typical java project contains the org.eclipse.jdt.core.javabuilder which invokes the default Eclipse compiler on java sources.

If you would like to write build steps that depend on specific build commands, you can use the hasBuildCommand condition which checks if a project has a specified buildCommand. The hasBuildCommand-condition can be used with ant's native condition and waitfor tasks (see Condition Task). It can also be used with the if-task from the ant-contrib project to create build steps that check whether some specific build commands exist or not.

Arguments

The hasBuildCommand datatype provides the following arguments:

Example usage

The following example checks if the project with the name 'simple.java.project' has the build command 'org.eclipse.jdt.core.javabuilder':

<antcontrib:if>
  <ant4eclipse:hasBuildCommand workspacedirectory="${workspace}"
                               projectname="simple.java.project"
                               buildcommand="org.eclipse.jdt.core.javabuilder" />
  <antcontrib:then>
    ...
  </antcontrib:then>
</antcontrib:if>

<executeBuildCommands>

Description

The executeBuildCommands task allows you to iterate over one or more build commands that are defined in your eclipse project.

Arguments

The executeBuildCommands task provides the following arguments:

Example usage

The following example iterates over all build commands defined in the eclipse project 'simple.java.project':

<ant4eclipse:executeBuildCommands workspacedirectory="${workspace}"
			          projectname="simple.java.project">
 
	<org.eclipse.jdt.core.javabuilder>
		...
	</org.eclipse.jdt.core.javabuilder>
</ant4eclipse:executeBuildCommands>

<getProjectDirectory>

Description

Returns the project directory for a given eclipse project. Since ant4eclipse supports the usage of linked projects, it is necessary in some case to resolve the 'real' path of a project.

Arguments

The getProjectDirectory task provides the following arguments:

Example usage

The following example resolves the absolute path of the the project with the name 'simple.java.project':

<ant4eclipse:getProjectDirectory workspacedirectory="${workspace}"
                                 projectname="simple.java.project"
	                         property="test" />

<workspaceDefinition>

Description

The workspaceDefinition type allows you define a workspace with a custom workspace layout. In eclipse a workspace always has a flat layout (Workspace -> Projects), but many users store there eclipse projects in a hierarchical way within the source code repository. Ant4eclipse directly supports the usage of custom workspace layouts through this datatype.

Many thanks to Mark Riley for submitting the initial patch!

Arguments

The workspaceDefinition datatype provides the following arguments:

Nested Elements

To define a custom workspace layout, you can use one or more nested Directory Sets.

Example usage

The following example defines a workspace that contains projects that can be found in any sub-directory (recursively) of the directory 'D:/tmp':

  <ant4eclipse:workspaceDefinition id="myWorkspace">
    <dirset dir="D:/tmp">
      <include name="**"/>
    </dirset>
  </ant4eclipse:workspaceDefinition>

You can use the workspace definition within the ant4eclipse task by using the 'workspaceId' attribute insead of the 'workspaceDirectory' attribute.

<linkedResourceVariable>

Description

The linkedResourceVariable datatype is an Ant datatype that allows you to specify an environment specific path for a linked resource. Within the eclipse IDE these variables are defined in the preferences dialog (Window -> Preferences..., General -> Workspace -> Linked Resources).

Arguments

The linkedResourceVariable type provides the following arguments:

Usage examples

<ant4eclipse:linkedResourceVariable name="myLinkedResourcesDirectory" location="D:/location" />

<executeProjectSet>

Description

The executeProjectSet task allows you iterate over a set of projects. The project set can be defined using a (comma separated) list of projects or a team project set file.

With the nested forEachProject element you can execute tasks for each project that is defined in the project set. The build order of the contained projects are computed automatically.

Arguments

The executeProjectSet task provides the following arguments:

Nested Elements

To iterate over the projects defined in the executeProjectSet task, 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:

• forEachProject: executed for each project

Scoped properties

Several properties and references are "passed in", so you can access them within the forEachProject element. The following scoped properties are available:

Scoped references

The following scoped references are available:

Example usage

Working with project set files

The following example shows how to iterate over a project set defined by a team project set file (projectSet.psf):

<ant4eclipse:executeProjectSet workspace="${workspace}"
		               teamprojectset="projectSet.psf" >
 
  <ant4eclipse:forEachProject>
    <echo>${executeProjectSet.project.name}</echo>
  </ant4eclipse:forEachProject>
 
</ant4eclipse:executeProjectSet>

The following example only iterates over the java projects of the team project set:

<ant4eclipse:executeProjectSet workspaceDirectory="${workspace}"
		               teamprojectset="projectSet.psf" >
 
  <ant4eclipse:forEachProject filter="(executeProjectSet.org.eclipse.jdt.core.javanature=*)" >
    <echo>${executeProjectSet.project.name}</echo>
  </ant4eclipse:forEachProject>
 
</ant4eclipse:executeProjectSet>

Defining a project set by a list of project names

The following example shows how to iterate over a project set defined by all projects defined in the workspace:

<ant4eclipse:executeProjectSet workspaceDirectory="${workspace}"
		               projectNames="simpleProject, secondProject" >
 
  <ant4eclipse:forEachProject>
    <echo>${executeProjectSet.project.name}</echo>
  </ant4eclipse:forEachProject>
 
</ant4eclipse:executeProjectSet>

Choosing all projects within a workspace

The following example shows how to iterate over a project set defined by all projects defined in the workspace.

<ant4eclipse:executeProjectSet workspaceDirectory="${workspace}"
		               allWorkspaceProjects="true" >
 
  <ant4eclipse:forEachProject>
    <echo>${executeProjectSet.project.name}</echo>
  </ant4eclipse:forEachProject>
 
</ant4eclipse:executeProjectSet>

<getBuildOrder>

Description

The getBuildOrder task computes the order in which projects of a workspace must be built. The task requires either a Team Project Set file containing the projects or a property with a list of project names to be computed. The project set resp. the project names must contain all needed projects. If a project that is referenced by a project listed in the project set or in projectNames is not included, the task will fail. All projects that are needed to compute the build order must exist in the workspace, otherwise the task will fail.

Arguments

The getBuildOrder task provides the following arguments:

Example usage

The following example computes the build order of all the projects contained in the team project set projectSet.psf:

<getBuildOrder workspace="${workspaceDir}"
               teamprojectset="projectSet.psf"
               buildOrderProperty="test" />

<cvsGetProjectSet>

Description

Use the cvsGetProjectSet task to automatically check out all projects defined in a team project set. The cvsGetProjectSet requires the name of a Team Project Set file and a destination directory into which the projects will be checked out. Furthermore you need to specify a username and a password for CVS. Ant4eclipse then checks out all projects listed in the file in the version / from the branch that is mentioned in the file.

Arguments

The cvsGetProjectSet task provides the following arguments:

Example usage

The following example shows how to checkout projects defined in a team project set:

<cvsGetProjectSet cvsUser="myCvsUserId"
                  cvsPwd="myCvsPassword"
                  command="checkout"
                  projectSet="myProjectSet.psf"
                  workspace="${workspace.dir}" />

<svnGetProjectSet>

Description

Use the svnGetProjectSet task to automatically check out all projects defined in a subversion-based team project set. The svnGetProjectSet requires the name of a Team Project Set file and a destination directory into which the projects will be checked out. Furthermore you may need to specify a username and a password for SVN, that depends on your repository. Ant4eclipse will check out all projects listed in the file in the version / from the branch that is speciified in the file.

Arguments

The svnGetProjectSet-Tasks takes a command argument that detemines how a project will be received from the CVS repository:

• checkout: Checks out the complete projects from SVN (svn checkout)
• update: Updates the projects: receive/remove changed files only (svn checkout)
• export: Like checkout, but removes the .SVN directories, so the checked out projects have no connection to SVN anymore (svn export)

Setup

1. In order to use the svnGetProjectSet task you must have svn-ant installed, which can be obtained from http://subclipse.tigris.org/svnant.html. Ant4Eclipse is built and tested against the 1.1.0-RC2 version of svn-ant.
2. You'll need to have the jar files shipped with svn-ant in one of your Ant lib-directories (i.e. a directory you'll point ant with "-lib" to). Note: You can not use the classpath elements in the taskdef (see below) for svn-ant since that results in a ClassCastException due to Classloader mismatch.
3. You'll need to add a taskdef element to your build file to make Ant (and Ant4Eclipse) aware of the svn-Task (that is used internally by Ant4Eclipse): <taskdef resource="org/tigris/subversion/svnant/svnantlib.xml"/>

Providers

The svnGetProjectSetTask has been tested with PSF-files exported by the Subclipse and the Subversive plugins. If you'll discover any problems with a PSF file please send us the PSF file and information which plugin you used to export it (including the plugin's version!)

Examples

The following example shows how to checkout projects defined in a team project set. Note that it is required to have ant4eclipse.jar as well as the jars from the svn-ant-Project in your classpath (see "Setup" above):

<project name="..." default="...">
 
  <!-- define Ant4Eclipse tasks -->
  <taskdef uri="antlib:org.ant4eclipse" resource="org/ant4eclipse/antlib.xml" />
 
  <!-- define svnant tasks -->
  <taskdef resource="org/tigris/subversion/svnant/svnantlib.xml" />
 
  <target name="checkout-psf">
    <!-- Check out the contents of "myProjectSet.psf" into the directory "${workspace.dir}" -->
    <ant4eclipse:svnGetProjectSet username="myCvsUserId"
                                  password="myCvsPassword"
                                  command="checkout"
                                  projectSet="myProjectSet.psf"
                                  workspace="${workspace.dir}">
 
  </target>
</project>

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

<buildPlugin>

Description

This macro builds an eclipse plug-in project. It reads the information from the MANIFEST and the build.properties file and builds the plugin according to these settings.

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

Arguments

The buildPlugin task provides the following arguments:

Lifecycle hooks

To allow the user of ant4eclipse to add additional build steps to the plug-in build, the buildPlugin 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 plug-in project with the project name 'example-bundle'. The built bundle will reside in 'd:/plugins/plugins'.

<buildPlugin workspace="${workspace}"
             projectName="example-bundle"
             targetPlatformId="target.platform"
             destination="d:/plugins" />

<buildPlugin workspace="${workspace}"
             projectName="example-bundle"
             targetPlatformId="target.platform"
             destination="d:/plugins" >
 
  <generate-sources>
    <!-- add additional build steps here... -->
  </generate-sources>
 
  <post-compile>
    <!-- add additional build steps here... -->
  </post-compile>
 
</buildPlugin>

<buildFeature>

Description

This macro builds an eclipse feature project. It reads the information from the file feature.xml and builds the feature according to these settings.

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

Arguments

The buildFeature task provides the following arguments:

Example usage

The following example builds the feature project with the project name 'test.feature'. The built feature will reside in 'd:/plugins'.

<buildFeature workspaceDirectory="${workspace}"
              projectName="test.feature"
              targetplatformid="target.platform"
              destination="d:/plugins" />

<buildProduct>

Description

This macro builds a complete eclipse product. This incorporates the build process for each feature/plugin declared by this product.

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

Arguments

The buildProduct task provides the following arguments:

Lifecycle hooks

To allow the user of ant4eclipse to add additional build steps to the product build, the buildProduct macro defines the following lifecycle hooks that are implement as macro elements. The scope information identifies the properties which are available within this macro define (check out the executeProduct task description for detailed information).

Example usage

The following example builds a product with the project. The built product will be stored into 'd:/my-rcp'.

<buildProduct 
  workspaceDirectory="${workspace}"
  productfile="d:/my-rcp.product"
  targetPlatformId="eclipse-3.4"
  destination="d:/my-rcp" 
  clearDestination="true"
  os="win32"
/>

The next example shows how to add additional build steps to the build process.

<buildProduct 
  workspaceDirectory="${workspace}"
  productfile="d:/my-rcp.product"
  targetPlatformId="eclipse-3.4"
  destination="d:/my-rcp" 
  clearDestination="true"
  os="win32"
>
 
  <deploy>
    <!-- sometimes we just want to add some documentation -->
    <mkdir dir="d:/my-rcp/docs"/>
    <copy todir="d:/my-rcp/docs">
      <fileset dir="V:/my-rcp/docs" includes="**/*"/>
    </copy>
  </deploy>
</buildProduct>

<targetPlatform>

Description

The targetPlatform type can be used to define a PDE target platform. Target platforms are used when working with plugin and feature projects. They define locations where binary, plugins can be found (e.g. an existing eclipse installation).

A target platform may consist of more than one directory. A directory listed in the targetPlatform type has to be the parent directory of the plugins directory that contains the plugins (e.g. if you would like to include the plugins of your eclipse distribution, you would add "c:/eclipse" (or whereever you've installed Eclipse) as a directory and not "c:/eclipse/plugins").

You can use the target platform within the ant4eclipse tasks by refering to it with the target platform id.

Arguments

The targetPlatform type provides the following arguments:

Nested elements

Each directory you want to include in your platform definition must be added using a location element.

Example usage

The following example creates a target platform defintion that consists of one directory. The defintion can be referenced via it's id 'eclipse-3.5':

<project name="..." default="...">
 
  <ant4eclipse:targetPlatform id="eclipse-3.5">
    <location dir="c:/eclipse-3.5" />
    <location dir="d:/addtionalLocation" />
  </ant4eclipse:targetPlatform> 
 
 </project>

<executePluginProject>

Description

The executePluginProject task allows you to iterate over the plug-in libraries defined in a PDE project.

Arguments

The executePluginProject 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:

• forPluginLibrary: executed for each plug-in library
• forProject: executed once

Scoped Properties

Several properties and references are "passed in", so you can access them within the forPluginLibrary or forProject elements. You can access the following scoped properties:

Example usage

The following example shows the usage of the executePluginProject task:

<ant4eclipse:executePluginProject workspaceDirectory="${workspaceDirectory}"
                                  projectName="${projectName}" >
 
  <!-- execute once for the project -->
  <ant4eclipse:forProject>
    ...
  </ant4eclipse:forProject>
 
  <!-- execute for each library (except the 'self' library) -->
  <ant4eclipse:forEachPluginLibrary filter="(library.isSelf=false)">
    ...
  </ant4eclipse:forEachPluginLibrary>
 
  <!-- execute for each library (only for the 'self' library) -->
  <ant4eclipse:forEachPluginLibrary filter="(library.isSelf=true)">
    ...
  </ant4eclipse:forEachPluginLibrary>
 
</ant4eclipse:executePluginProject>

<executePluginLibrary>

Description

The executePluginLibrary allows you to iterate over the source and output entries of plug-in libraries defined in the build.properties file of a PDE project.

Arguments

The executePluginLibrary task provides the following arguments:

Nested Elements

To iterate over source or output entries specified in the build.properties file, you can define one or more nested elements. Those elements can contain several task calls, similar to an ant target element. The following elements are defined:

• forEachSourceDirectory: executed for each source directory
• forEachOutputDirectory: executed for each output directory
• ForLibrary: executed once for the library

Scoped Properties

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

Example usage

The following example shows the usage of the executePluginProject task:

<ant4eclipse:executePluginLibrary workspace="${workspaceDirectory}"
		                  projectname="${project.name}"
		                  libraryname="${library.name}">
 
  <!-- execute for each output directory -->
  <ant4eclipse:forEachOutputDirectory>
    ...
  </ant4eclipse:forEachOutputDirectory>
 
  <!-- execute for each source directory -->
  <ant4eclipse:forEachSourceDirectory>
    ...
  </ant4eclipse:forEachSourceDirectory>
 
</ant4eclipse:executePluginLibrary>

<pdeProjectFileSet>

Description

The pdeProjectFileSet type can be used to define plug-in project relative file sets.

Note: The bundle root ('.') will be resolved to a directory with the name '@dot'.

Arguments

The pdeProjectFileSet type defines the following attributes:

Example usage

<copy todir="${destination}"
      overwrite="true">
 
  <ant4eclipse:pdeProjectFileSet workspace="${workspaceDirectory}"
                                 projectname="${project.name}"
                                 includes="META-INF,.,OSGI-INF"
                                 excludes="META-INF/todos.txt" />
</copy>

<executeFeature>

<platformConfiguration>

Description

The platformConfiguration type can be used to define a PDE platform configuration. Platform configurations are used in conjunction with target platforms. They define the system platform to resolve a given target platform for. As the default the system configuration of the machine where the ant4eclipse build is running is used. If you want to execute cross-platform build, you have to specify the platform configuration explicitly.

You can use the platform configuration within the ant4eclipse tasks by refering to it with the platform configuration id.

Arguments

The platformConfiguration type provides the following arguments:

Example usage

The following example creates a platform configuration. The defintion can be referenced via it's id 'win32.win32.x86':

<project name="..." default="...">
 
  <ant4eclipse:platformConfiguration id="win32.win32.x86"
                                     windowingSystem="win32"
                                     operatingSystem="win32"
                                     architecture="x86" />
 
</project>

<executeProduct>

Description

The executeProduct task allows you to iterate over all plug-ins and features specified within a product file. This build process is probably the most comfortable way to build an eclipse release since you only need to supply a product description.

Arguments

The executeProduct task provides the following arguments:

Nested Elements

To iterate over source or output folders specified in a 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:

• forProduct: executes for a product
• forEachFeature: executes for each feature
• forEachPlugin: executes for each plugin

Scoped Properties

Several properties and references are "passed in", so you can access them within these scoped elements. Following scoped properties are available:

Example usage

The following example shows the usage of the executeProduct task:

<ant4eclipse:executeProduct 
  workspaceDirectory="${workspaceDirectory}"
  product="my.product" 
  os="win32"
  targetPlatformId="K:/my-platform"
>
 
  <!-- execute once for the product -->
  <ant4eclipse:forProduct>
    ...
  </ant4eclipse:forProduct>
 
  <!-- execute for each included feature -->
  <ant4eclipse:forEachFeature>
    ...
  </ant4eclipse:forEachFeature>
 
  <!-- execute for each included plugin -->
  <ant4eclipse:forEachPlugin>
    ...
  </ant4eclipse:forEachPlugin>
 
</ant4eclipse:executeProduct>

<patchFeatureManifest>

<getPythonPath>

Description

The getPythonPath task resolves the python path of an eclipse project. This task reads and parses the python related project artefacts in order to access these pathes. The pythonpath can be resolved to ant's path type or to a string property. The pythonpath can be resolved in a relative (to the given workspace) or absolute manner. In case the pythonpath is resolved to a path type, it can be referenced using the ref-id attribute wherever a pythonpath must be used.

Arguments

The getPythonPath task provides the following arguments:

Example usage

The following example resolves the pythonpath of the project simple.python.project to the property pythonpath. 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 pythonpath:

  <ant4eclipse:getPythonPath 
    workspaceDirectory="${workspace}"
    projectName="simple.python.project"
    property="pythonpath"
    ignoreruntime="true"
    pathSeparator=";"
  />

You can also export a pythonpath to an ant path:

  <ant4eclipse:getPythonPath 
    pathId="pythonpath"
    workspaceDirectory="${workspace}"
    ignoreruntime="true"
    projectName="simple.python.project" 
  />

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

  <ant4eclipse:getPythonPath 
    property="pythonpath"
    workspaceDirectory="${workspace}"
    projectName="myProject"
    pathSeparator=";"
    ignoreruntime="true"
    relative="true"
  />

<getPythonSourcePath>

Description

The getPythonSourcePath task resolves the source folders of an eclipse python 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 getPythonClassPath 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 python project to an ant path:

  <ant4eclipse:getPythonSourcePath 
    pathId="sourcepath"
    workspaceDirectory="${workspace}" 
    projectName="simple.python.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 source 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:getPythonSourcePath 
    property="sourcepath"
    workspaceDirectory="${workspace}" 
    projectName="simple.python.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 path entries that are relative to the project directory.

  <ant4eclipse:getPythonSourcePath 
    property="sourcepath"
    workspaceDirectory="${workspace}" 
    projectName="simple.source.project"
    relative="true" 
  />

<pythonContainer>

Description

The pythonContainer type allows to declare python installations where each installation obviously provides an interpreter and a library (the runtime environment).

Arguments

The pythonContainer task provides the following arguments:

Each installation will be declared using a separate child element pyre within that container element:

Currently the following types of python are supported:

• Python (aka CPython)
• IronPython
• Jython

Example usage

  <ant4eclipse:pythonContainer default="cpython-2.5">
    <ant4eclipse:pyre id="cpython-2.5" location="/usr/lib/python/cpython/2.5"/>
    <ant4eclipse:pyre id="cpython-2.6" location="/usr/lib/python/cpython/2.6"/>
  </ant4eclipse:pythonContainer>

<pythonDoc>

Description

The pythonDoc task allows to extract api documentation from python source code. Rather than using the internal documentation tools from python this task uses Epydoc which produces a much nicer document structure. This package is bundled as a library of this ant task so it's not necessary to explicitly perform any kind of installation.

Arguments

The pythonDoc task provides the following arguments:

Example usage

Simple generation of python documentation:

  <ant4eclipse:pythonContainer default="cpython-2.5">
    <ant4eclipse:pyre id="cpython-2.5" location="/usr/lib/cpython/2.5"/>
    <ant4eclipse:pyre id="cpython-2.6" location="/usr/lib/cpython/2.6"/>
  </ant4eclipse:pythonContainer>
 
  <ant4eclipse:pythonDoc 
    runtime="cpython-2.6"
    sourcedir="/users/kasimir/python/sample1/sources"
    destdir="/users/kasimir/python/sample1/apidoc"
  />