Integrating Ant with Xcode

It was a dark and hazy night, and you had just crunched out your latest round of Java code on Mac OS X using Xcode. The phone rings. It's your boss calling from her vacation in Mexico. She wants your code to build seamlessly on your Mac as well as under Windows. You hang up the phone as thunder begins to clap outside and lightning blinks around you. You start to sweat. You feel moisture pouring down your face.

You wake up to find your cat licking your face, your light bulb flickering badly, and “Thunder Rolls” by Garth Brooks blaring in the background. Wow, your boss isn't even on vacation and you don't listen to country. You gotta stop coding at 3 in the morning!

OK, over-dramatizations aside, building Java code on multiple platforms is a problem facing many Java developers. The natural answer tends to be Ant, an open-source tool hosted by the Apache Group.

Why Use Ant?

Ant has a number of advantages:

• Standards Based: The build file is written in XML, making it easy to edit.
• Cross-Platform: Ant works the same on Mac OS X, Windows, or Linux.
• Easily Extendable: Custom Ant tasks can be written to extend the functionality of Ant. There has already been a custom Ant task created to automatically create a disk image (.dmg file) after a build.
• IDE Support: A number of IDEs (Integrated Development Environments) provide strong integration with Ant, including Eclipse.
• Open Source: If you want to get in under the hood to see how Ant goes about building projects -- no problem. The source code is readily available.

I assume the following in this article:

• You are a developer on Mac OS X.
• You have the developer's tools installed, specifically Xcode.
• You have a basic understanding of Java.

Installing Ant

Installing Ant is very straightforward. This previous article by David Miller contains instructions for installing Ant on Mac OS X.

Related Reading Mac OS X for Java Geeks By Will Iverson

Understanding the Build File

One of the easiest ways to get started using Ant is to use it at the command line through the Terminal. Ant automatically looks for the build.xml file in the base directory of your project. After creating a simple Xcode project, you can build it using Ant from the command line.

Within Xcode, you can create a build.xml file. The build.xml file to go along with a simple Xcode project might look like the following:

<?xml version="1.0"?>

<project name="HelloWorld" default="myApp" basedir=".">
	<description>HelloWorld build file.</description>
	<property name="src" location="."/>
	<property name="build" location="build"/>

	<target name="init">
		<mkdir dir="${build}"/>
	</target>

	<target name="myApp" depends="init" description="compile the source ">
		<javac srcdir="${src}" destdir="${build}"/>
	</target>

</project>

Let's step through this simple build file:

<project name="HelloWorld" default="myApp" basedir=".">

We start by creating the <project> node. This node must be the uppermost node in the build.xml file. Only one <project> node is allowed per build.xml file. The project has a name, which can be anything short and descriptive. The default attribute tells Ant the first task to kick-off if no task is specified. We'll examine tasks in a moment. The base directory is the root of the project.

<description>HelloWorld build file.</description>
    <property name="src" location="."/>
    <property name="build" location="build"/>

The <description> is the description for the project. It is a great place to include a bit of documentation about the build.xml file and the project in general. The <property> tag defines variables that can be used later on in the build file. In this case, we define two variables for the location of source files and the destination of the build files.

Properties are easy to reference by using a syntax very similar to Java Standard Tag Library (JSTL). The src variable is referenced like this: ${src} . Other system variables are also available, such as the OS name (${os.name}) and the project name (${ant.project.name}).

	<target name="init">
		<mkdir dir="${build}"/>
	</target>

The target is a set of items to do. In this case the init item makes sure that the build directory is available.

	<target name="build" depends="init" description="compile the source ">
		<javac srcdir="${src}" destdir="${build}"/>
	</target>

The next target called build has a dependency on the init target. Hence the init target will be called before the build target. The description is another great place to add a little documentation. Next, Ant calls the javac task, just as the mkdir was also a task. The attributes are fairly self-explanatory. The srcdir is the source directory for the code. The destdir is the destination directory for the build.

Executing the build file from the command line is easy. Simply open Terminal and go to your project directory. If you added Ant to your terminal configuration file, then all you have to do is type in ant once you have gone to the base of your project directory. Ant automatically looks for the build.xml file and executes the default target. Since the default target, called build, depends on the init target, the init target is executed first. It's that easy!

Here is the output from a simple build.xml file executed at the command line:

Buildfile: build.xml

init:

build:
     [echo] Start dBuild.
    [javac] Compiling 1 source files to /Users/dhaidle/dev/antTest/build
     [echo] End dBuild.

BUILD SUCCESSFUL
Total time: 3 seconds

If you have a larger Ant file, you might want to execute a particular target. In the aforementioned example, you can execute just the init target by entering ant init.

Setting Up Xcode

