Section 11.2. Running Ant Build Files

11.2. Running Ant Build Files

You have two options to run these build files from within Eclipse. You can right-click build.xml in the Package Explorer and select Run Ant Build. Doing so runs Ant and gives you the results in Eclipse's Console view.

Eclipse 3.0 runs Ant in a separate JVM, solving many problems that used to plague previous versions.

The output in the Console view is the same as you'd see from Ant if you ran the build file on the command line:

Buildfile: D:\eclipse3\eclipse\workspace\AntExample\build.xml compile:     [javac] Compiling 1 source file compress:       [jar] Building jar: D:\eclipse3\eclipse\workspace\AntExample\Project.jar main:      [echo] Building the .jar file. BUILD SUCCESSFUL Total time: 2 seconds

If there are problems, you can see Ant's output in the Console view. Eclipse will give you a summary in the Problems view, which you can see by clicking the Problems tab at the bottom of Eclipse.

The other option to run a build file is to right-click build.xml in the Package Explorer and select Run Ant Build..., this time with an ellipsis (three dots). This opens the Ant launch configuration dialog you see in Figure 11-6. The Ant launch configuration is specific to the current project.

Figure 11-6. Selecting an Ant target

By default, the Targets tab is selected in this dialog, showing a list of the targets in build.xml. The default target has been selected; you can click the Run button to run that target, or you can select other targets to run. If you leave the default target selected and click Run, you'll see the same results as before in the Console view.

You can set the execution order of targets, shown in the Target execution order box at the bottom of the page (the order in which you select the items is the order in which they will run). Ant will still run each target's dependencies, but you have to be careful in case your changes mess up the overall build order.

11.2.1. Selecting the Build File and Passing Arguments to Ant

You can get as much use out of Ant in Eclipse as you can from the command line. For example, to pass arguments to Ant, right-click build.xml in the Package Explorer and select Run Ant Build... to open the Ant launch configuration. Click the Main tab shown in Figure 11-7. In this page, you can set the build file you want to use, the base directory for the build, and you can pass arguments to Ant.

Figure 11-7. Setting the build file and arguments to pass to Ant

The Capture output checkbox at the bottom of this dialog indicates whether you want to capture the Ant output to the Eclipse Console view, as we've been doing by default.

11.2.2. Modifying the Ant Classpath

When using an optional or custom task, adding extra libraries to the classpath may be necessary. The Ant classpath can be modified globally or by using an individual project's launch configuration. To set the Ant classpath for an individual Eclipse project, open the Ant launch configuration for the project and click the Classpath tab. You can add external JARs by clicking the Add External JARs button.

You can modify the Ant classpath globally for all projects. To do that, select Window Preferences Ant Runtime, and click the Classpath tab. You can add JAR files as needed here, and they'll be used globally for all Ant builds.

11.2.3. Setting Property Values

You can set global Ant properties using the Ant preferences page, which you open by selecting Window Preferences Ant Runtime and clicking the Properties tab. To add a new property, click the Add Property button and fill in the Name and Value fields in the dialog that appears. This will set the global properties for all Ant builds in Eclipse, and since properties are immutable, you will be setting the final value for such properties.

You can set properties on a project-by-project basis by setting the project's Ant launch configuration. Click the Properties tab in the launch configuration (as seen in Figure 11-8), deselect the "Use global properties as specified in the Ant runtime preferences" checkbox, and click the Add Property button to set new properties.

Figure 11-8. Setting properties

11.2.4. Setting Environment Variables

You can set the environment variables you want passed to Ant, but you have to ensure Ant will run in its own JRE (the default). In the project's Ant launch configuration, click the JRE tab and click the Separate JRE radio button. To set environment variables, click the Environment tab, shown in Figure 11-9, and click the New button to create a new environment variable.

Figure 11-9. Setting environment variables

When you click the New button, the New Environment Variable dialog appears. Enter the name and value of the environment variable in the appropriate fields and click OK.

11.2.5. Configuring the Ant Editor

You can reformat an Ant build file using the Format command (Ctrl-Shift-F) from the Ant editor's context menu or by selecting Edit Format. To configure how that formatting works, open the Ant preferences page with Window Preferences Ant Editor Formatter, as shown in Figure 11-10. Any changes you make will be reflected in the Preview box.

Figure 11-10. Configuring Ant formatting

Selecting Window Preferences Ant Editor lets you configure the build file editor by setting tab widths, margins, highlighting and more.

11.2.6. Adding New Ant Tasks and Types

You can add new Ant tasks and types (covered in detail in the next chapter) to Eclipse by using the Ant preferences page at Window Preferences Ant Runtime. These tasks and types will be available for build files without having to use the taskdef or typedef tasks, which are normally needed.

To add a new task, select the Tasks tab, shown in Figure 11-11, click the Add Task button, and navigate to the JAR file in which the new Ant task is located. To add a new type, click the Types tab and follow the same steps.

Figure 11-11. Adding Ant tasks

If you can't find the JAR files you need, add them to the Ant classpath first.

Alternatively, you can add additional classes defining tasks and types to the Ant classpath by clicking the Classpath tab.