Introduction

The EL4Ant is a build system based on Ant. Its principle is to generate a build file (build.xml) for Ant with high-level targets for everyday tasks, based on a project description, consisting in plugins and modules.

Objectives

• Must be efficient and fast for everyday tasks
• Must be extensible with plugins (easy to write for a Ant user, Java developper)
• Keep it lightweight and simple

Getting Started

Download the latest HelloWorld package ant+el4ant+helloworld at SourceForge.net and follow the GettingStarted instructions.

Core documentation

Let's read the user's guide before reading the documentation of a plugin you want to use.

The full build system user documentation in one document (e.g. to print out) can be found here.

Plugin documentation

This section lists available plugins for the build system and their dedicated user documentation.

You should only declare in your project description, the plugin you really use. That way, you keep your project build usage simple because the number of available targets is smaller, and the system works faster.

Core plugins

The compile, runtime, onlinelib and show plugins are described in the user's guide.

Reports

• javadoc : generates a javadoc report per set
• checkstyle : generates a checkstyle report per set
• junit : executes JUnit testcases and generates a report per set
• emma : instruments code and generates a code coverage report per set
• website : aggregates reports into a single entry point

Tools

• binrelease : binary module support
• resources : add support for resources directory per module
• commons-attributes : parses and generates attributes with the eponym Jakarta Apache tool

J2EE Integration

• j2ee-war, j2ee-web-tomcat, j2ee-web-weblogic, j2ee-ear, j2ee-ejb-jboss, j2ee-ejb-weblogic : generates a WAR or EAR for a module and deploys it in Tomcat, BEA Weblogic or JBoss

IDE Integration

• eclipse : integrates features in Eclipse

Internal documentation

• Developer's guide describes the build system internals and how to create a plugin.

User's Guide

General documentation

The EL4Ant build system is based on Ant and some basic concepts to ease the description and modularization of a project to build.

Introduction

EL4Ant is a Ant build file generator. This generation is controlled by a project description file which declares plugins used and modules.

The build file generation is called the configuration step, it corresponds to the configure Ant target invocation on bootstrap.xml or build.xml.

After configuration, the generated build.xml is used as a normal Ant build file.

Concepts

Ant

Ant is the well-known Java build tool from the Apache project http://ant.apache.org. It is the main component of the build system. It is included without any changes.

• A build file is an XML project description for Ant. It contains tasks organised in targets.
• A target is an entry point in the build file. Its name is invoked to execute its sequence of tasks.
• A task is an elementary component of the build file, with its parameters. Internally, it is a Java class with setters and the method execute.
• A property is a Ant variable to store information.

What you should know about Ant before using it:

• Ant looks for a build.xml build file by default. You can load another file name with the -f option.
• You can query a build file's documentation with ant -projecthelp.
• A build file declares a default target that is executed if no target is specified on the command line.
• You can specify a list of targets to execute sequentially in the same command, for instance ant target1 target2. It is faster because only one Java virtual machine is started to process all targets.

To know more about Ant, please consult the Ant manual.

Plugin

The build system provides an infrastructure to easily extend its behavior with plugins. Even core targets (compile, start) are defined in plugins, so they have to be declared in your project description to get a usable build system.

Plugins are read by the configuration process initiated by ant -f bootstrap.xml. The results of the configuration are a project specific build.xml and properties project.properties.

A plugin may depend on other plugins. If dependencies or configuration constraints are not fullfiled in a plugin description, the configuration may abort.

Module

A module is the minimal project component. It enables you to split your project into features-set or services.

It is defined by its relative path (for instance mysystem/core) and a set of specific child directories defined by plugins (for instance java to compile, docs for javadoc and sql for the SQL scripts). The module's path may contain as many subdirectories as needed by your project structure.

  module_root/
      java/
      docs/ 
      sql/
      [...]

In the project description, a module is declared with:

  <module path="mysystem/core">
    [...]
  </module>

A symbolic module name is associated with a module. If not specified, it is build from the path, removing the / characters. In the previous example, the module name is mysystemcore. The module name can also be set explicitly with the name attribute in the module element.

If the module definition is in a separate xml file (for instance mymodule.xml) and placed directly in module path (for instance mysystem/core) the attribute path can be omitted. Of course this separate xml file must be referenced by using directive include (for instance <include file="mysystem/core/mymodule.xml"/>) in project xml file.

Execution unit

An execution unit (eu) is a logical part of a module. It may be used optionally to provide internal structure to a module. Each execution unit of a module has its own deliverables (typically jar files) and runtime command definition.

An execution unit defines:

• A set of classes
• Dependencies
• Configuration

A module will be split into jars according to the execution unit definitions. Each execution unit will have its own runtime specification: ClassPath, main class, arguments, system properties.

The declaration of execution units in a module is optional. In fact, a module without eu element has a virtual default execution unit called 0, you may see that notation in generated properties, targets or hooks.

The main aim of execution units is to select classes to be deployed on different tiers - for instance client, server and batch. As a result runtime commands are configurable per execution unit. The execution unit definition is orthogonal to the module definition.

Examples are provided in project description section.

Dependency

A dependency enables to declare a module to module or module to jar class use. Dependencies are implicitly transitive: if a module A depends on B and module B depends on C, you can consider A automatically depends on C.

In fact, a dependency applies to execution units. A dependency may be limited to a specified execution unit; the configuration resolves implicit dependencies with the following patterns:

• A dependency to a jar without explicit execution unit limitation applies to all module execution units.
• Per execution unit, eu to eu dependencies are done if modules have same execution unit sets or none.

Attribute

An attribute is a configuration entry used by plugins. It may be defined in a plugin declaration for a global scope, in a module declaration or in an execution unit declaration to limit its scope to the corresponding object.

Consult the plugins documentation to know which attribute names are available for each scope.

Hook

A hook is an entry point in the build file target execution. Hooks allow to add specific behaviors during the execution of build system targets. Hooks are declared in plugins and hook targets registered on a hook chain are called within the target.

The hook invocation may be conditionned by a user property which acts as a switch.

Most of the time, a pre and a post hook is defined before and after an important target processing. Specific properties may be available to configure hook target implementation behavior.

Consult the plugins documentation to know which hook chains are available and which hook targets are registered by default. Most hooks are designed for plugin to plugin interaction.

Module set

Each module defines what sets it is contained in (sample sets could be tests, framework, or consoleApplication). To define the sets a module is part of, the set attribute is used. A set classifies modules in a logical group to apply a target on them.

The sets for a module can be declared with multiple set attributes or a single attribute with a list of set names separated by comas.

If a module does not declare a set attribute, it will be present in all sets from its module dependencies. If module A is in sets S1 and S2, and module B in set S3, then a module C that depends on A and B without explicitly declaring its sets will be in sets S1, S2 and S3.

If a module does not declare a set and has no dependencies, then it will be registered in the set default.

If a module declares the noset attribute, then it is not registered in any set.

Project description

Structure

The following graph shows the complete structure of the project.xml file:

+ <plugin  [name] [file]>
|   + <attribute  name [value | CDATA]>
|
+ <module  [name] [path]>
|   + <eu  name>
|   |  + <attribute  name [value | CDATA]>
|   |  + <hook  name target [action="append.(first|last)"]>
|   + <dependency  [jar | module] [eu] [inheritEuList]>
|   |  + {if module} <mapping  target [eu]>
|   + <attribute  name [value | CDATA]>
|   + <hook  name target [eu] [action="append.(first|last)"]>
|   
+ <hook  name target [module] [eu] [action="append.(first|last)"]>

• Here is the order of importance of the elements: attribute, plugin, module, dependency, eu, mapping, hook. You should learn how to use them in that order.
• All elements are optional.
• Elements order in the project description is only important for the plugin registration order and the module registration order according to the respective dependencies.
• When an include statement is analyzed, its content is registered immediately, so it has an impact on the registration order.

Project description examples are described later.

The attribute element

Attribute elements are used to configure the plugin behavior and Ant targets. The attribute scope depends on where it is set:

• global scope if set in a plugin element,
• module scope if set in a module element,
• module execution unit scope if set in a eu element.

Please refer to each plugin documentation to know available attribute names, expected values and scope(s).

The plugin element

In the normal case, a plugin declaration only uses the name attribute. The corresponding build file packaged in the plugin jar file is processed.

If the given name does not match any available plugins in the EL4Ant lib directory, the plugin can only be used to store attributes. Such a plugin is called virtual.

When developing a plugin, the file attribute must be provided. See for more details about plugin development.

The module element

A module declaration must set its directory path. A symbolic name can be set. A module can declare its dependencies, its execution units, its attributes and its hook targets.

Module execution units are optional. When no execution unit is specified, execution unit attibutes and hooks must be defined on the module level.

The dependency element

A module may depend on a third party jar or on another module.

A dependency to a jar applies by default to all module execution units. It can be specific to a module execution unit with the eu scope. The jar file may only be the file name which is then expected to be in lib/. It may be a path relative to the project directory or an absolute path.

A dependency to a module uses the target module name (explicitly declared or built from the path).

• If the eu scope is not set,
  • if inheritEuList=true is used, the target module execution unit list is declared in the current module.
  • if the target module has no execution unit, all module execution units depend on the single target module jar.
  • if the target module has execution units, each module execution unit depends on the target module execution unit with the same name if it exists (except if mapping is used).
• If the eu scope is set,
  • if the target module has no execution unit, the eu depends on the single module jar.
  • if the target module has execution units, the eu depends on the same eu of the target module (except if a mapping is used).

The mapping element helps to declare explicitly execution unit mappings.

The eu element

An eu element declares an execution unit for the module it is used in. Its name is mandatory. An execution unit can declare its attributes and its hook targets.

Attributes and hook target registrations are limited to the execution unit where they are declared.

The mapping element

It enables to create more complex dependencies from module to module, mainly when the module execution units are not the same. Multiple mapping elements may be used in the same dependency element.

