Working with Modules

Tutorial Objective

The objective of this tutorial is to introduce the concept of a module and the usage of modules in managing namespaces for produced artifacts. In general terms a module can be viewed as a named group. Modules can contain projects, resources and other modules. As such - modules enable the creation of a namespace heirachy that maps directly to the notion of a group in the artifact protocol. For example - the uri artifact:part:dpml/metro/dpml-metro-runtime#1.0.0 is referencing a resource named dpml-metro-runtime in the dpml/metro module.

index.xml

The following index file introduces an enclosing module to our earlier multi-project build example. In this case we are using the module declaration to partition the two projects in the namespace org/acme.

<?xml version="1.0" encoding="ISO-8859-1"?>
<index xmlns="dpml:library">

  <imports>
    <import uri="link:module:org/apache/ant"/>
    <import uri="link:module:dpml"/>
  </imports>

  <module name="org/acme" basedir=".">
  
    <project name="clock-api" basedir="api">
      <types>
        <type id="jar"/>
      </types>
    </project>
  
    <project name="clock-impl" basedir="impl">
      <types>
        <type id="jar"/>
      </types>
      <dependencies>
        <runtime>
          <include key="clock-api"/>
        </runtime>
        <test>
          <include ref="org/apache/ant/ant-junit"/>
          <include ref="dpml/transit/dpml-transit-main"/>
        </test>
      </dependencies>
    </project>

  </module>
  
</index>

Listing the Module

The following command lists the projects relative to the module tutorial source project. The output validates that the resources names used within Depot now include the org/acme namespace.

$ cd tutorials\tooling\complex\modules
$ build -list

Selection: [3]

  [1]   project:org/acme/clock-api#SNAPSHOT
  [2]   project:org/acme/clock-impl#SNAPSHOT
  [3]   module:org/acme/#SNAPSHOT

$

Something important to note is that the above listing includes our two projects clock-api and clock-impl together with the enclosing module. In effect a module that declares a basedir is considered as a buildable project. Sometimes it is convinient to handle application level packaging and installer creation concerns at the level of a module build, but more interesting is the potential for exporting a module definition for use by third-parties. Our next tutorial presents an example of the creation of a module artifact suitable for use by third-party projects that want to reference our content.