The Craftsman Bundle (<bundle>)

The Craftsman Bundle is concept for packaging modules. Modules create build artifacts, but they are often not very useful without their dependents or their libraries. Packaging projects for distribution becomes problematic especially when you may want to distribute the project in two different piecesm each containing a specific subset of the project's modules.

Declaring a <bundle>

Declaring a bundle is actually very simple: just enclose any of the modules you want in a bundle with a <bundle> tag. A bundle would look something like this in your build.xml file:

    <!-- define the modules for this package -->
    <craftsmandef>
        <bundle bundleid="foobar">
	        <module moduleid="foobar">
	            ...
	        </module>
	        <module moduleid="foobar-ejb">
	            ...
	        </module>
	        <module moduleid="foobar-web">
	            ...
	        </module>
	        <module moduleid="foobar-app">
	            <capability name="j2ee-ejb">
	                <option name="app-name" value="foobar"/>
	            </capability>
	            <dependency moduleid="foobar"/>
	            <dependency moduleid="foobar-ejb"/>
	            <dependency moduleid="foobar-web"/>
	            ...
	        </module>
        </bundle>
    </craftsmandef>

This will create a bundle including the modules foobar, foobar-ejb, foobar-web, and foobar-app. The final bundle will contain the build artifacts of these modules.

The bundles.xml support file

Bundles are where you attach "version" or "release" information. While a module may contain its release information internally via the module-MODULEID.xml file, it is not reflected in the build artifact name. That is, foobar v1.1.1 creates a foobar.jar, not a foobar-1.1.1.jar. You attach the version number to the bundle instead (e.g. foobar-1.1.1.zip).

Information like this, along with where to download/retrieve the library distribution are contained in the bundles.xml file. You can place this file in your module directory, the module directory's parent (e.g. "../"), or the parent lib directory (e.g. "../lib). Generally, the file looks something like this:

<bundles>
    <bundle id="rsh-commons" download-url="http://craftsman.redstarhackers.com/libcache">
        <version>1.0.0</version>
    </bundle>
    <bundle id="rsh-test" download-url="http://craftsman.redstarhackers.com/libcache">
        <version>1.0.0</version>
    </bundle>
</bundles>

This specifies that the rsh-commons bundle is version 1.0.0 and that the library-rsh-commons.xml file created by the bundle process should use "http://craftsman.redstarhackers.com/libcache" for the download location for the library archive (where the library archive is the bundle itself).

<bundle> options

Bundles are configured via their capability options. This is to allow for flexibility and the addition of more options at a later date. You can find the full reference for the options at Craftsman Bundle Capabilities.

The options you are most likely interested in are the "include-libraries" and "exclude-library" option. Using these two options together (or just the "include-libraries" alone), you can build bundles that contain all the libraries needed for your module(s) to work. This is handy, as the bundle functionality automatically generates a <library> configuration file for use in Craftsman builds. You could build and distribute a bundle and then use it in another module by just putting the library.xml file in the right place.

Building your <bundle>

Once you have your bundle defined in the build.xml and the bundles.xml files, just call ant bundle. This will reuse any build artifacts in creating the bundle. To get a clean bundle (one built from the latest), use ant clean build bundle.

If your bundle is foobar, you will get a "foobar.zip" and a "library-foobar.xml" file in your current directory.