View source for Higgins2Ant

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}
[[Image:Higgins_logo_76Wx100H.jpg|right]]
== 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 [http://download.eclipse.org/technology/higgins/higgins2ant/ Higgins2ant Update Site].

== Prerequisites ==
A number of prerequisites need to be installed on the build machine, as follows:
# [http://java.sun.com/j2se/1.4.2/download.html J2SE SDK 1.4.2]
# [http://www.eclipse.org/downloads/ Eclipse] version 3.2 or higher
# [http://ant.apache.org/ 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 ===
{| class="wikitable" style="text-align:left; border="1" cellpadding="5" cellspacing="0"   
! rowspan="2" border="1" align="left" valign="top" | Connection Type 
| Committers 
| https:// or svn+ssh://
|-
| Anonymous access 
| http://
|-
! colspan="2" border="1" align="left" valign="top" | Host 
| dev.eclipse.org
|-
! colspan="2" border="1" align="left" valign="top" | Repository Path 
| /svnroot/technology/org.eclipse.higgins
|-
|}  


{| class="wikitable" style="text-align:left; border="1" cellpadding="5" cellspacing="0"   
|-style="background:#d6dee9; color:black"   
! border="1" align="left" valign="top" | Project
! border="1" align="left" valign="top" | Module Location
! border="1" align="left" valign="top" | Eclipse PSF
! border="1" align="left" valign="top" | ViewSVN
|-
|rowspan="2" |higgins2ant.feature
|rowspan="2" |/trunk/builds/higgins2ant.feature
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.feature/project.psf?root=Technology_HIGGINS&view=co project.psf] 
|rowspan="2" | [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.feature/?root=Technology_HIGGINS viewsvn]
|-
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.feature/projectWithDeps.psf?root=Technology_HIGGINS&view=co projectWithDeps.psf]
|-
|rowspan="2" |higgins2ant
|rowspan="2" |/trunk/builds/higgins2ant
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant/project.psf?root=Technology_HIGGINS&view=co project.psf] 
|rowspan="2" | [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant/?root=Technology_HIGGINS viewsvn]
|-
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant/projectWithDeps.psf?root=Technology_HIGGINS&view=co projectWithDeps.psf]
|-
|rowspan="2" |higgins2ant.core
|rowspan="2" |/trunk/builds/higgins2ant.core
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.core/project.psf?root=Technology_HIGGINS&view=co project.psf] 
|rowspan="2" | [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.core/?root=Technology_HIGGINS viewsvn]
|-
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.core/projectWithDeps.psf?root=Technology_HIGGINS&view=co projectWithDeps.psf]
|-
|rowspan="2" |higgins2ant.pde
|rowspan="2" |/trunk/builds/higgins2ant.pde
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.pde/project.psf?root=Technology_HIGGINS&view=co project.psf] 
|rowspan="2" | [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.pde/?root=Technology_HIGGINS viewsvn]
|-
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.pde/projectWithDeps.psf?root=Technology_HIGGINS&view=co projectWithDeps.psf]
|-
|rowspan="2" |higgins2ant.site
|rowspan="2" |/trunk/builds/higgins2ant.site
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.site/project.psf?root=Technology_HIGGINS&view=co project.psf] 
|rowspan="2" | [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.site/?root=Technology_HIGGINS viewsvn]
|-
| [http://dev.eclipse.org/viewsvn/index.cgi/trunk/builds/higgins2ant.site/projectWithDeps.psf?root=Technology_HIGGINS&view=co projectWithDeps.psf]
|-
|}

