<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>

  <header>    
    <title>GOM : Module</title>
  <authors><person name="Sam Ruby" email="rubys@us.ibm.com"/></authors></header>

<body>

  <section><title>module</title>
    <p>A module is a collection of projects that are physically stored in a 
    single repository.</p>

    <table>
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required?</th>
      </tr>
      <tr>
        <td>name</td>
        <td>The name of the module.</td>
        <td>Yes</td>
      </tr>
      <tr>
        <td>tag</td>
        <td>Override the <link href="#cvs">cvs</link> tag to be used.</td>
        <td>No</td>
      </tr>
      <tr>
        <td>debug</td>
        <td>Set to "true" to turn on module debugging.</td>
        <td>No</td>
      </tr>
      <tr>
        <td>groupId</td>
        <td>mvn groupId for artifacts built by the projects contained
        in this module.</td>
        <td>No, defaults to the module's name</td>
      </tr>
    </table>

    <section><title>url</title>
      <p>This is the homepage for the collection of projects contained in
      this module.  This element is optional, but if present, will be
      referenced in the generated web pages containing build results.</p>

      <p>Note: give the way that Apache Gump uses href to specify definitions which
      are to be inlined, the design of this element is rather unfortunate.
      Perhaps it should be replaced with a &lt;home-page&gt; element.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>href</td>
          <td>URL of home page</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>srcdir</td>
          <td>The directory (relative to the workspace's basedir) which
          the checked out sources are to be copied for build purposes.</td>
          <td>No.  Defaults to the name of the module.</td>
        </tr>
      </table>
    </section>

    <section><title>description</title>
      <p>If present, will contain information added to the title in web
      pages containing build results.</p>
    </section>

    <section><title>cvs</title>
      <p>References the <link href="repository.html">repository</link> in which
      this project resides.  May also contain various overrides.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>repository</td>
          <td>The name of the repository in which this module resides.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>host-prefix</td>
          <td>Additional information which will be added in the front of the
          host name.  Useful for repositories like sorceforge which define
          a separate virtual host for every project</td>
          <td>No</td>
        </tr>
        <tr>
          <td>dir</td>
          <td>The subdirectory in which the cvs module is present.  Useful
          for repositories like developerworks which organize related modules
          into directories.</td>
          <td>No</td>
        </tr>
        <tr>
          <td>module</td>
          <td>An override for the name of the cvs module.</td>
          <td>No.  Defaults to the name of the module.</td>
        </tr>
        <tr>
          <td>tag</td>
          <td>Specify the cvs tag desired.</td>
          <td>No.  Effectively defaults to HEAD.</td>
        </tr>
        <tr>
          <td>compress</td>
          <td>Set the compression level.  Some CVS client/server combinations 
            will not work with compression.</td>
          <td>No.  Defaults to the compress value for the repository</td>
        </tr>
      </table>
    </section>

    <section><title>svn</title>

      <p>References the
      Subversion <link href="repository.html">repository</link> in
      which this project resides.  May also contain various
      overrides.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>repository</td>
          <td>The name of the repository in which this module resides.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>dir</td>
          <td>The subdirectory in which the svn module is present.  Useful
          for repositories like Apache's which organize related modules
          into directories.</td>
          <td>No</td>
        </tr>
      </table>
    </section>

    <section><title>p4</title>

      <p>References a <link href="https://www.perforce.com/">Perforce</link> 
      repository in which this project resides.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>repository</td>
          <td>The name of the repository in which this module resides.</td>
          <td>Yes</td>
        </tr>
      </table>

      <p>For example:</p>
          <source>
  &lt;p4 repository="my-p4-repository"/&gt;
</source>    
    </section>

    <section><title>git</title>

      <p>References the
      Git <link href="repository.html">repository</link> in
      which this project resides.  May also contain various
      overrides.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>repository</td>
          <td>The name of the repository in which this module resides.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>dir</td>
          <td>The subdirectory in which the git module is present.
          Useful for repositories which organize related modules into
          directories.</td>
          <td>No</td>
        </tr>
        <tr>
          <td>branch</td>
          <td>Remote git branch to pull from.</td>
          <td>No, defaults to "master".</td>
        </tr>
        <tr>
          <td>debug verbose</td>
          <td>Setting either of these attributes to "true" removes --quiet flag
          from git commands.</td>
          <td>No, defaults to "false".</td>
        </tr>
      </table>
    </section>

    <section><title>darcs</title>

      <p>References the
      darcs <link href="repository.html">repository</link> in
      which this project resides.  May also contain various
      overrides.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>repository</td>
          <td>The name of the repository in which this module resides.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>dir</td>
          <td>The subdirectory in which the darcs module is present.
          Useful for repositories which organize related modules into
          directories.</td>
          <td>No</td>
        </tr>
      </table>
    </section>

    <section><title>bzr</title>

      <p>References the
      Bazaar <link href="repository.html">repository</link> in
      which this project resides.  May also contain various
      overrides.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>repository</td>
          <td>The name of the repository in which this module resides.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>dir</td>
          <td>The subdirectory in which the bzr module is present.
          Useful for repositories which organize related modules into
          directories.</td>
          <td>No</td>
        </tr>
      </table>
    </section>

    <section><title>hg</title>

      <p>References the
      Mercurial <link href="repository.html">repository</link> in
      which this project resides.  May also contain various
      overrides.</p>

      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required?</th>
        </tr>
        <tr>
          <td>repository</td>
          <td>The name of the repository in which this module resides.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>dir</td>
          <td>The subdirectory in which the hg module is present.
          Useful for repositories which organize related modules into
          directories.</td>
          <td>No</td>
        </tr>
      </table>
    </section>

    <section><title>project</title>
      <p>A definition of a <link href="project.html">project</link> which is
      physically contained in this module.</p>
    </section>

    <section><title>redistributable</title>
      <p>If present, indicates that outputs of builds from this module
      are redistributable.  Defaults to the redistributable value for
      the repository.</p>
    </section>
  </section>
</body>
</document>
