Creating Eclipse project-builder ant build files

Russell Bateman
26 August 2011
last update:

It's possible in Eclipse to create something called an ant build file for the purpose of creating an Eclipse project from it—something others do (since you're creating the project yourself in your own workspace). This can be useful in the case where the project is huge, there are lots of participants, submodules, etc. It avoids the case where everyone has to have a well-formed Eclipse project that builds everything under the sun.

The instructions for creating one of these are sort of well documented at Creating a project builder Ant buildfile. By "sort of", I mean that it's possible to follow along and succeed, but the documentation falls down in two ways.

  1. As illustrated, you're somewhat left wondering if you've done what you're supposed to have done in a couple of the dialogs. It would have been better to show these finished rather than in their initial state (with nothing of what they say to fill in visible).
    2.  
  2. I could not find in Eclipse documentation on how to use a project-builder ant build file, product of this action. I will show this here.
    3.  
  3. Once you're done with the sample project and files, what you have simply doesn't work. This is mostly what this page is here to explain how to fix (and it's very simple).

The problem...

...with what you've created at this point (I'm assuming you're doing this very short tutorial) is that attempting to create a project from it will error out. To create the project, what I said I'd show in #2 above, do the following: 

    New -> Project... -> Java Project from Existing Ant Buildfile -> Next -> Ant Buildfile -> Browse

Browse to the ant file you created in the project and choose it. Click Finish. What happens is that you get: 

    Specified buildfile does not contain a javac task

As spelled out, if mysteriously given that this is only the product of what's supposed to be a working example, your ant file must contain a javac target. The solution is simply to put one in. Here's what I found and added to projectBuilder.xml (note the line in bold below): 


    <?xml version="1.0" encoding="UTF-8"?>
    <project name="HW.makejar" default="makejar" basedir=".">
      <target name ="makejar" description="Create a jar for the HW project">
        <jar jarfile="HelloWorld.jar" includes="*.class" basedir="bin" />
      </target>
      <javac srcdir="src" destdir="bin" />
    </project>

A word about destdir: it has to be a subdirectory you own because if Eclipse (that is, you yourself) do not have full privileges in it, Eclipse will issue an error.

Once you've done this, you'll find that you can dig down under the new project's src to find HelloWorld.java, right-click on it and choose to run or debug it. That's the point to the whole exercise.

Finishing the job

For completeness in answering #2 above, permit me to point out that the project Eclipse creates will not be correct. I'm not certain why this is the case, but it's a long-standing problem in my experience. The project is created to use JRE_LIB, which will be set up as pointing into your JDK, at jre/lib/rt.jar. This is incorrect (and has been for longer than I've been using Eclipse). It should be using the JRE System Library.

To fix this (it's a habit to get into each time you create a project from an ant build file script), simply right-click the project, choose Build Path -> Configure Build Path -> Libraries, remove this library, then click Add Library and add the JRE System Library associated with your workspace.

This will eliminate a warning in your Eclipse Problems view.

The real world

So, this seems a bit elaborate for what little pizzazz there is to get out of it. Why do it then?

Back to what I said above, if you're collaborating on a terribly huge project, one with tens of thousands of sources you don't want to have to build even once, you can fix your build files to generate this magic project for others (and you) to create from using existing, JAR'd class files. Obviously, the application requires rather more ant work than is illustrated here.

Note that projectBuilder.xml is not the ant file you'd use. Instead, you'd put this target into your build.xml (which would not suffer from a lack of javac targets). Upon project creation (having clicked the Finish button noted above), you'd be presented with a list of your build.xml targets and you'd select the right one to finish the dialog in Eclipse (the target that contains javac).


With everything set up...

I'm adding this section to describe how to use this after it's set up. The Eclipse documentation only shows set-up and execution the first time. Here is the complete ant script, recast in my own example rather than using Eclipse's names. 

  <?xml version="1.0" encoding="UTF-8"?>
  <project name="helloworld.makejar" default="makejar" basedir=".">
    <target name ="makejar" description="Create a JAR for the HelloWorld project">
      <delete file="helloworld.jar" />
      <jar jarfile="helloworld.jar" includes="**/*.class" basedir="bin">
        <manifest>
          <attribute name="Built-By"               value="${user.name}" />
          <attribute name="Main-Class"             value="project.builder.example.HelloWorld" />
          <attribute name="Specification-Title"    value="Example" />
          <attribute name="Specification-Version"  value="1.0.0" />
          <attribute name="Specification-Vendor"   value="Example Organization" />
          <attribute name="Implementation-Title"   value="common" />
          <attribute name="Implementation-Version" value="1.0.0 today" />
          <attribute name="Implementation-Vendor"  value="Acme Corp." />
        </manifest>
      </jar>
    </target>
    <javac srcdir="src" destdir="bin" includeantruntime="false" />
  </project>

After this is set up, all you need to do is execute the ant script, whether from Eclipse or from the command line. This creates a) helloworld.jar and b) MANIFEST.MF.

Note that, from Eclipse, you'll always get the warning: 

    No Implementation-Title set.No Implementation-Version set.No Implementation-Vendor set.

This despite that (as shown) you've set them. This does not happen from the command line. Perhaps there's a bug in Eclipse?