== General Information ==
Higgins2ant plug-in generates following set of files:
* <code>[http://wiki.eclipse.org/Higgins2Ant#build.xml build.xml]</code> - ant build file
* <code>[http://wiki.eclipse.org/Higgins2Ant#dependencies.xml dependencies.xml]</code> - xml file contains all project's dependencies in the format used by [[Automated Builds]]
* <code>[http://wiki.eclipse.org/Higgins2Ant#project.psf_and_projectWithDeps.psf project.psf and projectWithDeps.psf]</code> - 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'''
<p>
In order to extend capabilities of generated build files Higgins2ant plug-in automatically imports all build files in the project directory which contains <code><?eclipse.ant.import?></code> 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</p>
<p>
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.</p>

==== 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 <code>'''build/bin'''</code>.
* '''jar''' - the target to pack project's binaries. Creates <code>'''projectName_version.jar'''</code> file in the <code>'''build/lib'''</code> folder.
* '''javadoc''' - the target to create javadoc for the project. Uses <code>'''build/doc'''</code> folder as output destination.
* '''clean''' - the target to clean build output folder of the project. This target deletes all files and subdirectories of <code>'''build'''</code> folder, including <code>'''build'''</code> 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 <code>'''toDir'''</code> parameter should be specified.
* '''copy.jar''' - the target to copy jar (project's jar) to user defined folder. In order to use this target <code>'''toDir'''</code> 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 <code>'''toDir'''</code> 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.
<source lang="xml">
<?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>
</source>

==== 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 <code>pluginID_version.jar</code> file in the <code>build/plugins</code> folder.

'''Note:'''
# In order to use this target the '''ECLIPSE_HOME''' property must point to the correct location where Eclipse runtime can be found. 
# 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.
# 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 <code>featureID_version.jar</code> file in the <code>build/features</code> folder

'''Note:'''
# In order to use this target the '''ECLIPSE_HOME''' property must point to the correct location where Eclipse runtime can be found. 
# 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.
# 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 <code>featureID_version.jar</code> and <code>pluginID_version.jar</code> files in <code>build/features</code> and <code>build/plugins</code> folders respectively. Also creates zipped content of update site in <code>siteID_version.zip</code> in the <code>build</code> folder.

'''Note:'''
# In order to use this target the '''ECLIPSE_HOME''' property must point to the correct location where Eclipse runtime can be found. 
# In order to build Eclipse update site build script uses build scripts of containing futures to build them.
# 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:'''
# This target is generated only if [http://subclipse.tigris.org/ Subclipse] plug-in is installed into Eclipse IDE and projects in your workspace are connected to SVN repository.
# In order to use '''fetch.dependencies''' target the following set of libraries from [http://subclipse.tigris.org/svnant.html svnant] should be available for Ant at runtime:
#* javasvn.jar
#* svnant.jar
#* svnClientAdapter.jar
#* svnjavahl.jar 
# 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.
<source lang="xml">
<?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>
</source>

For more information see [[How_Autobuild_Gets_Dependencies]]

=== project.psf and projectWithDeps.psf ===
These files are created if you have installed the [http://subclipse.tigris.org/ Subclipse] plug-in.
<p>
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.
</p>
<p>
Build scripts use project.xml file with the structure below as generated by Eclipse IDE.
</p>
<pre>
<?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>
</pre>

== Install information ==

With the prerequisites installed, follow these steps to setup your environment:
# Add the jre/bin directory of the installed JDK to your PATH environment variable.
# Add the ant/bin directory of the installed Ant to your PATH environment variable.

One cans install the plug-in by 2 ways:
<ul>
 <li>setup locally</li>
 <li>setup on-line</li>
</ul>
=== 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 [http://download.eclipse.org/technology/higgins/higgins2ant/ Higgins2ant Update Site] to your local machine.
<p>
To Setup locally, follow the instructions below:
</p>
* from the main Eclipse menu select '''Help''' -> '''Software Updates''' -> '''Find and Install...'''
[[Image:Inst1.JPG]]
* in the "Install/Update" window select '''Search for new features to install''' -> '''Next'''
[[Image:Inst2.JPG|350px]]
* click '''New Archived Site...''' and choose .zip archive of the update site (e.g. higgins2ant.site_1.0.0.5.zip)
[[Image:Inst4b.JPG|350px]]
* Edit name -> click '''OK'''
[[Image:Inst5.JPG|350px]]
* click '''Finish'''
[[Image:Inst6.JPG|350px]]
* in the "Updates" window select '''Higgins Ant Files Generator Feature {installed version}''' in the treeview of features -> click '''Next'''
[[Image:Inst7.JPG|350px]]
* read the license agrement and if you accept it click '''Next'''
[[Image:Inst8.JPG|350px]]
* click '''Finish'''
[[Image:Inst9.JPG|350px]]
* in the "Verification" window click either '''Install''' or '''Install All'''
[[Image:Inst10.JPG|350px]]
* click '''Yes'''
[[Image:Inst11.JPG|350px]]

=== Install on-line ===

To Setup on-line, follow the instructions below:
* from the main Eclipse menu select '''Help''' -> '''Software Updates''' -> '''Find and Install...'''
[[Image:Inst1.JPG]]
* in the "Install/Update" window select '''Search for new features to install''' -> '''Next'''
[[Image:Inst2.JPG|350px]]
* 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 [http://download.eclipse.org/technology/higgins/higgins2ant/ Higgins2ant Update Site] -> '''OK'''
[[Image:Inst4c.JPG|350px]]
* click '''Finish'''
[[Image:Inst6.JPG|350px]]
* in the '''Updates''' window select '''Higgins Ant Files Generator Feature {installed version}''' in the treeview of features -> '''Next'''
[[Image:Inst7.JPG|350px]]
* read the lisence agrement and if you accept it -> click '''Next'''
[[Image:Inst8.JPG|350px]]
* click '''Finish'''
[[Image:Inst9.JPG|350px]]
* in the "Verification" window click either '''Install''' or '''Install All'''
[[Image:Inst10.JPG|350px]]
* click '''Yes'''
[[Image:Inst11.JPG|350px]]

== Generate build files ==
* '''right click''' on the project tree and select '''Export'''
[[Image:Gen1.JPG]]
* (General) '''Higgins Buildfiles''' -> '''Next'''
[[Image:Gen2.JPG|350px]]
* check projects for which you wish to create build files -> '''Finish'''
[[Image:Gen3.JPG|350px]]

== 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 ===
# From the Package Explorer right click on Right click on build.xml -> Run As -> Ant Build ...
# Click '''Targets''' tab, select targects you want to run.
# Go to '''JRE''' tab, make sure you are using correct JDK version.
# Define ant properties you need to override. You can do this in either of two ways:
#* On the '''Properties''' tab
#*# Un-select "Use global properties as specified in the Ant runtime preferences"
#*# Click "Add Property ..."
#*# Set Name = <property name>
#*# Set Value = <property value>
#* On the '''JRE''' tab
#*# For each property you need to overrite, add -D<property name>=<property value> VM argument
# Click '''Run'''
=== Running from command line ===
With the prerequisites installed, follow steps below to run your build script from command line:
# Make sure JDK's bin directory is added to your PATH environment variable.
# Make sure Ant's bin directory in added to your PATH environment variable.
# CD to your project's directory
# 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'''
[[Image:Uninst1.JPG]]
* in window "Product Configuration" select '''Higgins Ant Files Generator Feature {installed version}''' in the treeview of features
[[Image:Uninst2.JPG|350px]]
* '''right click''' -> '''Uninstall'''
[[Image:Uninst3.JPG]]
* click '''OK'''
[[Image:Uninst4.JPG|350px]]
* click '''Yes'''
[[Image:Uninst5.JPG|350px]]

== See Also ==
[http://wiki.eclipse.org/Automated_Builds Automated Builds]
[[Category:Higgins 1.x Developer Info]]
[[Category:Higgins 1.x - Building]]