• If the dependency eu scope is not set,
  • mapping target="targeteu" makes dependencies for each current module execution unit to the target module targeteu.
  • mapping eu="oneeu" target="targeteu" makes a dependency of the current module oneeu to the target module targeteu.
• If the dependency eu scope is set,
  • mapping target="targeteu" makes a dependency of the current module eu to the target module targeteu.

The hook element

It enables to plug a dedicated target in a plugin hook chain.

If the hook name contains the [module] pattern, then a hook chain is available per module. If the hook name contains the [module].[eu] pattern, then a hook chain is available per module execution unit.

If the hook element is used to register a target in a chain at the project level,

• this registration applies to all modules in case of [module] hook
• this registration applies to all execution units of all modules in case of [module].[eu] hook

If the hook element is used to register a target in a chain at the module level,

• this registration applies to the concerned module in case of [module] hook
• this registration applies to all execution units of the concerned module in case of [module].[eu] hook

If the hook element is used to register a target in a chain at the execution unit level,

• this registration applies to the concerned module in case of [module] hook
• this registration applies to the concerned module execution unit in case of [module].[eu] hook

A target invocation in a hook chain can be controlled by the if and unless attributes which expect a property name to check. With if, the target is invoked when the property is defined and different from false or no. With unless, the target is invoked when the property is not defined or equals to false or no. Property switching is designed to be used on the Ant command line with -Dpropertyname=t for instance.

The documentation of plugins describes the declared hook chains in the user targets and targets designed to be registered in a hook chain.

Examples

Simple description

Here is a simple project description:

<?xml version="1.0"?>
<!-- EL4Ant Project definition -->
<ant:project 
  name="helloworld" 
  xmlns="antlib:ch.elca.el4ant" 
  xmlns:ant="antlib:org.apache.tools.ant">

  <plugin name="compile"/>
  <plugin name="runtime"/>
  <plugin name="show"/>

  <module name="helloworldcommon" path="helloworld/common">
    <dependency jar="log4j-1.2.8.jar"/>
    <attribute name="set" value="helloworld"/>
  </module>

  <module name="helloworldapp" path="helloworld/app">
    <dependency module="helloworldcommon"/>
    <attribute name="runtime.runnable" value="true"/>
    <attribute name="runtime.class" value="helloworld.Main"/>
  </module>

  <module name="helloworldtests" path="helloworld/tests">
    <dependency module="helloworldcommon"/>
    <attribute name="junit.runnable" value="true"/>
    <attribute name="set" value="tests"/>
  </module>

</ant:project>

This description does not use execution units. Execution unit attributes are so declared at the module level.

Execution unit usage

Consider this short project description:

• Module mytool without execution unit. The jar mytool.jar will be generated with the whole module content.
• Module myservice
  • Execution unit interface: The jar myservice-interface.jar contains common classes and the service interface.
  • Execution unit implementation: The jar myservice-implementation.jar contains common classes and the service interface and implementation. Only this eu depends on the mytool module.
• Module myapp
  • Execution unit client: The jar myapp-client.jar contains client code deployed with Java WebStart. The client eu depends on myservice.interface to be able to remotely call myservice.
  • Execution unit server: The jar myapp-server.jar contains a server component deployed in a EJB container to provide a remote myservice interface implementation. The server eu depends on myservice.implementation.
  • Execution unit batch: The jar myapp-batch.jar provides automation to call myservice with parameters provided in a file transmitted by FTP.

<?xml version="1.0"?>
<!-- EL4Ant Project definition -->
<ant:project 
  name="example" 
  xmlns="antlib:ch.elca.el4ant" 
  xmlns:ant="antlib:org.apache.tools.ant">

  <plugin name="compile"/>
  <plugin name="runtime"/>
  <plugin name="show"/>

  <module name="mytool" path="modules/tool">
    <dependency jar="log4j-1.2.8.jar"/>
  </module>

  <module name="myservice" path="modules/services/food">
    <eu name="interface">
      <attribute name="compile.jar.excludes" value="**/implementation/**"/>
    </eu>
    <eu name="implementation">
    </eu>

    <dependency eu="implementation" module="mytool"/>
  </module>

  <module name="myapp" path="applications/food">
    <eu name="client">
      <attribute name="compile.jar.includes" value="**/client/**"/>
      <!-- TBD: Attributes to generate Java WebStart package -->
    </eu>
    <dependency eu="client" module="myservice">
      <!-- myapp.client depends on myservice.interface -->
      <mapping target="interface"/>
    <dependency>

    <eu name="server">
      <attribute name="compile.jar.includes" value="**/server/**"/>
      <!-- TBD: Attributes to generate EJB specific artefacts -->
    </eu>
    <dependency eu="server" module="myservice">
      <!-- myapp.server depends on myservice.implementation -->
      <mapping target="implementation"/>
    <dependency>

    <eu name="batch">
      <attribute name="compile.jar.includes" value="**/batch/**"/>
      <attribute name="runtime.runnable" value="true"/>
      <attribute name="runtime.class" value="app.Batch"/>
    </eu>
    <dependency eu="batch" module="myservice">
      <!-- myapp.batch depends on myservice.interface -->
      <mapping target="interface"/>
    <dependency>
  </module>

</ant:project>

Hook usage

The hook concept enables to plug additional behavior in a plugin target. The most interesting hook chain is runtime.[module].[eu] which is used to tune a Java application command line to run.

A target registration in a hook is permanent except when if or unless attributes are used.

<?xml version="1.0"?>
<!-- EL4Ant Project definition -->
<ant:project 
  name="helloworld" 
  xmlns="antlib:ch.elca.el4ant" 
  xmlns:ant="antlib:org.apache.tools.ant">

  <plugin name="compile"/>
  <plugin name="runtime"/>
  <plugin name="show"/>

  <module name="helloworldcommon" path="helloworld/common">
    <dependency jar="log4j-1.2.8.jar"/>
    <attribute name="set" value="helloworld"/>
  </module>

  <module name="helloworldapp" path="helloworld/app">
    <dependency module="helloworldcommon"/>
    <attribute name="runtime.runnable" value="true"/>
    <attribute name="runtime.class" value="helloworld.Main"/>
    <hook 
      name="runtime.[module].[eu]" 
      target="runtime.hook.jvm.verbose"
      if="jvmverbose"/>
  </module>

  <module name="helloworldtests" path="helloworld/tests">
    <dependency module="helloworldcommon"/>
    <attribute name="junit.runnable" value="true"/>
    <attribute name="set" value="tests"/>
    <hook 
      name="runtime.[module].[eu]" 
      target="runtime.hook.jvm.verbose"
      if="jvmverbose"/>
  </module>

</ant:project>

In the previous example, the Java command executed by target start.module.eu.helloworldapp and start.module.eu.helloworldtests will be turned in verbose mode (JVM option -verbose) when the property jvmverbose is set.

  ant start.module.eu.helloworldapp -Djvmverbose=

Plugin documentation details the available hook and their usage in most use cases.

Special features

Automatic reconfiguration

When a target of the build.xml is invoked, EL4Ant checks that the project configuration is up-to-date compared to the project description files. If not, a new configuration is automatically done before the listed targets are invoked - if possible, because they may have been removed from the project.

Automatic module section

The autoselect feature enables you to invoke a target with its generic name from a module directory. EL4Ant automatically deduces the module the target should apply on according to the invocation directory.

Suppose a module mymodule which directory path is myproject/mymodule has been declared in the project. The target ant compile.module invoked from a sub-directory of myproject/mymodule/ automatically defines the module property to mymodule and compile.module compiles only mymodule.

If the automatically selected module has only one execution unit, it is selected too, so generic target relative to an execution unit can be used.

Note: this feature only make sense if Ant is used with -find build.xml. For comfort, it is advised to set the option in the ant script directly.

Shortcut generation filter

By default, generated shortcuts do not have descriptions to prevent them to be shown by ant -projecthelp. If you want some targets to be visible, you can make them visible with the property project.visible.shortcuts in etc/bootstrap.properties:

## Visible shortcuts regexp list (use java.util.regex.Pattern regexp)
project.visible.shortcuts=start.*\.module\.eu.*,compile\.rec\.module\.helloworld.*

The previous line adds a description to matching shortcuts, so they are shown by the command ant -projecthelp.

Core system plugins documentation

Introduction

For each plugin, the documentation explains:

• what the plugin is designed to do
• Declaration : how to declare the plugin with its minimal configuration
• Dependencies : if the plugin depends on others
• Usage : how to use the plugin in everyday work
• Targets : list of available Ant targets the user may invoke. If the mention Shortcuts are generated is present, this means a module/execution unit specific target is generated for properly configured module/execution unit in the build file to ease target invocation. For instance, compile.module.mymodule is generated to invoke compile.module if the module mymodule is compilable. Use ant -v -projecthelp to list all generated targets. See generation filter configuration for shortcuts.
• Attributes : how to configure the plugin to suit your specific needs
  • Global : plugin level attributes to configure globally the plugin behavior or set default attribute values for all module/execution unit.
  • Per module : attribute to configure how the plugin works with the module
  • Per execution unit : if used, configure how the plugin works with the specified exection unit. If no execution unit is used, the same attribute name can be used at module level to configure targets behavior.
• Hooks : plugin defined hooks to enhance targets behavior for advanced users or plugin developpers, and specific properties available for a target registered in each hook.

Compile

This plugin compiles Java sources from each module's java/ directory to the corresponding classes/ directory.

Declaration

  <plugin name="compile"/>

Usage

Most important targets are compile and jars.

A module without specific attributes is expected to have a java/ directory (default of compile.sources.directory). Java sources are compiled in a dedicated classes/ directory (by default in dist/classes).

A module without sources to compile, but only with resources to include in jar files and in ClassPath, must set the compile.nosources module attribute.

A module without sources nor resources to include in ClassPath must set the compile.noclasses module attribute. It implies automatically compile.nosources. Such a module may exist to provide files for other modules (for instance webapp/ resources to be included in a WAR).

