Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Higgins2Ant

Revision as of 08:16, 31 March 2008 by Vkokhan.aquasoft.dp.ua (Talk | contribs) (Run build files)

{{#eclipseproject:technology.higgins}}

Higgins logo 76Wx100H.jpg

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.

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

General Information

Higgins2ant plug-in generates following set of files:

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:

  • Jeneric Java Project
  • Eclipse Plug-in Project
  • Eclipse Feature 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

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 must download higgins2ant.update.zip on local machine.

To Setup locally, follow the instructions below:

  • select (in main menu) Help -> Software Updates -> Find and Install...
Inst1.JPG
  • in window "Install/Update" select Search for new features to install -> Next
Inst2.JPG
  • select New Local Site... (New Archived Site... if site archived) and choose folder (.zip or .jar file), where your local site places
Inst3.JPG
  • Choose location for local site
Inst4a.JPG

or archived site

Inst4b.JPG
  • Edit name -> OK
Inst5.JPG
  • Finish
Inst6.JPG
  • in window "Updates" select Higgins Ant Files Generator Feature {installed version} in the treeview of features -> Next
Inst7.JPG
  • read license, if you accept the terms in the license agreements, select Next
Inst8.JPG
  • Finish
Inst9.JPG
  • in window "Verification" select Install or Install All
Inst10.JPG
  • Yes
Inst11.JPG

Install on-line

To Setup on-line, follow the instructions below:

  • select (in main menu) Help -> Software Updates -> Find and Install...
Inst1.JPG
  • in window "Install/Update" select Search for new features to install -> Next
Inst2.JPG
  • select New Remote Site...
Inst3.JPG
Inst4c.JPG
  • Finish
Inst6.JPG
  • in window "Updates" select Higgins Ant Files Generator Feature {installed version} in the treeview of features -> Next
Inst7.JPG
  • read license, if you accept the terms in the license agreements, select Next
Inst8.JPG
  • Finish
Inst9.JPG
  • in window "Verification" select Install or Install All
Inst10.JPG
  • Yes
Inst11.JPG

Generate files

To generate, select (from menu) Export

Gen1.JPG

(General) Higgins Buildfiles -> Next

Gen2.JPG

check projects (for which you wish to create the build file) -> Finish

Gen3.JPG

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:

  • select (in main menu) Help -> Software Updates -> Manager Configuration
Uninst1.JPG
  • in window "Product Configuration" select Higgins Ant Files Generator Feature {installed version} in the treeview of features
Uninst2.JPG
  • right click -> Uninstall
Uninst3.JPG
  • OK
Uninst4.JPG
  • Yes
Uninst5.JPG

See Also

Automated Builds

Back to the top