# Building features

PDE Build comes with infrastructure to automate the build of features. Most of the setup necessary for such a build can be done through a few modifications to the template build.properties provided in PDE build. The following section focuses on setting up a simple build assuming that all plug-ins and features (both to-build and pre-built) referenced from the feature being built are already locally available on disk.

## Basic Setup

The first step in setting up a build is to create the directory in which the build will take place. This directory will be referred to as the build directory and will contain the plug-ins and features to build as well as all the generated artifacts. Next, copy your plug-ins and features respectively into "plugins" and "features" subdirectories. The feature folder is expected to contain the feature being built.

The second step in setting up a build is to copy the template build.properties file from org.eclipse.pde.build/templates/headless-build to a new directory which will be the build configuration directory (also referred to as the configuration directory). Edit the copied build.properties file and set the following properties:

- baseLocation: the location of an eclipse install containing all the pre-built features and plug-ins in `features/` and `plugins/` subdirectories.
- baseos: indicate the os of the eclipse specified by baseLocation.
- basews: indicate the ws of the eclipse specified by baseLocation.
- basearch: indicate the arch of the eclipse specified by baseLocation.
- buildDirectory: the directory the build will take place in. Set this to the full path of the build directory created previously.
- configs: list the configurations for which you want your feature to be built. You can uncomment the configuration(s) provided (be careful of the line continuations). If the feature you are building is platform independent, this property does not need to be set or can be set to `*,*,*`.
- archivePrefix: the name of the directory in which your feature will be unzipped on disk.

## Controlling what will be built: allElements.xml

Copy the allElements.xml file from org.eclipse.pde.build/templates/headless-build to your configuration directory. This is the file that tells PDE which feature you are building. This file contains two kinds of targets: the `allElementsDelegator` which specifies the feature being built, and the assemble targets which are called to assemble individual configurations. The `allElementsDelegator` for a feature named `org.foo.Feature` is:

     	<target name="allElementsDelegator">
     		<ant antfile="${genericTargets}" target="${target}">
    	 		<property name="type" value="feature" />
    	 		<property name="id" value="org.foo.Feature" />
     		</ant>
     	</target>

The assemble targets allow you to control the name of the final archive on a per configuration basis. You should have one target for each configuration you are building. For example, when building `org.foo.Feature` for windows (when `configs` is set to win32, win32, x86) you should have the following target:

    <!--Target for assembling  os=win32, ws=win32, arch=x86 -->
    <target name="assemble.org.foo.Feature.win32.win32.x86">
    	<ant antfile="${assembleScriptName}" dir="${buildDirectory}/">
    </target>

When building a platform independent configuration (when `configs` is not set or is set to `*,*,*`), you should a target like the following:

    <!--The platform independent assemble target-->
    <target name="assemble.org.foo.Feature">
     	<ant antfile="${assembleScriptName}" dir="${buildDirectory}"/>
    </target>

## Running the build

To run the build you will use the org.elipse.ant.core.antRunner application. When invoking eclipse with this application to perform a build you need to set two arguments on the command line:

- `-buildfile=</path/to/build.xml>`: This is the path to the build.xml provided by pde build. It is located in the org.eclipse.pde.build/scripts directory. This is the build file that drives the whole build process.
- `-Dbuilder=</path/to/configuration folder>`: This is the path to the build configuration folder.

Run the antRunner application using the following command:
`java -jar <eclipseInstall>/startup.jar -application org.eclipse.ant.core.antRunner -buildfile <<eclipseInstall>/plugins/org.eclipse.pde.build_<version>/scripts/build.xml> -Dbuilder=<path to the build configuration folder>`
Once the build is complete, you can get the result in the build directory in the folder named I.TestBuild (this name can be configured by setting the buildLabel property).

## Advanced scenarios

If you require more customization of the build, ie fetching from a repository, see the Advanced PDE Build topics for more information.