In eclipse you can define classpath entries that indirectly reference files, directories or projects: classpath containers and classpath variables.

A classpath container provides a way to indirectly reference a set of classpath entries. Typically, a classpath container is used to describe a complex library composed of multiple JARs or projects. Bear in mind that in different projects a container can map to a different set of entries, in other words, several projects can reference the same generic container path, but each of them is actually bound to a different container object.

Classpath variables can be used in a Java Build Path to avoid a reference to the local file system. Using a variable entry, the classpath only contains a variable and the build path can be shared in a team.

Entries of both types are difficult to resolve outside of the eclipse environment, simply because they are highly dependent on the specific environment. In the case of classpath containers, they also can depend on the specific project (actually they can be computed at project compile-time!).

So, if you plan to build your system outside of eclipse, avoid using containers and variables. If you can't avoid them, you have to manually specify how ant should resolve these entries. Currently there are two possibilities to declare that actual pathes for containers: either use an ant Path or Property or use ant4eclipse userLibraries type to load an exported configuration file.

To use an ant Path to resolve a container create a Path with an id that matches the name of the container as specified in the path attribute of the classpathentry:

Imagine your .classpath-file looks like this:

  <classpath>
    ...
    <classpathentry kind="con" path="org.eclipse.jdt.USER_LIBRARY/myUserLibrary"/>
    ...
  </classpath>

You could define a Path for this entry like this:

Example:

In this example all occurrences of org.eclipse.jdt.USER_LIBRARY/myUserLibrary in your project's classpathes would be replaces with the defined Path structure.

Instead of using a Path you could also use a Property. The name Property must match the path attribute. This is especially useful if you're specifying the value for a classpath variable.

 <classpath>
 ...
 <classpathentry kind="var" path="RUNTIME_RESOURCES"/>
 ...
 </classpath>

You could define a Property for this entry like this:

Example:

Using a Property you're also able to specify a "base directory" for extended variables, i.e. variables you have added to your classpath by using the "Extend..." button in "Java Build Path -> Libraries -> Add Library" of your project properties.

Imagine you have all your libraries in a folder (/usr/lib/java). Some of them are added to your project classpath by using an extended variable. You will have some lines like this in your .classpath file:

  <classpath>
    ...
	<classpathentry kind="var" path="JAVA_LIBS/xml/xerces.jar"/>
	<classpathentry kind="var" path="JAVA_LIBS/hibernate.jar"/>
	...
  </classpath>

Instead of specifing a Property for each of those libraries it's enough to declare a Property for the "variable part" of this classpath entries, i.e. for the JAVA_LIBS variable to make ant4eclipse work correctly:

  <property name="JAVA_LIBS" value="/usr/lib/java"/>

Another way to resolve containers would be the use of the userLibraries type. This element allows to use a user library configuration file that has been exported from eclipse ("Window->Preferences...->Java->Build Path->User Libraries->Export"). This way you only need to specify the location of the exported file. The pathes will be registered automatically according to the desired naming scheme.

Example:

Sometimes a user wants to setup projects where the project names aren't equal to the folder names. This can be very problematic in case you have to deal with project dependencies. These dependencies are using the project names so a project folder cannot be found this way. Ant4Eclipse allows the use of the property initialiseWorkspace. In case this attribute has been enabled, each folder within the workspace will be parsed allowing to create a mapping between project and folder names.

By default this option is disabled because it invokes the parsing process for each project contained in a workspace which could take some time on huge workspaces.

The Web App Libraries container is a dynamic container that is introduced with the Web Tools Platform (WTP). It is used to automatically add all libraries from a project's WEB-INF/lib folder to the classpath (as an application server would do at runtime). Ant4eclipse is able to provide a default value for this kind of classpath container (org.eclipse.jst.j2ee.internal.web.container) if no Path or Property is specified for such a container in your classpath. If you have a web module (dynamic web project) called "my.fancy.webmodule" you will find an entry like this in the .classpath-file of it's parent project:

  <classpath>
    ...
    <classpathentry kind="con"
      path="org.eclipse.jst.j2ee.internal.web.container/my.fancy.webmodule"/>
    ...
  </classpath>

