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.
Download the latest HelloWorld package ant+el4ant+helloworld at SourceForge.net and follow the GettingStarted instructions.
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.
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.
The compile
, runtime
, onlinelib
and show
plugins are described in the
user's guide.
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
binrelease
: binary module support
resources
: add support for resources directory per module
commons-attributes
: parses and generates attributes with the eponym Jakarta Apache tool
The EL4Ant build system is based on Ant and some basic concepts to ease the description and modularization of a project to build.
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.
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.
execute
.
What you should know about Ant before using it:
build.xml
build file by default. You can load another
file name with the -f
option.
ant -projecthelp
.
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.
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.
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.
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 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.
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:
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.
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.
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.
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)"]>
include
statement is analyzed, its content is registered
immediately, so it has an impact on the registration order.
Project description examples are described later.
Attribute elements are used to configure the plugin behavior and Ant targets. The attribute scope depends on where it is set:
plugin
element,
module
element,
eu
element.
Please refer to each plugin documentation to know available attribute names, expected values and scope(s).
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.
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.
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).
eu
scope is not set,
inheritEuList=true
is used, the target module execution unit list
is declared in the current module.
mapping
is used).
eu
scope is set,
eu
depends on the
single module jar.
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.
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.
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.
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
.
dependency
eu
scope is set,
mapping target="targeteu"
makes a dependency of the current module
eu
to the target module targeteu
.
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,
[module]
hook
[module].[eu]
hook
If the hook element is used to register a target in a chain at the module level,
[module]
hook
[module].[eu]
hook
If the hook element is used to register a target in a chain at the execution unit level,
[module]
hook
[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.
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.
Consider this short project description:
mytool
without execution unit. The jar mytool.jar
will be
generated with the whole module content.
myservice
interface
: The jar myservice-interface.jar
contains
common classes and the service interface.
implementation
: The jar myservice-implementation.jar
contains common classes and the service interface and
implementation. Only this eu depends on the mytool
module.
myapp
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
.
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
.
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>
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.
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.
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.
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
.
For each plugin, the documentation explains:
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.
This plugin compiles Java sources from each module's java/
directory to the
corresponding classes/
directory.
<plugin name="compile"/>
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.
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.
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.
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.
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.
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.
This plugin provides execution targets to run a java command corresponding to a module execution unit.
<plugin name="runtime"/>
compile
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.
runtime.default.command.creator
must be a valid
java command creator. Default value is
runtime.command.creator.basic
.
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.
runtime.command.creator.basic
, runtime.class
must be
set to a class name with public static void main(String[])
method.
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.
runtime.command.creator.basic
, runtime.class
must be set to
a class name with public static void main(String[])
method.
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.
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:
runtime.arguments
attribute set in the module execution unit
-Druntime.arguments="arg1 arg2 arg3"
set in the Ant command line
-Druntime.append.arguments="arg4 arg5"
can be used to
append arguments to the current list (from runtime.arguments
property)
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.
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.
<plugin name="show"/>
This plugin downloads lacking jar files from a list of repositories according to its file name.
<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>
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
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.
This plugin provides javadoc generation targets.
<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>
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.
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.
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>
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
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:
java/
directories (such as binary modules)
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.
It is most likely the concerned classes are in modules in dependence but are not compiled. First run compile target and try again.
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.
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.
docs
directories
doc-file
directories
This plugin uses the eponym SourceForge project to analyze Java source files or any other text files: HTML, XML, properties, ...
<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.
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.
checkstyle
generates reports for all module sets (checkstyle.set.list
).
checkstyle.set
generates the report for a specific set.
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.
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.
IllegalArgumentException: can't parse argument number '' et ''
with a language setting in Ant script ANT_OPTS="-Duser.language=en"
This plugin provides a java command creator to execute JUnit test cases in a module and a target to generate a global report.
<plugin name="junit"> <attribute name="junit.jar" value="junit-3.8.1.jar"/> </plugin>
runtime
and compile
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.
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.
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.
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.
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.
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.
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
.
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
.
pre.junit.report
and post.junit.report
are called before and after the set
report generation.
This plugin uses the eponym SourceForge project to provide Java code coverage.
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>
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.
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.
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
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.
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.
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.
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=
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.
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.
emma.mode
is the module code coverage mode. If set to offline
and
global mode is not offline
, then the module classes are instrumented.
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.
dist/runtime
when running a
command in on-the-fly mode.
This plugin provides a single entry point to generated a project website including reports.
<plugin name="website"> <attribute name="website.resources" value="etc/website/resources"/> <attribute name="website.templates" value="etc/website/templates"/> </plugin>
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.
website
generates the site pages and menu.
website.clean
cleans the complete site, pages and reports.
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
.
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/
).
<plugin name="resources"> <attribute name="resources.directories" value="conf"/> </plugin>
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.
resources.copy.module
copies the resources files for a given
module. This target is automatically invoked after the target compile
(hook post.compile.[module]
).
resources.directories
is the list (comma separated) of optional
directories to consider as resources in a module.
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.
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!
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]
).
commons-attributes.enable
marks, when set to "true", that the module
uses commons attributes.
This plugin provides two mechanisms: support to use binary module releases and the generation of binary module releases from source modules.
<plugin name="binrelease"/>
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.
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 !
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:
binrelease.version.MODULENAME
in plugin binrelease
or binrelease.versions
, its value is the module version number.
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:
compile.nosources
is set, so compile
and jars
targets will skip this module
compile.jar
are set
to point to the dist/binrelease/leafcore_1.1/lib/
jar files.
binrelease.binary
is set.
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:
compile.module
, compile.rec.module
,
jars.rec.module
does not generate shortcuts for modules with the
binrelease.binary
marker.
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
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.
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
.
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/**
.
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.
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:
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.
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.
<plugin name="j2ee-war"> <attribute name="j2ee-war.jar.excludes" value="servlet-api-*.jar"/> </plugin>
runtime
, automatically included if not explicitly declared.
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
.
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
.
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.
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.
pre.war.[module].[eu]
and post.war.[module].[eu]
called in
create.war.module.eu
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.
runtime
, automatically included if not explicitly declared.
j2ee-war
, automatically included if not explicitly declared.
<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"/> [...]
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.
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>
WEB-INF/classes
with exact execution-unit aware content
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.
runtime
, automatically included if not explicitly declared.
j2ee-war
, automatically included if not explicitly declared.
<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:
j2ee-web.home
j2ee-web-weblogic.beahome
j2ee-web-weblogic.domain
j2ee-web-weblogic.server
7001
in j2ee-web.port
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.
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.
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
.
WEB-INF/classes
with exact execution unit
aware content
This plugin provides support to generate a J2EE EAR file (enterprise archive with .ear extension).
<plugin name="j2ee-ear"> <attribute name="j2ee-ear.jar.excludes" value="j2ee-*.jar"/> </plugin>
runtime
, automatically included if not explicitly declared.
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
.
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
.
j2ee-ear.jar.excludes
is a Ant exclusion filter to prevent some jar
files to be included.
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.
pre.ear.[module].[eu]
and post.ear.[module].[eu]
called in
create.ear.module.eu
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.
runtime
, automatically included if not explicitly declared.
j2ee-ear
, automatically included if not explicitly declared.
<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.
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.
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.
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.
runtime
, automatically included if not explicitly declared.
j2ee-ear
, automatically included if not explicitly declared.
<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.
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.
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.
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).
This plugin provides integration of the build system features in Eclipse.
compile
and runtime
are mandatory
commons-attributes
and config-conffolder
are implemented
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.
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:
clean.module
for instance) that applies to
the current module (selected project in Eclipse).
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/**
.
The checkclipse plugin enables Checkstyle warnings in your Eclipse workbench.
plugins
. After
unzipping it you should have a folder de.mvmsoft.checkclipse_x.y.z
in
the plugins
folder.
Window/Preferences
. You should see now a entry Checkclipse
on the
left. Click on it.
checkstyle_el4ant_checks.xml
which can be found in folder etc
of your
EL4Ant project.
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
).
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
.
.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.
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.
.classpath
file only refers to existing java/
and
conf/
(see config-conffolder
plugin) on disk when configuring or else
Eclipse build fails.
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.
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)
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.
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
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
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.
junit.startdev.all
to generate reports but the
JUnit progress bar is not shown in Eclipse.
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.
CheckStyle
, if the removal of the Sun Checks
fails,
you have to refresh all Eclipse projects first.
project.xml
and other files from the project base
directory in Eclipse. Currently, the menu File->Open External
File... must be used.