Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

O'Reilly Book Excerpts: Ant: The Definitive Guide, Second Edition

Integrating Ant with Eclipse, Part 1

Related Reading

Ant: The Definitive Guide
By Steve Holzner

Editor's Note: Every time we do a survey, we find that fewer and fewer Java developers are using a strictly command-line/text-editor approach. The overwhelming majority are using an IDE, and for most, the IDE of choice is Eclipse. Given that, do you really want to enjoy an IDE for creating your code, only have to go out to the command line to build it? Of course not. In this first of a two-part excerpt from Ant: The Definitive Guide, 2nd Edition, Steve Holzner shows how to integrate Ant with Eclipse, from creating a project to writing an Ant build.xml file in Eclipse, and running the build from inside the IDE.

Ant is the premier build tool for Java developers, and Eclipse is the premier integrated development environment (IDE) for Java programmers. Eclipse is great at visual development, and Ant is great for builds. For that reason, the latest Eclipse version (3.0) comes with Ant 1.6.1 (the version of Ant this book was written with), and there's an extensive Ant interface in Eclipse.

TIP: Doesn't Ant have its own IDE? Well, sort of. Antidote, started in 2000, was supposed to have been the Ant IDE; see http://archive.apache.org/dist/ant/antidote/. Unfortunately, that project appears to be more or less moribund, largely because the big guys behind Eclipse have been integrating Ant into their IDE now.

Introducing Eclipse

If you're a Java developer, you know how finicky Java can feel at times. Missed import statements, forgotten variable declarations, omitted semi-colons, garbled syntax, and typos will cause the Java command-line compiler, javac, to cough and display pages of error messages.

The error messages tell you that javac knows what the error is, so why doesn't it just fix the problem and let you continue developing? javac can't fix the problem; to do that, you can use an IDE, which will catch errors before you compile and suggest solutions. Java is badly in need of a good IDE, and the premier Java IDE these days is Eclipse. You can see what it looks like in Figure 11-1.

Figure X
Figure 11-1. Eclipse

Eclipse is free for the downloading, like a number of other Java IDEs, but Eclipse has a serious advantage behind it, which is the power of IBM, reportedly spending $40 million developing it. It's now an open source project, largely under IBM's development but part of a software consortium named eclipse.org.

