Modules

Concept

Modules are the grouping mechanism of files and source code into a logical versioning unit. Files or source code are never versioned individually, instead modules are versioned as a whole, providing a consistent versioning unit across components and projects.

So when should a separate module be introduced? This is simple: whenever reuse of the contents is necessary. So if an Ant buildfile, a software component, configuration data, documentation, etc. needs to be reused, put it apart in a logically named module and use that module across release descriptors.

A possible reuse scheme could look like this:

                 +------ somerelease/dev.xml
                 |
util 1.7  <------+
                 |
                 +------ releasetwo/2.1.xml

In this example, both "somerelease-dev" and "releasetwo-2.1" use the same "util" module, version 1.7.

Read more on versioning of modules in the Version Concepts.

Module Types

Different types of modules exist within a release. The following module types can be specified:

• library
  The default module type. Modules with type library are included in the release for their source code, so "ant build" is invoked on these modules when an "ant dist" is issued on release level.
• dist
  The same as type library, with the addition that "ant dist" is invoked on these modules when "ant dist" is issued on release level. Effectively this means that the release wants to include the module's distribution results in its release as well. By default this includes all files in the resources/dist directory of the module.
• buildrelease
  The module with type buildrelease (by default this is the main module, unless another module is assigned the type buildrelease) is the module that defines how the release as a whole gets constructed and packaged,
  When "ant dist" or "ant package" is issued on release level, Antmod will invoke "ant distrelease" or "ant packagerelease" in the buildrelease module. This module's "local.build.xml" can override these Ant targets, and thus customize this for the release.
• main
  Every release has one module with type main. This means it is the most important module in the release, usually containing required configuration and other files for various build plugins, and if there is no buildrelease module it's Ant buildfile is used for building the release as well.

Local build files

This only applies to release descriptors with "buildtype" set to java. In that case every module gets a "build.xml" Ant file that is used to build that module.

The module's Ant buildfile has various "build targets". The "build.xml" build files are read-only and default, and will never be changed; Antmod copies these files to each module, so changes in it will be lost. The advantage is that this enforces the same buildfile structure for all projects and modules.

In order to facilitate the many times that specific build functionality is required, each module can override the default behavior of each Ant target, by storing "local.build.xml" Ant buildfile in the root of the module; right next to the copied "build.xml".

Any build target of the module can be overridden by introducing an Ant target in "local.build.xml" with the following name:

• <target name="buildtarget">
  Overrides the default behavior of the module's buildtarget.

• <target name="buildtarget-pre>
  Before the buildtarget executes, this target is invoked. Allows the module to prepend some build actions before buildtarget executes.

• <target name="buildtarget-post">
  After the buildtarget has completed executing, this target is invoked. Allows the module to append some build actions after buildtarget has executed.

As mentioned earlier, the buildrelease module in a release is used for "ant dist" and "ant package" of the release. This means that the "local.build.xml" of that module can use the above naming scheme for overriding the default release build behavior. More precisely, the following Ant targets can be created for influencing the release build: distrelease-pre, distrelease, distrelease-post, packagerelease-pre, packagerelease, and packagerelease-post.