Higgins2Ant

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

Introduction

Higgins2ant is an Eclipse plug-in that the Higgins project uses to generate Ant build files which can be used either for developer builds or Automated Builds running on Eclipse build server.

Latest version of higgins2ant is available at Higgins2ant Update Site.

Prerequisites

A number of prerequisites need to be installed on the build machine, as follows:

1. J2SE SDK 1.4.2
2. Eclipse version 3.2 or higher
3. Ant version 1.6.5 or higher

Project Information

Higgins2ant unit consists of several projects which sources could be fould using SVN information below.

SVN Information

Connection Type	Committers	https:// or svn+ssh://
	Anonymous access	http://
Host		dev.eclipse.org
Repository Path		/svnroot/technology/org.eclipse.higgins

Project	Module Location	Eclipse PSF	ViewSVN
higgins2ant.feature	/trunk/builds/higgins2ant.feature	project.psf	viewsvn
		projectWithDeps.psf
higgins2ant	/trunk/builds/higgins2ant	project.psf	viewsvn
		projectWithDeps.psf
higgins2ant.core	/trunk/builds/higgins2ant.core	project.psf	viewsvn
		projectWithDeps.psf
higgins2ant.pde	/trunk/builds/higgins2ant.pde	project.psf	viewsvn
		projectWithDeps.psf
higgins2ant.site	/trunk/builds/higgins2ant.site	project.psf	viewsvn
		projectWithDeps.psf

General Information

Higgins2ant plug-in generates following set of files:

• build.xml - ant build file
• dependencies.xml - xml file contains all project's dependencies in the format used by Automated Builds
• project.psf and projectWithDeps.psf - team project sets to import the project and its dependencies respectively into Eclipse IDE workspace

Note: Since version 1.0.0.5 Higgins2ant automatically re-generatie build files when either project's classpathes, dependencies or hierarchy has been changed.

build.xml

Higgins2ant generates ant build files which contains all required targets to build the project. Generated build.xml files can be used by both developers to build the project on local computer and automated build scripts running on build server. Actual set of targets generated depends on the type of the project. Latest version supports generation of build.xml files for the following types of projects from the Eclipse IDE:

• Generic Java Project
• Eclipse Plug-in Project
• Eclipse Feature Project
• Eclipse Update Site Project

In order to extend capabilities of generated build files Higgins2ant plug-in automatically imports all build files in the project directory which contains <?eclipse.ant.import?> processing instruction as the first child. This allow to create any project specific targets in separated build file manually and they will be available to call from the generated build.xml

Generated build.xml file assumes that all output is placed in ./build subfolder of the project folder. Each target uses their own output subfolder of the build folder. In general the structure of the build folder is defined as follows:

• ./build/bin - output folder for binaries (class files).
• ./build/lib - output folder for jar files.
• ./build/doc - output folder for javadocs.
• ./build/plugins - output folder for Eclipse plug-ins.
• ./build/features - output folder for features.
• ./build/temp.dir - temporary folder used to build plug-ins and features.

Java Project's targets

For the generic Java projects following set of targets are generated:

• build - the default target which builds the source code of the project and subprojects. Output folder for project's binaries is build/bin.
• jar - the target to pack project's binaries. Creates projectName_version.jar file in the build/lib folder.
• javadoc - the target to create javadoc for the project. Uses build/doc folder as output destination.
• clean - the target to clean build output folder of the project. This target deletes all files and subdirectories of build folder, including build itself.
• cleanall - the target to clean build folders for the project and its dependencies.
• copy.libs the target to copy all project required libraries to user defined folder. In order to use this target toDir parameter should be specified.
• copy.jar - the target to copy jar (project's jar) to user defined folder. In order to use this target toDir parameter should be specified.
• copy.all.jars - the target to copy all jars (project's jar and all jars of its dependencies) to user defined folder. In order to use this target toDir parameter should be specified.
• -save.build.properties - the helper target. This target is not used directly by any target in the generated build.xml file unless build.properties.file property is explicitly defined. This can be used by targets in an extension build files to avoid a lot of recursive target calls at calls to <build>, <jar>, <copy.jar> and <copy.all.jars> targets.

Below is an example of an extension build file which shows how to use <copy.libs>, <copy.all.jars>, <-save.build.properties> targets.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse.ant.import?>
 
<project name="org.eclipse.higgins.rpps.web.builwar" default="war">
    <import file="build.xml"/>
 
    <path id="axis.classpath">
        <path refid="org.eclipse.higgins.rpps.web.classpath"/>
    </path>
 
    <target name="init-war">
    	<property name="build.dir.war" value="${build.dir}/war"/>
 
	<!-- define the name of the property file to save build properties -->
    	<property name="build.properties.file" value="${build.dir}/build.properties"/>
    	<mkdir dir="${build.dir.war}"/>
 
	<!-- save build properties -->
       	<antcall target="-save.build.properties"/>
    </target>
 
    <target name="copywardepprojects">
        <antcall target="copy.all.jars">
            <param name="toDir" value="${build.dir}/warlibs"/>
        </antcall>
        <antcall target="copy.libs">
            <param name="toDir" value="${build.dir}/warlibs"/>
        </antcall>
    </target>
 
    <!-- build war-->
    <target name="war" depends="init-war,build,copywardepprojects">
    	<war destfile="build/war/rpps-axis.war" webxml="web/WEB-INF/web.xml" duplicate="preserve">
	    <!-- Stuff in WebContent-->
	    <fileset dir="web/" excludes="**/web.xml"/>
	    <!-- Classes -->
	    <classes dir="${build.dir.bin}" excludes="**/plugin/**,**/*.jar,**/*.tar,**/*.zip,**/*.war"/>
	    <lib dir="${build.dir}/warlibs">
	        <include name="*.jar"/>
	        <exclude name="servlet-api.jar"/>
	        <exclude name="axis-ant-1.4.jar"/>	
	        <exclude name="axis-schema.jar"/>
	    </lib>
	</war>
 
        <!-- delete the build properties file -->
        <delete file="${build.properties.file}" failonerror="false"/>
 
        <delete>
	    <fileset dir="${build.dir}/warlibs">
	        <include name="*.jar"/>
	    </fileset>
	</delete>
    </target>
</project>

Plug-in project's targets

Eclipse Plug-in project is a special kind of Java project which designed to create a plug-ins for Eclipse. Build.xml files generated for plug-in projects has one additional target to build project as an Eclipse Plug-in:

• plugin - the target uses Eclipse PDE build scripts to build project as an Eclipse plug-in. Creates pluginID_version.jar file in the build/plugins folder.

Note:

1. In order to use this target the ECLIPSE_HOME property must point to the correct location where Eclipse runtime can be found.
2. In order to build Eclipse plug-in build script copies sources of the project and its dependencies into temporary folder to avoid corruption of source files and build scripts.
3. Higgins2ant support generation of Eclipse plug-in specific targets since ver. 0.9.0

Feature project's targets

Eclipse feature project is special kind of project which defines a set of Eclipse plug-ins and features as a deployable unit. Build.xml files generated for feature projects has only one target to build the project:

• feature - the default target uses Eclipse PDE build scripts to build project as a deployable unit containing all included features and plug-ins. Creates featureID_version.jar file in the build/features folder

Note:

1. In order to use this target the ECLIPSE_HOME property must point to the correct location where Eclipse runtime can be found.
2. In order to build Eclipse feature build script copies sources of the project and its dependencies into temporary folder to avoid corruption of source files and build scripts.
3. Higgins2ant supports generation of build files for Eclipse feature projects since ver. 1.0.0.1

Update Site project's targets

Eclipse Update Site project is special kind of project which defines an update site for Eclipse features. Update sites deployed somwerre in the web is used by Eclipse Update Manager to install and update features. Build.xml files generated for update site projects has only one target to build the project:

• site - the default target uses Eclipse PDE build scripts to build update site contents including all contained features and plug-ins. Creates a set of featureID_version.jar and pluginID_version.jar files in build/features and build/plugins folders respectively. Also creates zipped content of update site in siteID_version.zip in the build folder.

Note:

1. In order to use this target the ECLIPSE_HOME property must point to the correct location where Eclipse runtime can be found.
2. In order to build Eclipse update site build script uses build scripts of containing futures to build them.
3. Higgins2ant supports generation of build files for Eclipse update site projects since ver. 1.0.0.5

Common targets

For all types of projects following set of targets are generated:

• fetch.dependencies - the target to fetch the dependencies of the project from SVN repository.

Note:

1. This target is generated only if Subclipse plug-in is installed into Eclipse IDE and projects in your workspace are connected to SVN repository.
2. In order to use fetch.dependencies target the following set of libraries from svnant should be available for Ant at runtime:
   • javasvn.jar
   • svnant.jar
   • svnClientAdapter.jar
   • svnjavahl.jar
3. Higgins2ant support generation of SVN specific targets since ver. 0.9.0

dependencies.xml

For each supported type of projects Higgins2ant generates dependencies.xml file which contains all required information to provide automated build scripts with the information on the required projects and/or libraries.

Automated build scripts uses dependencies.xml file with the format described below.

<?xml version="1.0" encoding="UTF-8"?>
<dependencies id="org.eclipse.higgins.icard.provider.cardspace.common">
	<!-- list of projects that are required -->
    <higginsProjects>
        <project id="org.eclipse.higgins.registry"/>
        <project id="org.eclipse.higgins.icard"/>
    </higginsProjects>
	<!-- libs that should be downloaded to the project. can be multiple for different locations -->
    <remoteLibs location="lib">
        <library id="commons-logging-1.1.jar"/>
        <library id="serializer.jar"/>
        <library id="xalan.jar"/>
        <library id="xercesImpl.jar"/>
        <library id="xmlsec-1.4.0.jar"/>
    </remoteLibs>
</dependencies>

For more information see How_Autobuild_Gets_Dependencies

project.psf and projectWithDeps.psf

These files are created if you have installed the Subclipse plug-in.

Team Project Sets that are stored in the workspace can now be imported directly using the Import Project Set operation available in the context menu of any *.psf file. Higgins2ant automatically generates project.psf and projectWithDeps.psf files.

Build scripts use project.xml file with the structure below as generated by Eclipse IDE.

<?xml version="1.0" encoding="UTF-8"?>
<psf version="2.0">
    <provider id="org.tigris.subversion.subclipse.core.svnnature">
        <project reference="0.9.3,https://dev.eclipse.org/svnroot/technology/org.eclipse.higgins/trunk/plugins/org.eclipse.higgins.cache.api,org.eclipse.higgins.cache.api"/>
    </provider>
</psf>

Install information

With the prerequisites installed, follow these steps to setup your environment:

1. Add the jre/bin directory of the installed JDK to your PATH environment variable.
2. Add the ant/bin directory of the installed Ant to your PATH environment variable.

One cans install the plug-in by 2 ways:

• setup locally
• setup on-line

Install locally

Before setup locally, you need to download latest version of zipped update site (e.g. higgins2ant.site_1.0.0.5.zip) from the Higgins2ant Update Site to your local machine.

To Setup locally, follow the instructions below:

• from the main Eclipse menu select Help -> Software Updates -> Find and Install...

• in the "Install/Update" window select Search for new features to install -> Next

• click New Archived Site... and choose .zip archive of the update site (e.g. higgins2ant.site_1.0.0.5.zip)

• Edit name -> click OK

• click Finish

• in the "Updates" window select Higgins Ant Files Generator Feature {installed version} in the treeview of features -> click Next

• read the license agrement and if you accept it click Next

• click Finish

• in the "Verification" window click either Install or Install All

• click Yes

Install on-line

To Setup on-line, follow the instructions below:

• from the main Eclipse menu select Help -> Software Updates -> Find and Install...

• in the "Install/Update" window select Search for new features to install -> Next

• in the Install window click New Remote Site... and type a name (e.g. "Higgins2ant Update Site") and the URL (i.e. http://download.eclipse.org/technology/higgins/higgins2ant/) of the Higgins2ant Update Site -> OK

• click Finish

• in the Updates window select Higgins Ant Files Generator Feature {installed version} in the treeview of features -> Next

• read the lisence agrement and if you accept it -> click Next

• click Finish

• in the "Verification" window click either Install or Install All

• click Yes

Generate build files

• right click on the project tree and select Export

• (General) Higgins Buildfiles -> Next

• check projects for which you wish to create build files -> Finish

Running generated build files

You can run generated build files either from Eclipse IDE or from command line. In order to run generated build files successfully you may need to override some Ant properties. In most cases it is enough to override ECLIPSE_HOME property pointing to your Eclipse installation folder but you can override other properties defined in build.xml to customize build behaviour. The way to override depends on your runtime environment.

Running from Eclipse IDE

1. From the Package Explorer right click on Right click on build.xml -> Run As -> Ant Build ...
2. Click Targets tab, select targects you want to run.
3. Go to JRE tab, make sure you are using correct JDK version.
4. Define ant properties you need to override. You can do this in either of two ways:
   • On the Properties tab
     1. Un-select "Use global properties as specified in the Ant runtime preferences"
     2. Click "Add Property ..."
     3. Set Name = <property name>
     4. Set Value = <property value>
   • On the JRE tab
     1. For each property you need to overrite, add -D<property name>=<property value> VM argument
5. Click Run

Running from command line

With the prerequisites installed, follow steps below to run your build script from command line:

1. Make sure JDK's bin directory is added to your PATH environment variable.
2. Make sure Ant's bin directory in added to your PATH environment variable.
3. CD to your project's directory
4. run ant tool using command as wollows:
   • Ant [<target1>[,<target2>]...]
   • For each property you need to overrite, add -D<property name>=<property value> argument to the command line above.

Uninstall

To uninstall the Higgins2Ant plug-in, follow the instructions below:

• from the main Eclipse menu select Help -> Software Updates -> Manager Configuration

• in window "Product Configuration" select Higgins Ant Files Generator Feature {installed version} in the treeview of features

• right click -> Uninstall

• click OK

• click Yes

See Also

Automated Builds