A manifest file per execution unit is generated in the classes directory as META-INF/Manifest-eu.mf. This manifest provides the Class-Path attribute with third-party jar file names and project jar dependencies. As a result, META-INF/Manifest-*.mf files are excluded when packaging execution unit jar files.

Targets

• compile compiles all modules.
• compile.module compiles a specific module and copy resources to classes/. Shortcuts are generated.
• compile.rec.module compiles a specific module and recursively its dependencies. Shortcuts are generated.
• jars compiles and builds all module jar files.
• jars.rec.module compiles and builds a specific module's jar files and recursively its dependencies. Shortcuts are generated.
• clean cleans all modules.
• clean.module cleans a module. Shortcuts are generated.
• clean.rec.module cleans a module and its dependencies. Shortcuts are generated.
• compile.clean.hook is the default target registered in clean.[module] hook chain. It is responsible to delete classes directory and generated jars files.
• jars.manifest.module.eu generates the META-INF/Manifest-eu.mf file per execution unit with its Class-Path attribute. It is registered in the pre.jar.[module].[eu] hook chain.

The compile and jars targets checks if the source directory java/ is present in the module directory. If not, nothing is done.

Attributes

Global

• compile.resources.includes is the global value for the includes argument for the Ant fileset used in copy task from java/ to classes/ directories. Default is **/*.
• compile.resources.excludes is the global value for the excludes argument for the Ant fileset used in copy task from java/ to classes/ directories. Default is **/.cvsignore,**/*.java,**/doc-file/*.
• compile.jar.includes is the global value for the includes argument for the Ant fileset used in jar task on the classes/ directory. Default is **/*.
• compile.jar.excludes is the global value for the excludes argument for the Ant fileset used in jar task on the classes/ directory. Default is empty.
• compile.sources.directory is the directory name where the module Java source files are located. This property applies to all modules. Default is java.
• compile.classes.directory is the directory path where Class files must be generated. Argument 0 is the declared module path and argument 1 is the module name. Default is dist/classes/{1}. You may want generated classes in {0}/classes for instance.

Per module

• compile.resources.includes is the module value for the includes argument for the Ant fileset used in copy task from java/ to classes/ directories. Default is the same global attribute's value.
• compile.resources.excludes is the module value for the excludes argument for the Ant fileset used in copy task from java/ to classes/ directories. Default is the same global attribute's value.
• compile.nosources is a flag to mark that the java/ directory does not exists. Compiled jar files (execution units) are used if they exist. Default value is false.
• compile.noclasses is a flag to mark that classes/ and jar files must not be generated. Default value is false.
• compile.classes is the specific location of the module classes/ directory. If not set, it is generated from plugin compile.classes.directory pattern.

Per execution unit

• compile.jar.includes is the execution unit value for the includes argument for the Ant fileset used in jar task on the classes/ directory. Default is the same global attribute's value.
• compile.jar.excludes is the execution unit value for the excludes argument for the Ant fileset used in jar task on the classes/ directory. Default is the same global attribute's value.
• compile.jar is an optional attribute to set the jar file name. Its default value is modulename-eu.jar. If the name is a single file name without directories, then it is relative to dist/lib. If the file path is relative, it is relative to the project directory.

Hooks

• pre.compile.[module] and post.compile.[module] called unconditionnaly in compile.module. If the module is compilable (when compile.nosources flag is not set), pre.javac.[module] and post.javac.[module] are called around the javac task invocation. The following properties are set to be used in targets registered on that hook chains:
  • module is the current module name
  • module.src is the module java/ directory
  • module.classes is the module classes/ directory
  • module.classpath is the module compilation ClassPath
  • module.src.exists is set if the java/ directory is available
  • module.resources.includes is the module includes argument for the Ant fileset used in copy task from java/ to classes/ directories
  • module.resources.excludes is the module excludes argument for the Ant fileset used in copy task from java/ to classes/ directories

• pre.jar.[module].[eu] and post.jar.[module].[eu] called in jars.rec.module. The following properties are set:
  • module is the current module name
  • eu is the current execution unit name
  • jarfile is the target jar file to create or update
  • module.src is the module java/ directory
  • module.classes is the module classes/ directory
  • module.src.exists is set if the java/ directory is available
  • module.classes.includes is the module includes argument for the Ant fileset used in jar task on the classes/ directory
  • module.classes.excludes is the module excludes argument for the Ant fileset used in jar task on the classes/ directory

• clean.[module] is used to register cleaning task per module according to generated files. Default chain contains compile.clean.hook.

Hooks are called even if the source directory java/ is not present.

Runtime

This plugin provides execution targets to run a java command corresponding to a module execution unit.

Declaration

  <plugin name="runtime"/>

Dependencies

• compile

Targets

• start.module.eu executes the java command for a module execution unit with generated jars in ClassPath. Shortcuts are generated if the module or execution unit runtime.runnable is set.
• startdev.module.eu executes the java command for a module execution unit with classes/ directories in ClassPath. Shortcuts are generated if the module or execution unit runtime.runnable is set.

Attributes

Global

• runtime.default.command.creator must be a valid java command creator. Default value is runtime.command.creator.basic.

Per module

• runtime.runnable declares that all execution units are runnable if the attribute value is true . By default a module is not runnable.

If no execution unit is declared,

• runtime.directory is the execution directory. Default is dist/runtime.
• runtime.command.creator can define the module specific java command creator. See command creators section.
• In case you use runtime.command.creator.basic, runtime.class must be set to a class name with public static void main(String[]) method.

Per execution unit

• runtime.runnable declares that the concerned execution unit is runnable if the attribute value is true (or not defined). By default an execution unit is not runnable.
• runtime.directory is the execution directory. Default is dist/runtime.
• runtime.command.creator can define the execution unit specific java command creator. See command creators section.
• In you use runtime.command.creator.basic, runtime.class must be set to a class name with public static void main(String[]) method.

Command creators

Command creators are targets used to create the original java command before hook targets registered in runtime.[module].[eu] are called to modify it.

The creator definition with runtime.command.creator has a specific behavior. If an execution unit does not specify a creator, the first creator defined in its dependencies is used. If no creator definition is found, then the plugin default setting is used. Only one creator per execution unit can be defined.

• runtime.command.creator.basic creates a basic java command, using the execution unit attribute runtime.class (or the module attribute if no eu)

A plugin may provide alternate runtime command creators but its usage is hidden.

Basic command creator argument passing

When running a execution unit with the runtime.command.creator.basic (default behavior), the runtime.class is used as main class.

You can pass arguments to the main class different ways:

• with runtime.arguments attribute set in the module execution unit
• with -Druntime.arguments="arg1 arg2 arg3" set in the Ant command line
• in any case, -Druntime.append.arguments="arg4 arg5" can be used to append arguments to the current list (from runtime.arguments property)

Hooks

• runtime.[module].[eu] hook is designed to enable the modification of the java command created by the module runtime.command.creator. The name of the current java command is command.${module}.${eu}. Those hook targets are called recursively in module dependencies by the start targets.
• pre.start.[module].[eu] targets are called before java command creation.
• post.start.[module].[eu] targets are called after java command execution ends.

Registered targets in these three hooks can work with the following properties:

• module is the caller module name
• eu is the caller execution unit name
• module.eu.classpath is the module execution unit class with jars or module classes according to the caller target (start or startdev)
• module.runtime.creator is the module creator target.
• module.eu.dependencies is the module.eu dependency list for the current execution unit.

When the runtime.command.creator.basic is used, runtime.[module].[eu] and post.start.[module].[eu] targets can work with the following property:

• module.eu.class is the current execution unit runtime.class main class to run.

Show

This plugin shows the project model information on the console with Ant logging INFO level at the end of the project configuration (execution of ant -f bootstrap.xml or ant configure when already configured) with the [Model] task prefix.

Currently displayed information: Modules, execution units, dependencies to jars and to module with eu mappings, sets with modules registered in them.

Declaration

  <plugin name="show"/>

Online library

This plugin downloads lacking jar files from a list of repositories according to its file name.

Declaration

  <plugin name="onlinelib">
    <attribute name="onlinelib.repository" value="http://el4.elca-services.ch/el4ant/jars/"/>
    <attribute name="onlinelib.repository" value="http://el4.elca-services.ch/el4ant/jar-sources/"/>
  </plugin>

Usage

You can easily create your own repositories of files using all supported protocol by wget : http://, ftp:// or even file:// if local. Expected files must be available in a the refered directory.

When the plugin is declared, download of lacking files is effective, and if a file is optional, the trial is done at each configuration, which slows the configuration step.

Here is a way to control when the download can be done. Use the following declaration in your project description:

<antcontrib:if xmlns:antcontrib="antlib:net.sf.antcontrib">
  <ant:isset property="online"/>
  <antcontrib:then>
    <plugin name="onlinelib" file="buildsystem/core/onlinelib.xml">
      <attribute name="onlinelib.repository" value="http://el4.elca-services.ch/el4ant/jars/"/>
      <attribute name="onlinelib.repository" value="http://el4.elca-services.ch/el4ant/jar-sources/"/>
    </plugin>
  </antcontrib:then>
  <antcontrib:else>
    <ant:echo level="info">You can enable online plugin with -Donline=t at configuration to download files.</ant:echo>
  </antcontrib:else>
</antcontrib:if>

So the plugin onlinelib is only declared when the system property online is set on the command line.

  ant -f bootstrap.xml configure -Donline=t

Attributes

Global

• onlinelib.repository declares a repository URL. Mind the ending /, for instance http://el4ant.sourceforge.net/repository/jars/. No default value. The attribute may be used many times to declare more than one repository.

Reports

Javadoc

This plugin provides javadoc generation targets.

Declaration

  <plugin name="javadoc">
    <attribute name="javadoc.set.list" value="application"/>
    <!-- Javadoc configuration for application set -->
    <attribute name="javadoc.application.access" value="protected"/>
    <attribute name="javadoc.application.doctitle">
