Editor's Note: In last week's excerpt from Ant: The Definitive Guide, 2nd Edition, Steve Holzner showed off the basics of integrating Ant with Eclipse. But if you've ever written a
build.xml file for a large project, you know that there's more to Ant than spelling out the targets. Providing a build script that can be customized to the developer's OS, file-system layout, and other preferences is important for keeping a team of developers working consistently. In this excerpt, Steve shows how to use Eclipse to set property values and environment variables that can be picked up by Ant. He also shows how to configure the Ant editor to work on Ant files from within Eclipse, how to use a different version of Ant, and more.
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.
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
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.
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.
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
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
TIP: 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.
Eclipse comes with Ant 1.6.1, but it's possible to use a different version. Open the Ant preferences page by selecting Window→ Preferences→ Ant→ Runtime and clicking the Classpath tab.
When Eclipse runs Ant, it looks for the appropriate classes on the Ant classpath, as set in the Ant Home Entries item. To change the Ant Home Entries, click the Ant Home button and choose the Ant installation you wish to use.
TIP: If you don't want to change the classpath, you can run Ant as an external tool from Eclipse. To do that, select Run→ External Tools→ External Tools to open the External Tools dialog. Click the Program item and then the New button. Enter a name for the new tool (such as "Ant 1.8" or whatever is appropriate). Next, to the Location field, click the Browse File System button and navigate to ant.sh or ant.bat, whichever is right for your operating system, and click Open. The External Tools dialog will reappear; in the Arguments field, enter any arguments you want to pass to Ant. Finally, in the Working Directory field, enter the directory of the build file you want to use and click Run to launch the new version of Ant. The problem with doing this is that you won't have easy access to predefined values that you have while working inside Eclipse. In most cases, it's far better to use Ant from inside Eclipse when building Eclipse projects.
Eclipse comes with a dedicated view for working with Ant—called the Ant view—which is a window that gives you an overview of the targets in build files. To open this view, select Window→ Show View→ Ant; the Ant view appears at right in Figure 11-12.
Figure 11-12. The Ant view
The toolbar in this view contains these buttons (from left to right):
Add Build Files
Add Build Files with Search
Hide Internal Targets
Run the Default Target
Remove Selected Build File
Remove All Build Files
To add a build file to the Ant view, click the Add Build Files button, opening the Choose Location dialog. In the left box, select the Eclipse project you want to use, and in the right box, select the build file you want to add to the Ant view. Click OK, adding the build file to the Ant view.
TIP: In Windows, you can add build files to the Ant View with drag and drop.
Besides giving you an overview of a build file, the Ant view lets you run build files. Select a build file in the Ant view and click the Run the Default Target button. Or right-click a target and select the Run item in the context menu that appears. Double-clicking a build file in the Ant view opens it in the Ant editor (as does right-clicking the build file and selecting the Open With→ Ant Editor item).
Using Ant with Eclipse is a potent combination. Eclipse allows you to develop and debug code, and Ant lets you build and deploy it. Both of these tools are free for the downloading. It's a combination I recommend.
View catalog information for Ant: The Definitive Guide, Second Edition
Return to ONJava.com.
Copyright © 2009 O'Reilly Media, Inc.