TIP: Want to read more on Eclipse? See Eclipse by yours truly (O'Reilly).

Getting Eclipse

Eclipse is free for the downloading; all you have to do is navigate to http://www.eclipse.org/downloads. Select one of the download mirrors available on that page. When you do, you'll be presented with a list of the available downloads of these various types:

Release builds

These versions are for general use.

Stable builds

These are comparable to beta versions.

Integration builds

These builds are made up of components that have been fairly well tested, but their operation together may still have some issues.

Nightly builds

These are the most experimental of all publicly available Eclipse builds. They're created nightly by the Eclipse team, and there's really no guarantee that things will work well.

TIP: As with other software, you generally want to use the latest release version of Eclipse; I'll use Eclipse 3.0, the most recent release build, in this chapter.

Select the download for your operating system and click the appropriate link to download it. Installing Eclipse is easy; all you've got to do is to unzip or untar it, depending on your operating system. Since you download the version of Eclipse targeted to your operating system, you'll find the executable file ready to run as soon as you uncompress Eclipse. You start Eclipse by running the Eclipse executable. When you first run Eclipse, you should see the Welcome page. To get an overview of Eclipse or to run a tutorial, click the appropriate links. To close this Welcome page, click the X in the page's tab.

Creating an Eclipse Project

If you've installed Eclipse and have got it running, you have access to the Ant/Eclipse interface and no extra work is needed. Development work in Eclipse is based on projects, and I'll create a new project to show how to use Ant inside Eclipse. To create a new project, select File→ New→ Project, opening the New Project dialog. Select the Java Project item and click Next.

On the next page, give this project the name AntExample. Leave the other defaults as they are and click Finish.

This opens the new project in Eclipse; you can see the AntExample project at left in Eclipse's Package Explorer.

This project is empty so far; to add Java code, select the AntExample project in the Package Explorer and select File→ New→ Class, opening the New Java Class dialog. Give the package name as org.antbook, the name of the new class as AntClass, and select the checkbox marked publicstaticvoidmain(String[]args) to make Eclipse create a main method. Click the Finish button.

This creates the code, AntClass.java, you see in the Eclipse editor at the center of Figure 11-2, complete with a main( ) method.

Figure X
Figure 11-2. A new Java class

Add this code to make this class do something:

public static void main(String args[]) 
    System.out.println("No worries.");    

Click the Save icon in the toolbar to save the changes to AntClass.java, and select Run→ Run As→ Java Application. You'll see the output of this code, No worries., in the Console tab at the bottom of Eclipse.

Writing an Ant Build File in Eclipse

To create an Ant build file in Eclipse, right-click the AntExample project in the Package Explorer and select New→ File. In the File Name box, enter build.xml, and click Finish, adding this new file to the AntExample project. To JAR the output of this project, enter this XML in the build file:

<?xml version="1.0" ?>
<project default="main">
    <target name="main" depends="compile, compress" description="Main target">
            Building the .jar file.
    <target name="compile" description="Compilation target">
        <javac srcdir="org/antbook"/>
  <target name="compress" description="Compression target">
        <jar jarfile="Project.jar" basedir="org/antbook" includes="*.class" />

After entering this XML, save the new build file. The Eclipse support for Ant is evident; build.xml appears in the Package Explorer at left with an Ant icon and the syntax in the build file is colored with XML declarations in one color, attribute values in another, and Ant keywords in another, as shown (in glorious black and white) in Figure 11-3. The targets of this build file appear at right, in the Outline view.

Figure X
Figure 11-3. An Ant build file in Eclipse

TIP: If you close build.xml, you can open it again in the Eclipse Ant editor; double-click it in the Package Explorer. This is different than previous versions of Eclipse, which had no default Ant editor. You had to take extra steps to open Ant build files for editing.

Support for Ant is evident in Eclipse's code assist (also called content assist), which was added for Ant build files in Eclipse 3.0. When you enter partial text for Ant elements or attributes, you can press Ctrl-Space to open code assist, which will list possible completions of what you've been typing, as shown in Figure 11-4.

Figure X
Figure 11-4. Using code assist

TIP: If you enter a $ and use code assist, Eclipse's Ant editor will list all the Ant property names it knows about.

Eclipse 3.0 can catch syntax errors in Ant build files. For example, ending a target with </targe>, instead of a </target> tag, is immediately caught by the Eclipse Ant editor, as shown in Figure 11-5. If you let your cursor rest over the circled X icon to the left of the problem line, you'll see Eclipse's explanation of the problem: "Expected `</target>' to terminate element starting on line 3." This kind of syntax checking and corrections alone are worth the price of admission.

Figure X
Figure 11-5. Handling syntax errors

TIP: You can reformat an Ant build file-indenting everything nicely, using the Format command (Ctrl-Shift-F) from the Ant editor's context menu or by selecting Edit→ Format.

Want to see the value of a property? Let the mouse hover over it, and its value will appear in a tooltip.

TIP: Under some circumstances, Eclipse can generate Ant scripts for you. For example, if you're creating an Eclipse plug-in, which extends Eclipse with your own views and editors, you'll use a plug-in manifest file named plugin.xml. If you right-click the manifest file and select the Create Ant Build File item, Eclipse will create a build file for you. If you select Project→ Generate Javadoc, the Javadoc wizard will create an Ant build file that runs the javadoc tool, which you can edit as needed.

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.

TIP: 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
    [javac] Compiling 1 source file
      [jar] Building jar: D:\eclipse3\eclipse\workspace\AntExample\Project.jar
     [echo] Building the .jar file.
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 X
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.

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 X
Figure 11-7. Setting the build file and arguments to pass to Ant

TIP: 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.

View catalog information for Ant: The Definitive Guide, Second Edition

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.