<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  Copyright 2003-2004 The Apache Software Foundation

  Licensed 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>
    </table>

    <warning>Only Python Gump supports &lt;module debug=&quot;true&quot;</warning>

    <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 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>

      <p>Note: as the long term plans is to make Gump handle many different
      types of repository types, the name of this element should ultimately
      change</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 a <link href="http://subversion.tigris.org">Subversion</link> 
      repository in which this project resides.</p>

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

      <p>For example:</p>
          <source>
  &lt;svn url="http://svn.collab.net/repos/svn/trunk" /&gt;
</source>    
    </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>