<![CDATA[<h1>My Application Documentation</h1>]]></attribute>
    <attribute name="javadoc.application.windowtitle">My Application API</attribute>
  </plugin>

This declaration is an example of configuration for a javadoc generation of a module set called application.

An equivalent way of declared javadoc set attributes is:

  <plugin name="javadoc"
    xmlns:javadoc="antlib:ch.elca.el4ant.javadoc">
    <attribute name="javadoc.set.list" value="application"/>
    <!-- Javadoc configuration for application set -->
    <javadoc:config set="application">
      <javadoc:attribute name="access" value="protected"/>
      <javadoc:attribute name="doctitle">
<![CDATA[<h1>My Application Documentation</h1>]]></javadoc:attribute>
      <javadoc:attribute name="windowtitle">My Application API</javadoc:attribute>
    </javadoc:config>
  </plugin>

Usage

This plugin generates a javadoc per module set. A module can be registered in one or many sets thank to the set attribute. Please read details about module sets.

For more details about the javadoc plugin attributes, please read the javadoc Ant task documentation.

When used with the website plugin, javadoc are generated in the website.directory and a report entry is added in the project project page.

Targets

• javadoc generates all javadoc reports for the module sets declared in javadoc.set.list.
• javadoc.set generates the javadoc report for a specific module set.

Attributes

Global

If a javadoc attribute is not explicitly defined for a specific set, its value remains the default one. The upper case SET notation is used here to represent a module set name.

• javadoc.set.list is the list of module sets for which the javadoc target generates reports by default. Default value is the list of known module sets.
• javadoc.SET.destdir is the Ant javadoc destdir parameter. Default value is dist/javadoc/SET/ or javadoc/SET in website.directory when used with website plugin.
• javadoc.SET.PARAMETER is the Ant javadoc PARAMETER value for the set SET. For instance javadoc.myset.access is the Ant javadoc access parameter for myset and possibile values are private, protected, public. Default values for all parameters are given in the following table.

Parameter	Default value
access	private
author	true
bottom
breakiterator
charset
doctitle	Application API
docencoding
encoding
footer
header	Application API
helpfile
linksource
locale
maxmemory	128m
nodeprecated
nodeprecatedlist
nohelp
nonavbar
noindex
notree
packagenames	*
serialwarn
splitindex
stylesheetfile
use	true
verbose
version	true
windowtitle	Application API

When a parameter has a default value, its value can be changed with the attribute javadoc.default.PARAMETER.

The special parameter antelements can be used to pass xml blocks directly to the Ant javadoc task for the set, like the group element for example:

<attribute name="javadoc.el4ant.antelements">
  <![CDATA[<group title="Plugins">
    <package name="ch.elca.el4ant.*"/>
  </group>
  ]]>
</attribute>

Hooks

• pre.javadoc and post.javadoc called unconditionnaly
  • set is the current set
  • set.additonalparam can be appended to pass additional parameters to the javadoc command

Known issues

I get message No source files and no packages have been specified

The javadoc and javadoc.set targets may fail with the message: No source files and no packages have been specified.

This means the processed module set does not contain any source file. It may come from:

• an empty set: no module in the set
• modules without java/ directories (such as binary modules)
• modules with empty java/ directories

You can ignore this message. Only the report for the concerned set is not generated. The message will disappear as soon as at least one source file will be present in the module set.

I get warnings about unknown packages or classes from import statements

It is most likely the concerned classes are in modules in dependence but are not compiled. First run compile target and try again.

I can not create Javadoc with JDK1.5 if a module has Commons Attributes enabled

There is a bug in CATaglet class of Commons Attributes. Please replace existing jars with name commons-attributes-compiler-2.2.jar with the following http://el4.elca-services.ch/el4ant/jars/commons-attributes-compiler-2.2.jar or use EL4Ant version > 0.9.2 or upper.

Javadoc parameter bottom is wrong used on Windows

There is a bug that parameter bottom is taken as package name instead as html page bottom line. Further if the bottom parameter is long, javadoc generation will fail.

ToDo

• collect module docs directories
• support doc-file directories
• add parameters: group, overview, link.

Checkstyle

This plugin uses the eponym SourceForge project to analyze Java source files or any other text files: HTML, XML, properties, ...

Declaration

  <plugin name="checkstyle">
    <attribute name="checkstyle.config" value="etc/checkstyle_el4ant_checks.xml"/>
    <attribute name="checkstyle.properties" value="etc/checkstyle_el4ant.properties"/>
    <attribute name="checkstyle.set.list" value="application,tests"/>
  </plugin>

Warning: checkstyle.config and checkstyle.properties attributes are mandatory.

Usage

The target checkstyle generates a report per module set. A module can be registered in one or many sets thank to the set attribute. Please read details about module sets.

For more details about Checkstyle configuration files, please read the tool documentation.

When used with the website plugin, checkstyle reports are generated in the website.directory and a report entry is added in project reports overview.

Targets

• checkstyle generates reports for all module sets (checkstyle.set.list).
• checkstyle.set generates the report for a specific set.

Attributes

Global

• checkstyle.set.list is the module set list for which the checkstyle target generates reports by default. Default value is the list of known module sets.
• checkstyle.config refers to the checkstyle XML configuration file. This attribute is mandatory. No value by default.
• checkstyle.properties refers to the property file used in the checkstyle XML configuration file. This attribute is mandatory. No value by default.

ToDo

• Add a check for configuration attributes. Current state: if not set, the user targets fail when calling them.
• Be able to use default properties and rules included in the plugin jar if configuration attributes are not set by the user.

Known bugs

• The checkstyle and checkstyle.set targets does not work from another directory than the project directory if checkstyle configuration or properties refer to other files relatively (a header for instance). I think it is a bug of the checkstyle Ant task: it loads files from the JVM current directory instead of using Ant relative file resolution.
• Checkstyle report generation does not output files properly with Jdk 1.5. The project root directory is polluted.
• Checkstyle localization files are incorrects for french. As a result you must work around the following failure: IllegalArgumentException: can't parse argument number '' et '' with a language setting in Ant script ANT_OPTS="-Duser.language=en"

JUnit

This plugin provides a java command creator to execute JUnit test cases in a module and a target to generate a global report.

Declaration

  <plugin name="junit">
    <attribute name="junit.jar" value="junit-3.8.1.jar"/>
  </plugin>

Dependencies

• runtime and compile

Usage

At execution unit or module level, you have to declare the following attribute to enable JUnit support:

  <attribute name="junit.runnable" value="true"/>

It is exactly equivalent to add the junit.jar global attribute as jar dependency to the module and to add the following runtime attributes:

  <attribute name="runtime.runnable" value="true"/>
  <attribute name="runtime.command.creator" value="runtime.command.creator.junit"/>

Now, the module declared as runnable will have a start.module.eu shortcut in the build.xml file. Call one of start.module.eu.mymodule.myeu or startdev.module.eu.mymodule.myeu (or eventually without .myeu if the module has no execution unit declared) will execute JUnit with all the module's selected test cases.

An XML report per test case is generated in dist/junit.

As a shortcut, invoke junit.start.all or junit.startdev.all targets will run all junit modules declared in the project.

Then the set reports can be generated with junit.report that collects all available test cases XML reports in dist/junit for a module set and writes a global HTML report in ${reports.directory}/junit/SET or in dist/junit/SET if reports directory is not set.

If the website plugin is configured, the reports.directory is used and a report entry is added to the project reports overview.

To clean reports, the junit.clean.report target can be used.

Advanced usage

Change default runner

You can change default runner globally with the attribute junit.default.runner set in the plugin configuration. You may also set the runner to use for a specific module execution unit with the junit.runner attribute or just for a command invocation with the property set -Djunit.runner=junit.swingui.TestRunner (for instance) when a runtime target is called with a JUnit module.

Run a specific TestSuite

By default, the JUnit runner execute the suite method of the ch.elca.el4ant.junit.CollectionSuite class to detect TestCase implementation in the module classes directory.

To prevent test case detection, you may set the junit.collectionsuite.suite attribute with a TestCase class name or a class name with a static suite method. This attribute can be set on a specific module execution unit, or set for a command invocation with the property -Djunit.collectionsuite.suite=mypackage.MyTestCase on the command line.

XML reports are generated for the selected suite.

Change default TestSuite

By default, the JUnit runner execute the suite method of the ch.elca.el4ant.junit.CollectionSuite class to detect TestCase implementation in the module classes directory.

You may want to run your own suite, providing a subset of test cases to the runner. It can be done for a specific module execution unit with the junit.suite attribute or just for a command invocation with the property -Djunit.suite=mypackage.MyTestCase set when a runtime target is called with a JUnit module. The class must be a JUnit TestCase or provide a static suite method that returns a JUnit TestSuite. Of course, the specified class must be available in the ClassPath.

As far as the EL4Ant CollectionSuite is responsible to generate XML reports, setting the suite to run prevent reports to be generated.

Hide execution output

The attribute junit.collectionsuite.showoutput may be set on a module or an execution unit to prevent test execution output to be published on the Ant console. Its default value is true. This attribute can also be set on the execution command line to hide output for this single run with -Djunit.collectionsuite.showoutput=false. Even if output is hiden, it is stored in XML reports.

Attributes

Global

• junit.jar is the jar name to use as dependency. Default value is junit.jar.
• junit.set is the set name to add to junit modules. Default value is empty, in that case, no change is done on module sets.
• junit.set.list is the list of module sets for which reports are generated. Default value is the list of known module sets.
• junit.default.runner is the default JUnit runner used to run test suite.

Per execution eu

