# 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 Build Configuration Directory

The first step in setting up a build is to create the build configuration directory. This is the directory in which the files that control and customize the headless build are kept.

The main file for controlling the build is the top level build configuration build.properties file. When setting up a new build, copy the template file from the org.eclipse.pde.build bundle in your eclipse install that you will be using to run your build. The template file is located under org.eclipse.pde.build/templates/headless-build/build.properties.

This directory is refered to by the `builder` properties which is normally set on the ant command line.

### The buildDirectory

The `buildDirectory` property specifies the directory in which PDE/Build will generate scripts and perform the actual build. Plug-ins and features that are being built should placed in `${buildDirectory}/plugins` and `${buildDirectory}/features` sub-directories. If bundles and features are being fetch from a repository (See Fetching From Repositories), then they will be placed here as well.

This directory may be the same as the build configuration directory, or it may be a different directory. It may be desirable to use a separate directory, especially if the build configuration is kept in CVS and you don't want to pollute it with generated build artifacts.

### Initial Properties

To set up a basic feature build, you need to edit the build configuration build.properties file and set the following properties:

- topLevelElementId: Set to the id of the feature you wish to build.
- baseLocation: the location of an eclipse install containing pre-built features and plug-ins in `features/` and `plugins/` subdirectories. These are the binaries against which you will be compiling. If you have no pre-requisite binaries and are building everything from scratch, this property can be left un-set.
- buildDirectory: the directory the build will take place in.
- 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.

Previous version of PDE/Build also required an allElements.xml file, this is no longer necessary in 3.4. The allElements.xml can still be used, but is only required if you wish to customize certain aspects of your build. See Customizing a Headless Build.

## 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 script 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>/plugins/org.eclipse.equinox.launcher_<version>.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.