If you don't create a Path or a Property with the id org.eclipse.jst.j2ee.internal.web.container/my.fancy.webmodule ant4eclipse automatically would add all files in the folder my.fancy.webmodule/WEB-INF/lib to the classpath. That is the same as if you would manually defined the following Path:

Example:

You can copy all referenced jars of an eclipse project to somewhere by first getting the classpath, using the getEclipseClasspath task and then iterating over all it's entries using foreach. In the target invoked by foreach, an entry can be checked if it fulfills some conditions (for example if the file really exists) and can then be copied to the target destination.

An example is shown below (notice that you need Ant 1.6.3 or later to run this example):

Example:

Note that this is only an example, of course it is possible to copy whole directories as well. You can use this approach also for building jar files for all directories contained in your classpath.

A build file is considered reusable if it can be used by several workspaces (and projects) without any modification. Several ant4eclipse tasks support the creation of reusable build files. You would write your build file using the following steps:

1. Get all projects out of their version control repository using either the cvsGetProjectSet or the svnGetProjectSet task
2. Use computeBuilderOrder to compute the order in which the projects must be build according to their dependencies
3. Iterate over the list with projects received from computeBuilderOrder (using foreach from ant-contrib)
4. Execute "generic" targets for all builders defined in each project

Note that there a some prerequisits that must be fulfilled if you like to create reusable buildfiles:

• Don't use libraries outside of your workspace. Everything needed to build the workspace should be inside of a project in your workspace. You could create special eclipse projects that contain your external libraries.
• Use a fixed project layouts. All projects involved in your build should have the same (folder-)layout. Classes should always be in "classes", sources always in a "source"-folder an so on. (In a future ant4eclipse release we will provide a task for reading out this information for each project. Having this task would remove this limitation)
• Each builder must have a correspondending target. Each builder that is defined in a project must have a target in the build file that implements the logic that should be executed when this builder occures in a project. Create for example a javabuilder target that contains the calls to javac.

Having a build file that fulfills this requirements the only thing needed to execute a build for several workspaces is something like a simple build.properties file containing properties like username and password for CVS access and the name of a team project set file that contains the projects with their versions that should be build.

You could include this build file easily in your continuous integration tool and you'll have automated builds that always act like the builders inside eclipse do during your development time.

Example:

Invoke this file with the needed parameters (workspace location, psf location, ...)!

Generally it's a good idea to use unmanaged C/C++ projects because they're mainly focused by Ant4Eclipse. They're providing much more control to the user but it's necessary to provide a Makefile which controls this compilation process. Ant is not as popular within the C/C++ scene as it is within the Java scene but it's definitely the better make tool. So the Makefile is only responsible for the delegation of each target to a corresponding target within the build.xml script.

Example:

As you can see, writing the Makefile is an easy task. Dependencies between the targets will be reflected within the build.xml script. This way the complete logic for the build process is stored within the Ant script which can be accessed directly or through a commonly known make tool. It is necessary to make sure that Ant is on your path, otherwise the delegation through the make tool may fail.

To copy resources from multiple source folders you have to resolve the source directories to an ant property first. In conjunction with the foreach task you have to iterate over the folders and copy the resources to the output folder. Note that you have to include the antcontrib tasks in your build file to get the example running.

Example:

The following example uses the for task instead of the foreach task:

Some projects are configured to make use of variables in order to find special locations which is better than using absolute pathes from the developers point of view. It is necessary for Ant4Eclipse to know the values of such variables. Unfortunately these variables are stored within the workspace .metadata directory so we don't want to access this file; it is considered to be a black box. Therefore we've introduced the attribute eclipseVariables which allows to specify a file containing these variables:

Such a property file can look as followed:

A variable named BUILDTARGET can be resolved if such a file has been passed to the task. NOTE: This is a standard properties file so you should take care of special characters which must be preceeded by a slash.

For convenience reason and because the Eclipse file itself looks similar we've built in support for these files. They can be found within the workspace under the location .metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.core.resources.prefs. Be aware that this file is still part of the Black Box, so if the Eclipse folks are changing this, this location won't work anymore.