Using

Using Antmod

In the following paragraphs, the examples assume there is a release descriptor called "mytool-dev" with two modules: "gui" and "util".
If required, replace this with the release descriptor you are interested in and you can be up and running very quickly.

Release descriptors

The ${antmod.checkoutdir}/antmod-releases/ directory contains the release descriptors. Each release descriptor defines which modules are part of a specific release.

Before you can start using Antmod, make sure the relevant release descriptor exists, or create a new one.

Retrieving a release

With Antmod, work is always oriented at a specific release (= collection of modules). In order to work on the development version of the "mytool" release, make sure to have it checked out using: 

    antmod checkout mytool-dev

This will retrieve the relevant sources from CVS or Subversion. After it is done, this will result in the following directory structure: 

    ${antmod.checkoutdir}         Checkout directory, configurable in "${HOME}/.antmodrc".
    |
    +-mytool-dev
      |
      +-gui
      |
      +-util

Working on a release

You can now build the release: 

    cd ${antmod.checkoutdir}/mytool-dev
    ant build

This will iterate over all the modules, and build them in the order as they are listed in the release descriptor.

Instead of doing a "build" you can also invoke one of the other module-level build targets.

Making code changes in a release

You can change the sources in the various modules, and then commit you changes on a module-by-module basis to CVS or Subversion. While committing be aware of the following:

  • Are you committing to the trunk, or
  • Are you committing to a branch, in which case your change still has to be merged back to the trunk

Committing to a branch will only happen in non "-dev" releases, and is the case if the module version is specified as a 2-digit version number in the release descriptor (within the tag).

If the module version is specified as a 3-digit version number in the release descriptor, that module cannot be changed within the release. First you need to refer to the 2-digit version number, make changes in that branch, and then create a new 3-digit version number. This is complex, if you need help check out the mailing lists.

Creating a release package

When a release description needs to be released to a test environment, QA or customer, it first needs to be packaged. In order to do this, you can do the following: 

    cd ${antmod.checkoutdir}/mytool-dev
    ant dist

This creates the distribution sources in the following directory: 

    cd ${antmod.checkoutdir}/mytool-dev/build/dist

This is the result of invoking the "distrelease" Ant target on the 'main' module (or the 'buildrelease' module if any) of the release. If the 'local.build.xml' of the 'buildrelease'/'main' module does not override this target, it will by default do the following:

  • Put the non-test jars in the release-level "build/dist/lib/" directory
  • Put any additional 3rd party jars from the modules's lib directory in the release-level "build/dist/lib/" directory as well
  • Put the contents of all module's build/dist directories in the release-level "build/dist/" directory as-is

Next create a distributable package using: 

    cd ${antmod.checkoutdir}/mytool-dev
    ant package

This creates a "tar.gz" by default, or something else if the 'buildrelease'/'main' module overrides "packagerelease" in its 'local.build.xml'. The results can be found in: 

    cd ${antmod.checkoutdir}/mytool-dev/build/package

Note that it is very well possible that the 'buildrelease'/'main' module creates multiple packages at once from the distribution sources. For example a windows installer and a Linux RPM.