• junit.runner is the JUnit runner used to run test suite in the concerned module execution unit. Default value is the value set to junit.default.runner. This attribute may be set to a module if no execution unit is declared.
• junit.collectionsuite.showoutput is a switch to hide Java test execution output on the Ant console. Default value is true.
• junit.collectionsuite.suite is a TestCase name class or a class name with a suite method. This class is run by the CollectionSuite if set. Default behaviour of the CollectionSuite is to detect available test cases.
• junit.suite is a TestCase name class or a class name with a suite method. Default value is ch.elca.el4ant.junit.CollectionSuite.

Targets

• junit.start.all calls start.module.eu on all execution unit modules that are configured to be run with JUnit.
• junit.startdev.all calls startdev.module.eu on all execution unit modules that are configured to be run with JUnit.
• junit.report generates the test reports for all set in the dist/junit directory or in the reports.directory.
• junit.report.set generates the test report for a specific set.
• junit.clean.report cleans the generated test reports for all module sets.
• runtime.command.junit.creator is the java command creator to use as execution unit runtime.command.creator.

Hooks

• pre.junit.report and post.junit.report are called before and after the set report generation.

ToDo

• Support JAR for binary module
• Report JVM crash and exit

EMMA

This plugin uses the eponym SourceForge project to provide Java code coverage.

Declaration

Here is the recommended configuration for EMMA plugin:

  <plugin name="emma">
    <attribute name="emma.set.list" value="application"/>
    <attribute name="emma.mode" value="offline"/>
    <attribute name="emma.switch" value="emma"/>
  </plugin>

Usage

EMMA is a Java code coverage tool that is designed to work with instrumented classes. This instrumentation step can be done on-the-fly by a dedicated ClassLoader with non instrumented classes (online mode), or in any JVM runtime context with instrumented classes (offline mode).

Application must be executed after EMMA instrumentation to collect code coverage data, then the report generation provides you a comfortable way to analyze the code that has not been executed. You can run as many execution targets as possible or even the same target many times, code coverage data are merged with any previous execution data.

Offline mode

The offline mode should be preferred to collect code coverage information in any context: simple application, test cases or J2EE application deployed as a EAR or a WAR.

With the recommended configuration provided below, you have to use compile target to instrument classes before executing your application with the emma property set on the command line:

  ant compile junit.startdev.all startdev.module.eu.mymodule.myeu -Demma=t

Code coverage information are collected, ready to be used in report generation.

Online mode

The online mode (on-the-fly) should be reserved to simple application and test cases execution.

Its advantage is to skip the classes instrumentation step needed for the offline mode.

  <plugin name="emma">
    <attribute name="emma.set.list" value="application"/>
    <attribute name="emma.mode" value="online"/>
    <attribute name="emma.switch" value="emma"/>
  </plugin>

As instrumentation step is not needed, if your classes are already compiled, you can execute your runtime targets directly with emma set.

  ant junit.startdev.all startdev.module.eu.mymodule.myeu -Demma=t

Report generation

The target emma.report generates a code coverage report per module set with currently available code coverage data, generated by EMMA-enabled execution targets. A module can be registered in one or many sets thank to the set attribute. Please read details about module sets.

For more details about EMMA usage, link report interpretation, please read the tool documentation.

When used with the website plugin, EMMA are generated in the reports.directory and a report entry is added to the project reports overview.

Advanced manual configuration

This section describes how to enable EMMA support with a more fine grain, it is reserved for expert users. In that case, the global plugin emma.mode and emma.switch must not be set.

The hook registrations described here are exactly the same that the plugin configuration does automatically on runnable module execution units marked with the emma.mode attribute.

Advanced offline mode

Classes instrumentation is done by registering the following hook in your project description:

  <!-- add emma.instrumentation target in the compile hook -->
  <hook name="post.javac.[module]" target="emma.instrumentation.module"/>

If the hook is at the project level, it applies to all available modules. If the hook is declared at the module level, it only applies to the concerned module.

Classes instrumentation is not enough. EMMA jar must be available in your Java command ClassPath. To do so, the runtime.hook.emma.offline target must be registered in the runtime.[module].[eu] hook chain, at least for runnable module execution units.

  <hook name="runtime.[module].[eu]" target="runtime.hook.emma.offline"/>

If the hook is at the project level (faster but not advised), all runnable execution unit modules are concerned. If declared at the module level, all execution units of the module are concerned. If declared at the execution unit level, only that execution unit is concerned.

As a result, code coverage data are collected for modules that are both instrumented (emma.instrumentation.module hook) and executed by a runtime target with the runtime.hook.emma.offline target registered in the runtime hook chain.

Advanced on-the-fly mode

The instrumentation hook must be removed (emma.instrumentation.module) and the runtime hook must be renamed: use runtime.hook.emma.online instead of runtime.hook.emma.offline at the same place you have defined your module and execution unit hooks.

  <hook 
    name="runtime.[module].[eu]"
    target="runtime.hook.emma.online"
    if="emma"/>

  ant startdev.module.eu.mymodule.myeu -Demma=

Targets

• emma.report generates reports for all module sets (emma.set.list).
• emma.report.set generates the report for a specific set.
• runtime.hook.emma.offline is the runtime hook to enable offline code coverage in a Java command with instrumented classes.
• runtime.hook.emma.online is the runtime hook to enable online code coverage in a Java command with non instrumented classes.
• emma.instrument invokes emma.instrument.module on all modules.
• emma.instrument.module invokes EMMA incremental (only modified classes) instrumentation on a module classes directory. This target is designed to be registered in the post.javac.[module] hook chain.

Attributes

Global

• emma.mode is the default code coverage mode used for all runnable modules. If set to offline, all module classes are instrumented.
• emma.switch is the name of a property to enable instrumentation and code coverage support. If not defined, support is permanent. If defined, compilation must be done with this property set to enable instrumentation, and runtime targets must be executed also with this property set.
• emma.set.list is the module set list for which the emma.report target generates reports by default. Default value is the list of known module sets.

Per module

• emma.mode is the module code coverage mode. If set to offline and global mode is not offline, then the module classes are instrumented.

Per execution unit

• emma.mode is the execution unit code coverage mode. If set to offline and global mode is not offline, then the module classes are instrumented.

Known issue

• EMMA on-the-fly code coverage analysis is not able to work with already instrumented classes. As a result, you have to clean and compile again your instrumented modules to switch from the offline usage to the online mode.
• Current version outputs a text report in dist/runtime when running a command in on-the-fly mode.

Website

This plugin provides a single entry point to generated a project website including reports.

Declaration

  <plugin name="website">
    <attribute name="website.resources" value="etc/website/resources"/>
    <attribute name="website.templates" value="etc/website/templates"/>
  </plugin>

Usage

When the plugin is configured, other plugin generates reports in the site, generally per module set. The target website generates the site with current available reports. In order to include generated reports, other plugin targets must be called previously, like javadoc or junit.report for instance. Refer to plugins documentation to be aware of available report capabilities.

The source files to generate website may be customized for your project. Look at website.resources and website.templates values for EL4Ant project and that directories content as a example.

Target

• website generates the site pages and menu.
• website.clean cleans the complete site, pages and reports.

Attributes

Global

• website.resources is a comma separated list of directories from which resources must be copied into generated site (reports.directory). Default value is empty.
• website.templates is a comma separated list of directories containing *.html.vm Velocity templates which are processed to generate corresponding *html pages. Included section must not match the *.html.vm pattern. Default value is empty.
• reports.directory is the place where pages and other reports are generated. Default value is dist/website.
• website.donotclean controls if the site is cleaned by the distclean target (when false). Default value is false.

ToDo

• Create a single pretty stylesheet for the menu, the home page, the overview and all other reports (junit, javadoc, checkstyle, ...)
• Improve this documentation to explain which objects are available in Velocity templates.

Tools

Resources

This plugin provides support for including resources in ClassPath. These resources are stored in other source directories than the compilation source directory compile.sources.directory (default to java/).

Declaration

  <plugin name="resources">
    <attribute name="resources.directories" value="conf"/>
  </plugin>

Usage

When the plugin is declared, the files available in the list of resources.directories for a module are copied into classes/ when compile.module is invoked. The exclusion filter compile.resources.excludes is applied. Of course, files are included in jar files according to the execution unit filters.

When a module resource directory does not exist, it is ignored without any warning.

Target

• resources.copy.module copies the resources files for a given module. This target is automatically invoked after the target compile (hook post.compile.[module]).

Attributes

Global

• resources.directories is the list (comma separated) of optional directories to consider as resources in a module.

Known issue

The Eclipse plugin manages the directories declared in resources.directories as source directories. But the directory is declared in .project only if it exists when the project configuration is done. If you add a new resource directory in a module, you have to force a new project configuration with ant configure and to refresh concerned Eclipse projects.

Commons attributes

This plugin provides support for commons attributes. It takes care of generating and compiling the adequate classes for the attributes in all the modules that uses commons attributes.

When using multiples execution units, you must take care that the filter pattern you set for selecting the classes for a given execution unit also includes the corresponding generated attribute classes!

Target

• commons-attributes compiles the commons attributes for all the modules that use them.
• commons-attributes.module compiles the commons attributes for a specific module. This target will be automatically invoked after the target compile (hook post.compile.[module]).

Attributes

Per module

• commons-attributes.enable marks, when set to "true", that the module uses commons attributes.

Binary release

This plugin provides two mechanisms: support to use binary module releases and the generation of binary module releases from source modules.

Declaration

  <plugin name="binrelease"/>

Usage

What a binary module is

A binary release is a module zip file with the module content without typically the java/ and classes/ directories, plus a lib/ directory containing the jars for each execution, plus a generated module description file module.xml.

Here is for instance the zip content for service_1.0.zip file:

   module.xml
   lib/service-interface.jar
       service-implementation.jar
   sql/
   webapps/

Note: the module.xml is generated by the plugin from the original module declaration, wherever it is. There is no need to create a module.xml in the module directory.

Third party jars are not included in the module zip file itself. As they are declared in the module.xml, they are expected to be in the project's lib/ directory. Here is the reason why: a user is aware of which jars are used simply by looking in lib/, so he will of course avoid to add another version of an already used library (in a binary module) in the project ClassPath with potential conflits.

