HomeDownloadsUser GuideDevelopment

Development: Module

Module

This document describes how to add a new module to the build system.

Naming

Project module names should be names that are valid file names on all development platforms. Therefore please stick to the following pattern: [A-Za-z-], use - instead of spaces or underscores.

Module names must be unique in the whole build system regardless of their location. For example it is not possible to both have a module foo/test and bar/test since the build system could not distinguish between the two. Rather name them foo-test and bar-test.

Location

Basically a module can be stored whereever you like. However modules should be grouped by type, e.g. all example modules should be stored in the examples directory. Please take a look at the overall build structure and choose a suitable location.

The path of a module is not part of its identification. See the section about naming above for more information.

Directory Structure

The directory structure of each module is as follows:

module.xml
The module ant build file.
src
Folder that contains all source files.
Folder for documentation source files.
main
Main module source folder.
Contains the actual java sources including package folder hierarchy.
Contains the resources (images, property files, etc.) used.
test
module source folder for unit tests.
The unit test sources (same package hierarchy as main java sources).
Resources used by the unit tests.
lib
Module specific 3rd party libraries.
tools.xml
Description file for all libraries.
Each library has its own toplevel folder, all files are contained therein.
lib-b
Another library folder.
tool.xml
Each library must have a tool description file.
tool
Library specific files (jars, resources, etc.) should go into the tool folder.
lib-b.jar
Example archive of lib-b.
Yet another library.
You can have as many libraries as you want.

Build System

In order to support a newly created module the build system has to be adjusted in several locations. This might be enhanced in a future release but for the moment new modules have to be integrated manually.

Module Build File

The module build file can provide hooks to be called by the main build scripts to provide extra functionality to tasks like compile/distribution/etc. or it can completely replace them.

It would be out of scope to describe all you can do in a module build file, instead please have a look at the existing module build files and check what you can do.

There is only one single mandatory entry for each build file which is called <module-name>.path. This has to be a property which contains the location of the module folder relative to the root directory. (Do not use the location attribute, instead use the value attribute and use the slash / as directory separator.)

The targets in your module build file have to be prefixed with the name of the module followed by a dot. Example: If your module is called foo then all properties and tasks must be prefixed with foo. like e.g. foo.path.

Main Build File

The main build file build.xml has to be adjusted to include the newly created module:

  1. Include your build file:
    Best check out the top level build file and search e.g. for editor/module.xml to see how the editor module build file is included and do the same with your module.
  2. Adjust the module lists
    The modules used during the build are stored in a property called project.all.modules in the main build. Best search for this property in the main build file and include the name of your build file there.

The targets in your module build file have to be prefixed with the name of the module followed by a dot. Example: If your module is called foo then all properties and tasks must be prefixed with foo. like e.g. foo.path.

Versioning

Note:

As of release 0.3.0 modules are no longer versioned individually by default.

Only create a version section as defined below if you really want to use your own version number for a module.

The path of a module is not part of its identification. See the section about naming above for more information.

All modules in the build system are versioned. To enable a module for versioning a new versioning section has to be added to the corresponding build files:

  1. Edit the documentation build file shared/build/doc.xml.
  2. Navigate to the build target doc.change.
  3. Copy an existing module section and adjust it according to your new module.

Here is what a sample section might look like for a module called mynewmodule (note that the path ${mynewmodule.path} has to be defined in the module build file):

<section
  name="examples-ejb" 
  type="version"
  module="mynewmodule"
  prefix="Version"
  buildfile="${project.dir}/${mynewmodule.path}/${project.module.version.file}"
/>

Once the module section information has been inserted the module versioning information itself is created using the standard build version command.