You are viewing a plain text version of this content. The canonical link for it is here.
Posted to alexandria-dev@jakarta.apache.org by ru...@apache.org on 2001/09/26 00:35:36 UTC
cvs commit: jakarta-alexandria/proposal/gump/site/xdocs ant.xml module.xml profile.xml project.xml repository.xml status.xml workspace.xml
rubys 01/09/25 15:35:36
Modified: proposal/gump/site/xdocs module.xml profile.xml project.xml
repository.xml status.xml workspace.xml
Added: proposal/gump/site/xdocs ant.xml
Log:
More documentation. Now there is a reasonable first pass over the data
structures.
Revision Changes Path
1.3 +12 -6 jakarta-alexandria/proposal/gump/site/xdocs/module.xml
Index: module.xml
===================================================================
RCS file: /home/cvs/jakarta-alexandria/proposal/gump/site/xdocs/module.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- module.xml 2001/09/25 05:22:27 1.2
+++ module.xml 2001/09/25 22:35:36 1.3
@@ -9,8 +9,8 @@
<body>
<section name="module">
- <p>A <a href="module.html">module</a> is a collection of projects that
- are physically stored in a single repository.</p>
+ <p>A module is a collection of projects that are physically stored in a
+ single repository.</p>
<subsection name="url">
<p>This is the homepage for the collection of projects contained in
@@ -30,8 +30,14 @@
<tr>
<td>href</td>
<td>URL of home page</td>
- <td>Yes.</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>
</subsection>
@@ -57,21 +63,21 @@
<tr>
<td>repository</td>
<td>The name of the repository in which this module resides.</td>
- <td>Yes.</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>
+ <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>
+ <td>No</td>
</tr>
<tr>
<td>module</td>
1.3 +11 -10 jakarta-alexandria/proposal/gump/site/xdocs/profile.xml
Index: profile.xml
===================================================================
RCS file: /home/cvs/jakarta-alexandria/proposal/gump/site/xdocs/profile.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- profile.xml 2001/09/25 05:22:27 1.2
+++ profile.xml 2001/09/25 22:35:36 1.3
@@ -9,8 +9,8 @@
<body>
<section name="profile">
- <p>A profile is a collection of projects and repositories that are
- logically to be considered a unit. A profile can provide a consistent set
+ <p>A profile is a collection of projects and repositories that are
+ logically to be considered a unit. A profile can provide a consistent set
of installable dependencies, or tagged versions of cvs modules to be used.
</p>
@@ -29,13 +29,13 @@
<tr>
<td>href</td>
<td>URI of the file containing the module definition</td>
- <td>Yes.</td>
+ <td>Yes</td>
</tr>
</table>
</subsection>
<subsection name="project">
- <p>An individual project to be extended. For a complete description,
+ <p>An individual project to be extended. For a complete description,
see the documentation for <a href="project.html">project</a>.</p>
<table>
@@ -47,22 +47,23 @@
<tr>
<td>name</td>
<td>Name of the project to be modified</td>
- <td>Yes.</td>
+ <td>Yes</td>
</tr>
<tr>
<td>package</td>
<td>Specifies the name of the subdirectory relative to the pkgdir
specified in the workspace definition.
</td>
- <td>No.</td>
+ <td>No</td>
+
</tr>
</table>
</subsection>
<subsection name="repository">
- <p>An repository to be included. While a complete repository can be
- defined here, typically one is referenced via href. For a complete
- description, see the documentation for
+ <p>An repository to be included. While a complete repository can be
+ defined here, typically one is referenced via href. For a complete
+ description, see the documentation for
<a href="repository.html">repository</a>.</p>
<table>
@@ -74,7 +75,7 @@
<tr>
<td>href</td>
<td>URI of the file containing the repository definition</td>
- <td>Yes.</td>
+ <td>Yes</td>
</tr>
</table>
</subsection>
1.2 +184 -7 jakarta-alexandria/proposal/gump/site/xdocs/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-alexandria/proposal/gump/site/xdocs/project.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- project.xml 2001/09/25 02:30:35 1.1
+++ project.xml 2001/09/25 22:35:36 1.2
@@ -9,30 +9,207 @@
<body>
<section name="project">
- <p>TBD</p>
+ <p>A project is the atomic unit of integration. It can describe an
+ installable package or a buildable product. The nested elements of
+ a project definition fall into three different "groups", each optional:</p>
+
+ <ul>
+ <li>Build instructions: <ant> and <script>. Describes how to
+ produce the outputs from the inputs.</li>
+ <li>Inputs: <depend>, <option>, and <work>. Describes
+ where to find the inputs (primarily jar files, but can be directories and
+ files).</li>
+ <li>Outputs: <home> and <jar>. Describes where to locate
+ the output files.</li>
+ </ul>
+
+ <p>Note that <depend> elements nested within <ant>
+ elements are precisely equivalent to specifying both a property to be
+ passed to Ant, as well as a separate depend element.</p>
<subsection name="ant">
- <p></p>
+ <p>Identifies this project as "buildable", and specifies the
+ target to build and the properties to be passed to ant. The full
+ description of this XML element can be found
+ <a href="ant.html">here</a></p>
+
+ <p><a href="http://jakarta.apache.org/ant/">Jakarta Ant</a> is the
+ defacto build tool used by a large number of Open Source Java
+ projects.</p>
</subsection>
+ <subsection name="script">
+ <p>Identifies this project as "buildable", and specifies the
+ script to be executed in order to make this happen. The assumption
+ is that the script can be invoked in a platform independent manner,
+ though the contents of the script may be platform specific.
+ Specifically, if the name of the script is "name", it will be
+ invoked as follows:</p>
+
+ <p>At the present time, the only use of this is during the bootstrap
+ process for Ant.</p>
+
+ <ul>
+ <li>On Windows/batch, "call .\name.bat"</li>
+ <li>On Unix/bash, "./name.sh"</li>
+ </ul>
+
+ <table>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required?</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>The name of the script to execute.</td>
+ <td>Yes</td>
+ </tr>
+ </table>
+ </subsection>
+
<subsection name="depend">
- <p></p>
+ <p>Specifies the name of a required prerequisite project. If a
+ definition for that project is not found in the workspace, the
+ generation will fail.</p>
+
+ <p>For a build "all", the invocation of ant or the script is bypassed
+ if any of the outputs of the specified project can not be found.</p>
+
+ <p>For both script and ant based builds, any jars defined by the
+ specified project as outputs are added to the CLASSPATH prior to
+ invoking the build operation.</p>
+
+ <table>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required?</th>
+ </tr>
+ <tr>
+ <td>project</td>
+ <td>The name of the project depended on.</td>
+ <td>Yes</td>
+ </tr>
+ </table>
</subsection>
<subsection name="option">
- <p></p>
+ <p>Specifies the name of an optional prerequisite project. If a
+ definition for that project is not found in the workspace, the
+ dependency is ignored.</p>
+
+ <p>For both script and ant based builds, any jars defined by the
+ specified project as outputs are added to the CLASSPATH prior to
+ invoking the build operation. If the files are not present,
+ this will have little effect.</p>
+
+ <table>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required?</th>
+ </tr>
+ <tr>
+ <td>project</td>
+ <td>The name of the project depended on.</td>
+ <td>Yes</td>
+ </tr>
+ </table>
</subsection>
<subsection name="work">
- <p></p>
+ <p>Adds a directory or a file to the class path. This is to allow
+ projects which have compilation dependencies on byproducts of the build
+ (example: tests which import the project itself. This is necessary when
+ using the Ant build.sysclasspath="ignore".</p>
+
+ <p>It generally is OK if the directory is not present prior to the
+ build. However, if this directory is deleted during the course of
+ the build, the behavior of the JVM may become unpredictable.</p>
+
+ <p>If neither the parent nor the nested attributes are present, then
+ the srcdir for the module is added to the classpath.</p>
+
+ <table>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required?</th>
+ </tr>
+ <tr>
+ <td>parent</td>
+ <td>Name of a directory or file, relative to the base directory
+ of the workspace.</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>nested</td>
+ <td>Name of a directory or file, relative to the srcdir of the module
+ containing this project.</td>
+ <td>No</td>
+ </tr>
+ </table>
</subsection>
<subsection name="home">
- <p></p>
+ <p>The home directory for a project is the directory which contains the
+ files referenceable by another project. In many cases, it is possible
+ for another project element by the same name (see the
+ <a href="overview.html">overview</a>) to extend a project definition
+ for an installable package in such a way that the result actually builds
+ the project.</p>
+
+ <p>A home attribute on a project definition will override this value.</p>
+
+ <p>A package attribute on a project will provide a default for this
+ value. Such a default would be relative to the workspace pkgdir</p>
+
+ <p>If none of these attributes or elements, the default value is
+ the srcdir for the module.</p>
+
+ <table>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required?</th>
+ </tr>
+ <tr>
+ <td>parent</td>
+ <td>Name of a directory or file, relative to the base directory
+ of the workspace.</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>nested</td>
+ <td>Name of a directory or file, relative to the srcdir of the module
+ containing this project.</td>
+ <td>No</td>
+ </tr>
+ </table>
</subsection>
<subsection name="jar">
- <p></p>
+ <p>The name of an output jar, relative to the home directory.</p>
+
+ <table>
+ <tr>
+ <th>Attribute</th>
+ <th>Description</th>
+ <th>Required?</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>The name of the jar</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>id</td>
+ <td>Provides a unique id which can be used to provide selection
+ between multiple jars definitions.</td>
+ <td>No</td>
+ </tr>
+ </table>
</subsection>
</section>
1.2 +1 -1 jakarta-alexandria/proposal/gump/site/xdocs/repository.xml
Index: repository.xml
===================================================================
RCS file: /home/cvs/jakarta-alexandria/proposal/gump/site/xdocs/repository.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- repository.xml 2001/09/25 02:30:35 1.1
+++ repository.xml 2001/09/25 22:35:36 1.2
@@ -8,7 +8,7 @@
<body>
- <section name="Repository">
+ <section name="repository">
<p>This represents the location from which modules can be obtained.</p>
<table>
1.3 +20 -3 jakarta-alexandria/proposal/gump/site/xdocs/status.xml
Index: status.xml
===================================================================
RCS file: /home/cvs/jakarta-alexandria/proposal/gump/site/xdocs/status.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- status.xml 2001/09/25 12:20:13 1.2
+++ status.xml 2001/09/25 22:35:36 1.3
@@ -11,7 +11,8 @@
<section name="Recurring build problems">
<p>These represent "known problems". In some cases, they represent a
temporary problem that will be synched up at the point of the next
- release, in other cases they represent an abject failure to communicate</p>
+ release, in other cases they may represent an abject failure to
+ communicate.</p>
<subsection name="commons-latka">
<p>Latka depends on function which was subsequently rolled back from
@@ -88,9 +89,25 @@
</section>
<section name="Recent success stories">
- <p>TBD</p>
+ <p>This section describes cross project compatibility issues which were:
+ </p>
+
+ <ul>
+ <li>detected by gump</li>
+ <li>the changes would likely have otherwise gone undetected until
+ release</li>
+ <li>involved changes to one or both products</li>
+ <li>the changes were done prior to release.</li>
+ </ul>
+
+ <subsection name="jakarta-log4j">
+ <p>September 2001: in order to more closely resemble the JSR 47 API,
+ the Level class replaced the Priority class, and the Logger class
+ replaced the Category class. This was originally done in a manner which
+ was thought to be backwards compatible, but there was subtle reasons why
+ this was not the case.</p>
+ </subsection>
</section>
</body>
</document>
-
1.3 +11 -11 jakarta-alexandria/proposal/gump/site/xdocs/workspace.xml
Index: workspace.xml
===================================================================
RCS file: /home/cvs/jakarta-alexandria/proposal/gump/site/xdocs/workspace.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- workspace.xml 2001/09/25 05:22:27 1.2
+++ workspace.xml 2001/09/25 22:35:36 1.3
@@ -8,7 +8,7 @@
<body>
- <section name="Workspace">
+ <section name="workspace">
<p>This represents the combination of projects (either referenced
directly or indirectly, via profiles) that are to be built together.
By default, workspaces are named after the hostname of the computer
@@ -72,12 +72,12 @@
<th>Required?</th>
</tr>
<tr>
- <td>Name</td>
+ <td>name</td>
<td>Name of the property to set.</td>
<td>Yes</td>
</tr>
<tr>
- <td>Value</td>
+ <td>value</td>
<td>Desired value</td>
<td>Yes</td>
</tr>
@@ -99,7 +99,7 @@
<tr>
<td>href</td>
<td>URI of the file containing the profile definition</td>
- <td>Yes.</td>
+ <td>Yes</td>
</tr>
</table>
</subsection>
@@ -119,7 +119,7 @@
<tr>
<td>href</td>
<td>URI of the file containing the module definition</td>
- <td>Yes.</td>
+ <td>Yes</td>
</tr>
</table>
</subsection>
@@ -139,14 +139,14 @@
<tr>
<td>name</td>
<td>Name of the project to be modified</td>
- <td>Yes.</td>
+ <td>Yes</td>
</tr>
<tr>
<td>home</td>
<td>Convenient way to specify an override for a root/home
element.
</td>
- <td>No.</td>
+ <td>No</td>
</tr>
</table>
</subsection>
@@ -166,28 +166,28 @@
<tr>
<td>href</td>
<td>URI of the file containing the repository definition</td>
- <td>Yes.</td>
+ <td>Yes</td>
</tr>
<tr>
<td>method</td>
<td>Convenient way to specify an override for a root/method
element
</td>
- <td>No.</td>
+ <td>No</td>
</tr>
<tr>
<td>user</td>
<td>Convenient way to specify an override for a root/user
element
</td>
- <td>No.</td>
+ <td>No</td>
</tr>
<tr>
<td>path</td>
<td>Convenient way to specify an override for a root/path
element
</td>
- <td>No.</td>
+ <td>No</td>
</tr>
</table>
</subsection>
1.1 jakarta-alexandria/proposal/gump/site/xdocs/ant.xml
Index: ant.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<author email="rubys@us.ibm.com">Sam Ruby</author>
<title>Gump</title>
</properties>
<body>
<section name="ant">
<p>Specifies the arguments to be passed to Ant.</p>
<table>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required?</th>
</tr>
<tr>
<td>basedir</td>
<td>The base directory in which the build is executed. The generated
build script will make this directory the current working directory
prior to invoking Ant.
</td>
<td>No</td>
</tr>
<tr>
<td>target</td>
<td>The ant target to invoke.</td>
<td>No</td>
</tr>
</table>
<p/>
<subsection name="property">
<p>Property overrides to be passed to the Ant command</p>
<table>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required?</th>
</tr>
<tr>
<td>name</td>
<td>Name of the property to set.</td>
<td>Yes</td>
</tr>
<tr>
<td>value</td>
<td>Desired value</td>
<td>No</td>
</tr>
<tr>
<td>project</td>
<td>The name of the referenced project. Required if the reference
attribute is "home", "jar", "jarpath", or "srcdir".</td>
<td>No</td>
</tr>
<tr>
<td>reference</td>
<td>
<p>One of the following values:</p>
<ul>
<li>home: the home directory for the referenced project</li>
<li>jar: the simple name (path relative to home) of the jar in a
referenced project.</li>
<li>jarpath: the fully qualified path of the jar in a referenced
project.</li>
<li>srcdir: the srcdir for the module containing the project.</li>
<li>path: a path which is to be interpreted relative to the
srcdir for the module containing this project</li>
</ul>
</td>
<td>No</td>
</tr>
<tr>
<td>id</td>
<td>Specifies which jar is desired. Required only for projects which
define more than one jar.</td>
<td>No</td>
</tr>
</table>
</subsection>
<subsection name="depend">
<p>This is equivalent to a property reference="jarpath" as well as a
dependency element in the enclosing project. This was introduced as
that has become a common enough practice that it makes sense to
introduce this element</p>
<table>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required?</th>
</tr>
<tr>
<td>property</td>
<td>The name of the property which will receive the full jarpath
of the specified jar.</td>
<td>Yes</td>
</tr>
<tr>
<td>project</td>
<td>The name of the project depended on.</td>
<td>Yes</td>
</tr>
<tr>
<td>id</td>
<td>Specifies which jar is desired. Required only for projects which
define more than one jar.</td>
<td>No</td>
</tr>
</table>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: alexandria-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: alexandria-dev-help@jakarta.apache.org