How to create binary modules

A module must have the attribute binrelease.version to be released as a binary module in a zip file. The attribute value is considered as the module version (for instance 1.1). It is used to create the zip file name.

The targets binrelease or binrelease.module must be used and zip files will be generated in binrelease.output.directory.

Note: you may remove the java/** pattern from the binrelease.excludes attribute in order to include source files in the generated zip. In that case, Eclipse is able to show you the inline documentation of module classes and also debug the source code !

How to use binary modules

The list of available modules with their version numbers is needed to enable the plugin to get the right module.

A binary module can be declared:

• with an attribute binrelease.version.MODULENAME in plugin binrelease or binrelease.versions, its value is the module version number.
• with a binrelease:package definition and module and version attributes.

The plugin looks for these attributes in the binrelease plugin declaration itself or in the virtual binrelease.versions plugin declaration. This mechanism eases the release of the list of binary modules as a separated deliverable file, which will only contain binrelease.versions and will be included before "binrelease" plugin declaration.

Examples:

  <plugin name="binrelease">
    <attribute name="binrelease.version.mycoresystem" value="1.1"/>
  </plugin>
  <plugin name="binrelease.versions">
    <attribute name="binrelease.version.myextension" value="0.1"/>
  </plugin>

or equivalent with binrelease:package

  <plugin name="binrelease"
    xmlns:binrelease="antlib:ch.elca.el4ant.binrelease">
    <binrelease:package module="mycoresystem" version="1.1"/>
  </plugin>
  <plugin name="binrelease.versions"
    xmlns:binrelease="antlib:ch.elca.el4ant.binrelease">
    <binrelease:package module="myextension" version="0.1"/>
  </plugin>

With this declaration, at configuration, when a module declares a dependency to mycoresystem and mycoresystem which is not already declared in the project.xml as a normal source module, then the binrelease plugin will look for mycoresystem_1.1.zip in the lib/ directory (if not available, onlinelib may get it from a online repository if properly configured).

That zip file is deflated in dist/binrelease/leafcore_1.1/ and the module.xml is parsed and included in the project model.

The newly registered mycoresystem module is also specially configured to work correctly with other plugins:

• The attribute compile.nosources is set, so compile and jars targets will skip this module
• The execution unit attributes compile.jar are set to point to the dist/binrelease/leafcore_1.1/lib/ jar files.
• The attribute marker binrelease.binary is set.
• The target compile.clean.hook is removed from the hook targets clean.[module] for mycoresystem only, to avoid jar files to be deleted when clean is used.

The global build system behavior is also modified by the plugin:

• Shortcut generation for compile.module, compile.rec.module, jars.rec.module does not generate shortcuts for modules with the binrelease.binary marker.

Project structure example

This section proposes a project structure if you have to work on a project where some of its modules are delivered as binary and others are supposed to be sources only (for instance testcases).

The project declaration can be splitted into four files:

• plugins.xml contains declarations of all your plugins. binrelease is included.

• binary-modules.xml contains only the binrelease.versions virtual plugin. It is easy to deliver and easy to update for the user of the binary modules.

<?xml version="1.0"?>
<!-- EL4Ant Project definition -->
<ant:project name="binary-modules"
  xmlns="antlib:ch.elca.el4ant"
  xmlns:ant="antlib:org.apache.tools.ant">
  <plugin name="binrelease.versions"
    xmlns:binrelease="antlib:ch.elca.el4ant.binrelease">
    <binrelease:package module="mycoresystem" version="1.1"/>
    <binrelease:package module="myextension" version="0.1"/>
  </plugin>
</ant:project>

• source-modules.xml contains declarations of modules delivered as binary. They must have binrelease.version attribute set.

• project.xml is the entry point. It includes binary-modules first if you want to use binary releases, and then plugins.xml in any case. Then source-modules.xml is included if you do not use binary releases before the sources-only module declarations.

<?xml version="1.0"?>
<!-- EL4Ant project definition -->
<ant:project name="myproject"
  xmlns="antlib:ch.elca.el4ant"
  xmlns:ant="antlib:org.apache.tools.ant"
  xmlns:antcontrib="antlib:net.sf.antcontrib">

  <include file="plugins.xml"/>

  <antcontrib:if>
    <ant:isset property="usebinary"/>
    <antcontrib:then>
      <!-- Testing binary packages -->
      <include file="binary-modules.xml"/>
    </antcontrib:then>
    <antcontrib:else>
      <!-- Native module declarations -->
      <include file="source-modules.xml"/>
    </antcontrib:else>
  
  <!-- Source-only modules -->
  <module ...

</ant:project>

• online plugin can contain file://${basedir}/dist/binrelease/ in its onlinelib.repository attribute to automatically copy binary zip files to the lib directory.

When the project is configured without usebinary, native source modules are used. Run binrelease to generate the binary modules zip files.

When the project is configured with -Dusebinary=t on the command line, binary modules are found in dist/binrelease.

The following command sequence is an example of how to test binary modules:

ant -f bootstrap.xml distclean configure
ant binrelease clean
ant configure -Dusebinary=t
ant jars junit.start.all
ant binrelease.force.clean

Targets

• binrelease generates all releasable modules as binary modules.
• binrelease.module generates a releasable module as a zip file in binrelease.output.directory. Shortcuts are generated
• binrelease.force.clean removes registered binary modules in the project from the lib directory. It forces next configuration to get again zip files for binary modules.

Attributes

Global

• binrelease.output.directory is the path to the directory where zip files must be generated. May be absolute or relative to the project directory. Default value is dist/binrelease/.
• binrelease.default.excludes is the pattern used to exclude content of a source module without the binrelease.excludes attribute when packaging the binary module. Default value is java/**,classes/**.
• binrelease.sets.behavior controls how the binary modules are registered in sets. If equals to append, the binrelease.sets value is appended to original modules sets. If equals to exclude, binary modules are not registered in any module with noset flag. If equals to nochange, binary modules are registered in their original sets. Default behavior mode is exclude.
• binrelease.sets is the set attribute to append to binary modules if behavior is append.

Per module

• binrelease.version is the module version used to generate the zip file.
• binrelease.excludes is the exclude pattern used to build the zip file from the module path. Default value is java/**,classes/**.

Hooks

• pre.binrelease.[module] and post.binrelease.[module] are called before and after the zip generation only if the module is releasable.

The following properties are available for targets registered in these hook chains:

• binrelease.output.directory is the zip output directory.
• module.zip is the result zip file name.
• module.path is the module directory path.
• module.binexcludes is the module binrelease.excludes value or default if not set.
• module.version is the module binrelease.version attribute value used in the zip file name.
• module.jars is the list of module jar files to include in the zip lib/ directory.

ToDo

• Provide another target to package sources in a zip file with correct naming policy to make them available in Eclipse, associated with the jar files from a binary module.

J2EE Integration

J2EE

This plugin provides support for J2EE applications which run either in a servlet or in an EJB container. It allows creating packages of the specific format and delivers targets to control the different servers. The plugin has four distinct parts:

1. Support for WAR files
2. Web container support
3. Support for EAR files
4. EJB container support

The following presents each of them.

Remark: The multi environment support simplifies the usage of this plugin because it homogenizes among different web and EJB containers respectively. Using the environment support moves all attributes into property files and the plugins are declared using two special properties within the product-specific property file. See PluginEnvironment for details.

J2EE WAR

This plugin provides support to generate a J2EE WAR file (web archive with .war extension). The content of the WAR must be stored in the webapp/ directory of modules.

Declaration

  <plugin name="j2ee-war">
    <attribute name="j2ee-war.jar.excludes" value="servlet-api-*.jar"/>
  </plugin>

Dependencies

• runtime, automatically included if not explicitly declared.

Usage

If your module or module execution unit can be deployed as a WAR, the following attribute is needed to create the archive module-eu.war (or module.war if no execution unit)

    <attribute name="j2ee.war.application" value=""/>

If you want your WAR application name to be mywebapp, then you can set the j2ee.war.application attribute to that value. The archive mywebapp.war will be generated by the create.war target.

    <attribute name="j2ee.war.application" value="mywebapp"/>

The module dependency order is used to copy files with the same name in different webapp/ directories. If A depends on B, A/webapp/file.html replaces B/webapp/file.html in the WAR.

To speed up WAR generation, you can set the global attribute j2ee-war.unpacked to true. Instead of adding execution unit jar file in WEB-INF/lib (equivalent to the runtime classpath), it aggregates the classes/ directory content into WEB-INF/classes (equivalent to the development runtime classpath, not execution-unit aware). In that case, the whole module content (classes and resources) are available in the WAR file without considering execution unit filters.

Warning: the target create.war assumes your project compilation is up-to-date in case j2ee-war.unpacked is true, or else your project jars are up-to-date. From the command line, it is wiser to invoke ant compile create.war.module.eu.mymodule.myeu or ant jars create.war.module.eu.mymodule.myeu.

Targets

• create.war.module.eu generates the execution unit WAR for a module without compiling or building jars before. Shortcuts are generated.
• create.wars generates the WAR for all supported execution units. It calls create.war.module.eu.

Attributes

Global

• j2ee-war.unpacked may be set to true to aggregate module classes directory in WEB-INF/classes instead of using execution unit jars (included in WEB-INF/lib in that case). Default is false.
• j2ee-war.jar.excludes is a Ant exclusion filter to prevent some jar files to be included in WEB-INF/lib directory.

Per execution unit

• j2ee.war.application marks the module execution unit to enable WAR generation. If the attribute has empty string value, the name of the module execution unit is used as application name by default.
• j2ee-war.jar.excludes is the module execution unit specific filter, appended to the global attributes, when the WAR is generated for the concerned module.

Hooks

• pre.war.[module].[eu] and post.war.[module].[eu] called in create.war.module.eu

---

J2EE Web Tomcat support

This plugin directly extends j2ee-war with Tomcat support. It provides targets to start and stop Tomcat and to deploy or update a WAR as a Tomcat application. It has been tested with versions 4.1.30 and 5.0.27.

Dependencies

• runtime, automatically included if not explicitly declared.
• j2ee-war, automatically included if not explicitly declared.

Usage

  <plugin name="j2ee-web-tomcat">
    <attribute name="j2ee-web.container" value="tomcat"/>
    <attribute name="j2ee-web.home" value="../jakarta-tomcat-5.0.27"/>
    <attribute name="j2ee-web.host" value="localhost"/>
    <attribute name="j2ee-web.port" value="8080"/>
    <attribute name="j2ee-web.manager.username" value="admin"/>
    <attribute name="j2ee-web.manager.password" value="password"/>
    <attribute name="j2ee-web-tomcat.baseurl" value="http://localhost:8080"/>
  </plugin>

You have to specify where your Tomcat server is installed and the username/password of a user defined in conf/tomcat-users.xml with role manager to enable application reloading.

The module configuration must be done as described in the j2ee-war plugin documentation. In addition, the attribute runtime.command.creator is automatically added by the plugin for the concerned execution unit which enables to start tomcat during application deployment.

When you're developing your WAR content in module webapp/ directories (HTML, JSP, ...), you may want to speed up the WAR deployment with the unpacked flag (WEB-INF/classes) and the directory mode (the WAR is not packed) by adding the following two plugin attributes:

  <plugin name="j2ee-web-tomcat">
    <attribute name="j2ee-war.unpacked" value="true"/>
    <attribute name="j2ee-web.mode" value="directory"/>
    [...]

Targets

• deploy.war.module.eu deploys the execution unit WAR content in Tomcat webapps/ directory, starts Tomcat (without runtime hooks) if needed or else asks for application reloading. If the target has started Tomcat, it goes on running until Ctrl-C is hit. Shortcuts are generated
• runtime.command.creator.web is the runtime command creator used to start Tomcat.
• start.web starts Tomcat which goes on running until Ctrl-C is hit or until stop.web is executed.
• stop.web stops the running Tomcat instance.

Attributes

Global

• j2ee-web.home is the directory where the Tomcat server is installed. Mandatory, no default value.
• j2ee-web.host is the Tomcat server's host name or IP address. Mandatory, no default value.
• j2ee-web.port is the Tomcat server configuration port. Mandatory, no default value.
• j2ee-web.manager.username is the username of a user with manager role in Tomcat users. Mandatory, no default value.
• j2ee-web.manager.password is the password of the previously defined username. Mandatory, no default value.
• j2ee-web.mode may set to directory, war or war+directory. If the mode contains directory, the WAR content is copied in applications/appname/. If the mode contains war, the file applications/appname.war is packed. Default value is war.
• j2ee-war-tomcat.baseurl is the Tomcat server configuration URL. Optional, the default value is http://<j2ee-web.host>:<j2ee-web.port>

ToDo

• Be able to package the WAR WEB-INF/classes with exact execution-unit aware content

---

J2EE Web WebLogic Server support

This plugin directly extends j2ee-war with WebLogic Server support. It provides targets to start WLS and to deploy or update a WAR in WLS. It has been tested with WebLogic Server 8.1.

Dependencies

• runtime, automatically included if not explicitly declared.
• j2ee-war, automatically included if not explicitly declared.

Usage

  <plugin name="j2ee-web-weblogic" file="buildsystem/j2ee/war-weblogic.xml">
    <attribute name="j2ee-web.container" value="weblogic"/>
    <attribute name="j2ee-war.unpacked" value="true"/>
    <attribute name="j2ee-web.mode" value="war"/>
    <attribute name="j2ee-web.home" value="../external-tools/weblogic"/>
    <attribute name="j2ee-web.host" value="localhost"/>
    <attribute name="j2ee-web.port" value="7001"/>
    <attribute name="j2ee-web.manager.username" value="weblogic"/>
    <attribute name="j2ee-web.manager.password" value="password"/>
    <attribute name="j2ee-web-weblogic.beahome" value="../../bea"/>
    <attribute
      name="j2ee-web-weblogic.domain"
      value="../external-tools/domains/mydomain"/>
    <attribute name="j2ee-web-weblogic.server" value="myserver"/>
  </plugin>

The following configuration expects many things from the WLS installation:

• WebLogic server installation location in j2ee-web.home
• BEA home directory in j2ee-web-weblogic.beahome
• A domain to use (may be created with a wizard) in j2ee-web-weblogic.domain
• A server name available in the domain in j2ee-web-weblogic.server
• The server port, by default 7001 in j2ee-web.port
• The username and password for the domain administrator in j2ee-web.manager.username and j2ee-web.manager.password.

Moreover, the WebLogic domain must have been configured in development mode to enable automatic update of the application.

Targets

• deploy.war.module.eu deploys the execution unit WAR content in the WLS domain applications/ directory and starts the server if needed. If the target has started WLS, it goes on running until Ctrl-C. Shortcuts are generated
• runtime.command.creator.web is the runtime command creator used to start WebLogic Server.
• start.web starts WebLogic which goes on running until Ctrl-C or until stop.web is executed.
• stop.web stops the running WebLogic instance.

Attributes

Global

• j2ee-web.home is the directory where the Weblogic server is installed. Mandatory, no default value.
• j2ee-web-weblogic.beahome is the BEA home directory. Mandatory, no default value.
• j2ee-web-weblogic.domain is the WebLogic domain directory where the configuration can be found. Mandatory, no default value.
• j2ee-web-weblogic.server is the WebLogic server name configured in the previously defined domain. Mandatory, no default value.
• j2ee-web.host is the Weblogic server's host name or IP address. Mandatory, no default value.
• j2ee-web.port is the Weblogic server configuration port. Mandatory, no default value.
• j2ee-web.manager.username is the domain administrator username in Weblogic users. Mandatory, no default value.
• j2ee-web.manager.password is the password of the previously defined username. Mandatory, no default value.
• j2ee-web.mode may set to directory, war or war+directory. If the mode contains directory, the WAR content is copied in applications/appname/. If the mode contains war, the file applications/appname.war is packed. Default value is war.

ToDo

• Be able to package the WAR WEB-INF/classes with exact execution unit aware content

---

J2EE EAR

This plugin provides support to generate a J2EE EAR file (enterprise archive with .ear extension).

Declaration

  <plugin name="j2ee-ear">
    <attribute name="j2ee-ear.jar.excludes" value="j2ee-*.jar"/>
  </plugin>

Dependencies

• runtime, automatically included if not explicitly declared.

Usage

If your module or module execution unit can be deployed as an EAR, the following attribute is needed to create the archive module-eu.ear (or module.ear if no execution unit)

    <attribute name="j2ee.ear.application"/>

Warning: the target create.ear assumes your project compilation is up-to-date in case j2ee-ear.unpacked is true, or else your project jars are up-to-date. From the command line, it is wiser to invoke ant compile create.ear.module.eu.mymodule.myeu or ant jars create.ear.module.eu.mymodule.myeu.

Targets

• create.ear.module.eu generates the execution unit EAR for a module without compiling or building jars before. Shortcuts are generated.
• create.ears generates the EAR for all supported execution units. It calls create.ear.module.eu.

Attributes

Global

• j2ee-ear.jar.excludes is a Ant exclusion filter to prevent some jar files to be included.

Per execution unit

• j2ee.ear.application marks the module execution unit to enable EAR generation. If the attribute has no value, the name of the module execution unit is used as application name by default.
• j2ee-ear.jar.excludes is the module execution unit specific filter, appended to the global attributes, when the EAR is generated for the concerned module.
• j2ee.ear.dd points to the ear deployment descriptor file.

Hooks

• pre.ear.[module].[eu] and post.ear.[module].[eu] called in create.ear.module.eu

---

J2EE EJB JBoss support

This plugin directly extends j2ee-ear with JBoss support. It provides targets to start and stop JBoss and to deploy or update an EAR as a EJB application. It has been tested with version 4.0.2.

Dependencies

• runtime, automatically included if not explicitly declared.
• j2ee-ear, automatically included if not explicitly declared.

Usage

  <plugin name="j2ee-ejb-jboss">
    <attribute name="j2ee-ejb.container" value="jboss"/>
    <attribute name="j2ee-ejb.home" value="../external-tools/jboss"/>
    <attribute name="j2ee-ejb.host" value="localhost"/>
    <attribute name="j2ee-ejb.port" value="1099"/>
    <attribute name="j2ee-ejb-jboss.deploypath" value="../external-tools/jboss/server/default/deploy"/>
  </plugin>

You have to specify where your JBoss server is installed. The module configuration must be done as described in the j2ee-ear plugin documentation. In addition, the attribute runtime.command.creator is automatically added by the plugin for the concerned execution unit which enables to start JBoss during application deployment.

Targets

• deploy.ear.module.eu deploys the execution unit EAR content to JBoss. Shortcuts are generated
• runtime.command.creator.ejb is the runtime command creator used to start JBoss.
• start.ejb starts JBoss which goes on running until Ctrl-C is hit or until stop.ejb is executed.
• stop.ejb stops the running JBoss instance.

Attributes

Global

• j2ee-ejb.home is the directory where the WebLogic server is installed. Mandatory, no default value.
• j2ee-ejb.host is the JBoss server's name or IP address. Mandatory, no default value.
• j2ee-ejb.port is the WebLogic server configuration port. Mandatory, no default value.
• j2ee-ejb-jobss.deploypath is the path where EARs are copied to during deployment.

---

J2EE EJB WebLogic support

This plugin directly extends j2ee-ear with WebLogic support. It provides targets to start and stop WebLogic and to deploy or update an EAR as a EJB application. It has been tested with version 8.1.

Dependencies

• runtime, automatically included if not explicitly declared.
• j2ee-ear, automatically included if not explicitly declared.

Usage

  <plugin name="j2ee-ejb-weblogic">
    <attribute name="j2ee-ejb.container" value="weblogic"/>
    <attribute name="j2ee-ejb.home" value="../external-tools/weblogic"/>
    <attribute name="j2ee-ejb.host" value="localhost"/>
    <attribute name="j2ee-ejb.port" value="7001"/>
    <attribute name="j2ee-ejb.manager.username" value="weblogic"/>
    <attribute name="j2ee-ejb.manager.password" value="password"/>
    <attribute name="j2ee-ejb-weblogic.beahome" value="../../bea"/>
    <attribute
      name="j2ee-ejb-weblogic.domain"
      value="../external-tools/domains/mydomain"/>
    <attribute name="j2ee-ejb-weblogic.server" value="myserver"/>
  </plugin>

You have to specify where your WebLogic server is installed. The module configuration must be done as described in the j2ee-ear plugin documentation. In addition, the attribute runtime.command.creator is automatically added for the concerned execution unit to be able to start WebLogic when deploying.

Targets

• deploy.ear.module.eu deploys the execution unit EAR content to WebLogic. Shortcuts are generated
• runtime.command.creator.ejb is the runtime command creator used to start WebLogic.
• start.ejb starts WebLogic which goes on running until Ctrl-C is hit or until stop.ejb is executed.
• stop.ejb stops the running WebLogic instance.

Attributes

Global

• j2ee-ejb.home is the directory where the Weblogic server is installed. Mandatory, no default value.
• j2ee-ejb-weblogic.beahome is the BEA home directory. Mandatory, no default value.
• j2ee-ejb-weblogic.domain is the WebLogic domain directory where the configuration can be found. Mandatory, no default value.
• j2ee-ejb-weblogic.server is the WebLogic server name configured in the previously defined domain. Mandatory, no default value.
• j2ee-ejb.host is the Weblogic server's host name or IP address. Mandatory, no default value.
• j2ee-ejb.port is the Weblogic server configuration port. Mandatory, no default value.
• j2ee-ejb.manager.username is the domain administrator username in Weblogic users. Mandatory, no default value.
• j2ee-ejb.manager.password is the password of the previously defined username. Mandatory, no default value.

ToDo

Move from custom Ant scripts to Cargo, which unifies the control (start, stop, deploy) of different J2EE containers. There's currently no support for JBoss (work in progress and planned for next release, 0.7).

IDE Integration

Eclipse

This plugin provides integration of the build system features in Eclipse.

Dependencies

• compile and runtime are mandatory
• Supports for commons-attributes and config-conffolder are implemented

Declaration

Here is an example of how to use the eclipse plugin:

  <plugin name="eclipse">
    <attribute name="eclipse.workspace.path" value="workspace"/>
    <!-- External tools prefix -->
    <attribute name="eclipse.prefix" value="MyProject_"/>
    <!-- Eclipse targets -->
    <attribute name="eclipse.tools" value="eclipse.generate"/>
    <!-- compile targets -->
    <attribute name="eclipse.tools" value="clean.module,jars"/>
    <!-- junit targets -->
    <attribute name="eclipse.tools" value="junit.startdev.all"/>
    <!-- reports targets -->
    <attribute name="eclipse.tools" value="javadoc,checkstyle"/>
    <!-- j2ee-war and j2ee-war-tomcat targets -->
    <attribute name="eclipse.tools" value="create.war.module.eu,deploy.war.module.eu"/>
    <!-- binrelease targets -->
    <attribute name="eclipse.tools" value="binrelease.module"/>
  </plugin>

If you do not use some plugins, the corresponding targets should be removed from eclipse.tools attributes. You can also limit the list to mostly used targets.

Usage

First of all, it is necessary to use the build system Ant version. In Eclipse, open Window-> Preferences, Ant->Runtime->Classpath and set Ant Home to your current Ant directory (1.6.5 or later).

At project configuration, the plugin generates .project and .classpath files for each module, the corresponding Eclipse projects must be imported into Eclipse if they have not been imported yet or refreshed if they are already in Eclipse.

To ease the importation of multiple projects into Eclipse, the "Multi Project Import/Export" Eclipse plugin can be used. This plugin can be found on the web.

Some targets cannot be included in Eclipse at configuration, to work-around this limitation, you have to invoke eclipse.generate to create runtime shortcuts. In case of a change in shortcuts, the workspace must be refreshed to include new external tools. This can be done for example by restarting Eclipse (or the workspace).

Ant targets are inserted in external tools:

• as a normal target if it does not apply to a module,
• or as a shortcut with module and execution unit names,
• or as a generic target (like clean.module for instance) that applies to the current module (selected project in Eclipse).

With BinRelease plugin

The global binrelease.default.excludes attribute should be set to java/**,.classpath,.project,.externalToolBuilders/**.

If you are interested in keeping java sources for documentation and debug in Eclipse, you can set it to .classpath,.project,.externalToolBuilders/**.

With Checkstyle plugin

The checkclipse plugin enables Checkstyle warnings in your Eclipse workbench.

• Download the plugin from http://www.mvmsoft.de/content/plugins/checkclipse/checkclipse.htm
• Unzip the file where your Eclipse is installed in folder plugins. After unzipping it you should have a folder de.mvmsoft.checkclipse_x.y.z in the plugins folder.
• Restart Eclipse.
• Open Window/Preferences. You should see now a entry Checkclipse on the left. Click on it.

• Set the checkboxes like in picture above.
• Set the field Checkstyle Configuration File with the path of the file checkstyle_el4ant_checks.xml which can be found in folder etc of your EL4Ant project.
• Inside this Checkstyle Configuration File properties can be defined. To resolve these properties you have to copy the properties file checkstyle_el4ant.properties which can also be found in folder etc into another directory as the EL4Ant project is. We recommend to create a folder el4ant into directory from eclipse and copy this file into. This copy is necessary, because you have to adapt the property file to your local folder structure, because otherwise the Checkclipse plugin could not find the el4ant_java_header_file. Open the copied properties file in an editor and change the property el4ant_java_header_file to your local folder structure, i.e. el4ant_java_header_file=D:/Projects/EL4Ant/etc/el4ant_java_header. Be aware that you use / and NOT \ for the path. FYI: The file el4ant_java_header which is needed here is situated in the same directory as the checkstyle_el4ant_checks.xml (folder etc).
• Close window Preferences by pushing button Ok. Now the workspace should be rebuilt and checkstyle checks should be made.

Note: To have warnings displayed in view Problems you have to adapt the filter of this view. Just push the filter button (upper right of the view) and check entry de.mvmsoft.checkclipse.CheckclipseMarker.

Features

• At configure-time, it creates the .project and .classpath files for each module that is declared and whose directory exists on disk. This way, one Eclipse project is created per module.
• At configure-time, it registers external tools in Eclipse to call build system targets directly from within Eclipse.
• At configure-time, a builder is automatically installed for modules that uses Commons Attributes (see commons-attributes plugin), to call the Ant target commons-attributes.module. This way, commons attributes are automatically generated and compiled when Eclipse builds the project.
• The generated .classpath file only refers to existing java/ and conf/ (see config-conffolder plugin) on disk when configuring or else Eclipse build fails.
• The target eclipse.generate registers Eclipse configurations to run and debug runnable module execution units. It is then possible to run and debug applications in Eclipse with the same environment (classpath, system properties,...) as if it was run from the command line.
• To ease development, inline documentation and debugging are improved thanks to the automatic registration of sources associated to classes. If a jar file myjar-1.3.jar is declared as dependency, the plugin expects the sources of the classes to be in the file lib/src/myjar-1.3-src.zip (and download it from online repositories if configured)

Targets

• eclipse.generate generates the Eclipse run/debug configurations for all the runnable module execution units.
• eclipse.generate.module generates the Eclipse run/debug configurations for all the runnable execution units of a specific module.
• eclipse.generate.module.eu generates the Eclipse run/debug configurations for a specific runnable module execution unit.

Attributes

Global

• eclipse.workspace.path is the path to the Eclipse workspace directory. If this attribute is not defined, the Eclipse plugin won't be able to automatically register Eclipse external tools and to define runnable/debuggable applications in Eclipse. Mandatory, no default value.
• eclipse.prefix is the prefix used to register runtime targets and external tools. Default is EL4Ant.
• eclipse.tools is a comma-separated list of Ant targets to publish in Eclipse as external tools. They must be available in your generated build.xml

Per module

• eclipse.project.type is the type of the Eclipse project to create for this module; this attribute is optional and accepts the following values:
  • java is used for a Java project (default value)
  • pde is used for a plugin development project for the eclipse rich client platform

Known bugs

• If you have removed some targets from the eclipse.tools attributes or change the eclipse.prefix value, you have to clean old entries manually from Run->External Tools->External Tools... and Run->Run... with the delete button.
• Runtime targets for JUnit modules (with the JUnit command creator) does not work. You have to use junit.startdev.all to generate reports but the JUnit progress bar is not shown in Eclipse.
• Running JUnit test cases with the Eclipse menu (all tests from a project or a single test case) does not consider command line modifications applied by declared runtime hooks.

After a new project configuration with commons attributes enabled, Eclipse build fails with this kind of message:

Errors during build.
  Errors running builder "Integrated External Tool Builder" on project aModule.
  Resource is out of sync with the file system: /aModule/.externalToolBuilders/el4ant_Commons Attributes Builder.launch.

The fastest way to work-around this issue is to refresh all projects (select all projects, right-click, Refresh) and then build again.

• When configuring CheckStyle, if the removal of the Sun Checks fails, you have to refresh all Eclipse projects first.

ToDo

• Integrate cleanly JUnit targets to include runtime hooks and also enable debugging.
• The commons attributes generation process could be faster by creating an Eclipse plugin that does the job directly without calling an Ant task.
• Improve access to project.xml and other files from the project base directory in Eclipse. Currently, the menu File->Open External File... must be used.