Wouldn't it be great if you could execute the Ant build.xml file from within Xcode? Xcode can be configured to use Ant when you hit Command-B. Here are the steps:

1. Create a project: The project can be anything, but for this example we will create a simple Java tool.
   • Select New Project from the File menu.
   • Select a Java tool.
   • For the project name we will use antExample and for the project directory we will use ~/dev/antExample/. (Feel free to use your own naming conventions and substitute them in as we go along.)
   • Wait awhile, as all of the classes are indexed. Grab your favorite beverage.
2. Prepare the project: The files in your project should look like the following:

   

   • Delete the antExample target. When you delete the antExample target, the antExample executable is automatically removed as well. (Hint: Just hit the delete key to delete the target. The delete option is not in the contextual menu.)
   • Delete the java executable as well.
3. New Target: We need a new target for Ant to control and build.
   • Add a new target by doing a right-click on Target, select Add-->New Target.
   • Select the External Target under the Special Targets heading.
   • Enter AntTarget or another appropriate name.
4. Your Groups & Files area should look like the following:

   

5. Preparing the new target: We need to let Xcode know that we want to use Ant to build the project.
   • Click the in the toolbar.
   • Click on the AntTarget. The following panel should appear in the lower right-hand corner:

     

     (Hint: Sometimes Xcode is a bit finicky when presenting the target panel. You might have to select a file first and then the AntTarget.

   • Set the build tool to the path for your installation of Ant. In my particular case, this is /usr/local/apache-ant-1.6.1/bin/ant, but your directory could be different.
   • Scrolling down, you should remove all of the Build Settings except Product_Name.
   • Your target panel should look something like the following now:

     

6. Add a build.xml file: The build file becomes part of the Xcode project and is easy to edit from within Xcode.
   • Right-click on the root antExample, select Add --> New File, select Empty File in Project. Click Next and name it build.xml. Click Finish.
   • Select the build.xml file and paste in the following XML:

     <?xml version="1.0"?>
     <project name="antExample" default="myApp" basedir=".">
         <description>Ant Example build file.</description>
         <property name="src" 
             location="/Users/[yourUsername]/dev/antExample"/>
         <property name="build" 
             location="/build"/>
         <target name="init">
             <mkdir dir=""/>
         </target>
         <target name="myApp" depends="init" 
             description="compile the source ">
                 <javac srcdir="" destdir=""/>
         </target>
         </project>

     You will need to set the src property appropriately for the location of your source files.

7. If all has gone well, hit Command-b or click on the build hammer in the toolbar. It will tell you that it is building, and then after a few moments, depending on the speed of your processor, it will say Succeeded in the upper right-hand corner. You should now have an antExample.class file in the stated build directory.

You should be all set up now. Unfortunately, when you build the file, the build window is not aware of Ant and does not respond to the <echo> tags in your build file or tell you how much time the build process took -- as it does if executed from the command line.

Calling Xcode From Ant

Say you want to log into your system remotely through SSH to do a quick build of an Xcode project. You can use Ant to easily configure building Xcode projects from the command line. Xcode can be easily executed from the command line using xcodebuild and as such can be called by Ant. Here is the build file for a simple Xcode project:

<?xml version="1.0"?>

<project name="myApp" default="xcodeBuild" basedir=".">
    <target name="xcodeBuild">
        <echo>Start dBuild.
        <exec executable="xCodeBuild">
            <arg value="-alltargets"/>
        </exec>
        <echo>End dBuild.
    </target>
</project>

This demonstrates executing a command line instruction from Ant. Ant is very versatile. The echo task simply instructs Ant to display the enclosed text when executed. This can help with debugging Ant build files. The exec has a single argument passed in using the <arg/> tag and can have additional attributes. If no arguments are passed in, Xcode builds the default target.

Creating a Jar

Creating a .jar file is trivial with Ant. You can add a target such as the following:

<target name="jar" description="build jar file." depends="dBuild">
    <echo>Build jar file.</echo>
    <jar destfile="/installer.jar" basedir=""/>
    <echo>Jar File Build Complete.</echo>
</target>

Of course, the jarDir is specified as a property:

<property name="jarDir" value="jar"/>

Final Thoughts

As you can see, Ant is a versatile tool for the Mac developer. Once you start working with it, you'll find all sorts of ways it can save you time. For example, if you build Java Applications with Xcode, you can automate the creation of a .dmg. A .dmg is a disk image and is currently the preferred distribution method for applications on Mac OS X, unless you have configuration files to add, which might require an installer.

If you have a clever application of this tool, let us know in the TalkBacks section at the end of this article. In the meantime, happy exploration with Ant.

Derek Haidle is a Java programmer and owner of Haidle Consulting Inc. in Maple Grove, Minnesota.

Return to MacDevCenter.com.

Copyright © 2009 O'Reilly Media, Inc.