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.