notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1630 - trunk/central/site/src/docs/depot/tutorials

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1630 - trunk/central/site/src/docs/depot/tutorials
Date: Sat, 22 Jul 2006 10:22:36 +0200

Author: mcconnell
Date: 2006-07-22 10:22:35 +0200 (Sat, 22 Jul 2006)
New Revision: 1630

Added:
trunk/central/site/src/docs/depot/tutorials/alias.xml
trunk/central/site/src/docs/depot/tutorials/automation.xml
trunk/central/site/src/docs/depot/tutorials/complex.xml
trunk/central/site/src/docs/depot/tutorials/export.xml
trunk/central/site/src/docs/depot/tutorials/filters.xml
trunk/central/site/src/docs/depot/tutorials/imports.xml
trunk/central/site/src/docs/depot/tutorials/modules.xml
trunk/central/site/src/docs/depot/tutorials/properties.xml
trunk/central/site/src/docs/depot/tutorials/simple.xml
trunk/central/site/src/docs/depot/tutorials/symbolic.xml
trunk/central/site/src/docs/depot/tutorials/types.xml
trunk/central/site/src/docs/depot/tutorials/unit.xml
Removed:
trunk/central/site/src/docs/depot/tutorials/complex/
trunk/central/site/src/docs/depot/tutorials/modules/
trunk/central/site/src/docs/depot/tutorials/simple/
Modified:
trunk/central/site/src/docs/depot/tutorials/index.xml
trunk/central/site/src/docs/depot/tutorials/navigation.xml
Log:
flattern Depot tutorials

Copied: trunk/central/site/src/docs/depot/tutorials/alias.xml (from rev 1622,
trunk/central/site/src/docs/depot/tutorials/simple/alias.xml)

Copied: trunk/central/site/src/docs/depot/tutorials/automation.xml (from rev
1622, trunk/central/site/src/docs/depot/tutorials/simple/automation.xml)

Added: trunk/central/site/src/docs/depot/tutorials/complex.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/complex.xml 2006-07-22
07:58:05 UTC (rev 1629)
+++ trunk/central/site/src/docs/depot/tutorials/complex.xml 2006-07-22
08:22:35 UTC (rev 1630)
@@ -0,0 +1,209 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Multi-Project Build Sequencing</title>
+ </properties>
+
+ <body>
+
+ <section name="Multi-Project Build Sequencing">
+
+ <p>
+ An important aspect of Depot is the support for transitive
+ dependency management. Dependencies between project are maintained
+ relative to the following scopes:
+ </p>
+
+ <table>
+ <tr>
+ <td>build</td>
+ <td>
+ Declaration of one or build sequence dependencies. When
+ a project declares a build scoped dependency on another
+ project - Depot will ensure that the dependee project is
+ built before the dependee project.
+ </td>
+ </tr>
+ <tr>
+ <td>runtime</td>
+ <td>
+ Declaration of one or runtime dependencies. Runtime dependencies
+ are used by Depot to construct classloader chains resulting in
+ the potential automation of several common build requirements
+ (such as source code compilation). Runtime dependencies are
+ fully transitive in that the runtime dependencies of a project
+ are constructed by expanding the runtime dependencies of any
+ projects declared as runtime dependencies, and any runtime
+ dependencies of the dependee projects (etc., etc.).
+ </td>
+ </tr>
+ <tr>
+ <td>test</td>
+ <td>
+ Declaration of one or test dependencies. Test scoped dependencies
+ are used to suppliment transitive runtime dependencies and are
typically
+ applied to the automation of test-cases. An import aspect of
+ of test scope dependencies is the abiluity to separate test
concerns from
+ runtime concerns - ensuring that runtime meta-data is not
poluted with
+ test related information.
+ </td>
+ </tr>
+ </table>
+
+ <subsection name="index.xml">
+
+ <p>
+ Our index file has been updated to declare two projects named widget
and gizmo
+ and we have relocated our index file to a directory above the
respective
+ project basedirs. The <tt>gizmo</tt> project is declaring a
build-time dependency
+ on the <tt>widget</tt> project which simply ensures that
<tt>widget</tt> will be
+ built before <tt>gizmo</tt>. Basedir values for both projects are
declared as
+ immidiate subdirectories relative to the location of the index.xml
file.
+ </p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+ <font color="darkred"><project name="widget" basedir="widget"/>
+
+ <project name="gizmo" basedir="gizmo">
+ <dependencies>
+ <build>
+ <include key="widget"/>
+ </build>
+ </dependencies>
+ </project></font>
+
+</index>
+</pre>
+
+ </subsection>
+
+ <subsection name="Listing project sequence">
+
+ <p>
+ Before building our projects we will take a moment to look at the
build
+ tools <tt>-list</tt> option.
+ </p>
+
+ <pre>$ cd central\tutorials\tooling\complex\build</pre>
+
+ <p>
+ The following command list all project below our current directory
+ in proper build sequence:
+ </p>
+
+ <pre>
+$ build -list
+Selection: [2]
+
+ [1] project:widget#SNAPSHOT
+ [2] project:gizmo#SNAPSHOT
+</pre>
+
+ </subsection>
+
+ <subsection name="Listing project details">
+
+ <p>
+ We can also list information about a specific project as shown in
the following
+ example where we are requesting a detailing listing of the gizmo
project.
+ </p>
+
+ <pre>
+$ build -list -select gizmo
+Listing project: gizmo
+
+project:gizmo#SNAPSHOT
+
+ version: SNAPSHOT
+ basedir: D:\dpml\tutorials\tooling\complex\build\gizmo
+ build phase providers: (1)
+ project:widget#SNAPSHOT</pre>
+
+ <p>
+ Just for reference - the above command can be simplified to:
+ </p>
+
+<pre>$ build -l -s gizmo</pre>
+
+ </subsection>
+
+ <subsection name="Addition build options">
+
+ <p>For additional information on the build tool command options
+ the <tt>-help</tt> option is always available.
+ </p>
+
+<pre>$ build -help</pre>
+
+ </subsection>
+
+ <subsection name="Building the projects ..">
+
+ <p>
+ In the following example the <tt>build</tt> command is invoked
+ in the parent directory to the widget and gizmo projects. As such
+ the build tool will evaluate all projects declared in the index and
+ establish a build selection that includes all projects with a basedir
+ that is equal to or deeper that our current directory. This selction
+ is then sorted in terms of build-time dependencies resulting in
widget
+ appearing before gizmo. The build tool then initiates the build of
+ each project. If there is a failure of an indivial build then the
+ multi-project build sequence will fail.
+ </p>
+
+ <pre>
+$ build
+[2788 ] [INFO ] (depot.build): Initiating build sequence: (2)
+
+ (1) widget
+ (2) gizmo
+
+
+-------------------------------------------------------------------------
+widget#SNAPSHOT
+-------------------------------------------------------------------------
+
+build:
+ [echo] Executing WIDGET build
+
+BUILD SUCCESSFUL
+Total time: 0 seconds
+
+-------------------------------------------------------------------------
+gizmo#SNAPSHOT
+-------------------------------------------------------------------------
+
+build:
+ [echo] Executing GIZMO build
+
+BUILD SUCCESSFUL
+Total time: 0 seconds
+ </pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ This tutorial has introduced the subject of build-scoped dependencies
+ and how these dependencyt declarations impact build sequencing. In
practice
+ you will not generally need build-time dependency declarations -
instead it
+ is much more common to see runtime dependencies linking projects
together, and
+ its within runtime depedencies that we can do things like automatic
classpath
+ construction. The <a href="runtime.html">following tutorial</a>
focuses on
+ runtime dependencies and demonstrates how an API defined in one
project can be
+ automatically included in the classpath of a dependent project.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+

Added: trunk/central/site/src/docs/depot/tutorials/export.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/export.xml 2006-07-22
07:58:05 UTC (rev 1629)
+++ trunk/central/site/src/docs/depot/tutorials/export.xml 2006-07-22
08:22:35 UTC (rev 1630)
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Working with Modules</title>
+ </properties>
+
+ <body>
+
+ <section name="Exporting Modules">
+
+ <subsection name="Tutorial Objective">
+
+ <p>
+ In this tutorial we are demonstration how you can create a module
+ artifact suitable for use by other third-parties.
+ </p>
+
+ </subsection>
+
+ <subsection name="index.xml">
+
+ <p>
+ Our index definition remains unchanged except for the addition of
+ a type production statement declaring that the module build produces
+ a module artifact (and just for fun we have requested a version alias
+ to be produced at the same time).
+ </p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+ <module name="org/acme" basedir=".">
+
+ <font color="darkred"><types>
+ <type id="module" version="1.0">
+ </types></font>
+
+ <project name="widget" basedir="widget"/>
+
+ <project name="gizmo" basedir="gizmo">
+ <dependencies>
+ <build>
+ <include key="widget"/>
+ </build>
+ </dependencies>
+ </project>
+
+ <font color="darkred"></module></font>
+
+</index>
+</pre>
+
+ </subsection>
+
+ <subsection name="The Generated Module Artifact">
+
+ <p>
+ In this example we are building the module project using the
+ Depot template. As such Depot's project aware tasks are detecting
+ the type production statement associated with the module, resulting
in
+ the automatic production of the external module artifact under the
+ <tt>target/deliverables/modules/acme-SNAPSHOT.module</tt> file.
+ </p>
+
+<source><![CDATA[
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<module name="org"
+ xmlns="link:xsd:dpml/lang/dpml-module#1.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
+
+ <module name="acme" version="SNAPSHOT">
+
+ <types>
+ <type id="module" version="1.0"/>
+ </types>
+
+ <resource name="widget" version="SNAPSHOT">
+ </resource>
+
+ <resource name="gizmo" version="SNAPSHOT">
+ </resource>
+
+ </module>
+
+</module>
+]]></source>
+
+ <p>
+ Something imprant to note is that the above listing includes our two
+ projects <tt>widget</tt> and <tt>gizmo</tt> together with the
enclosing
+ module. In effect a module that declares a basedir is considered as
a
+ buildable project. Sometime 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.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+

Copied: trunk/central/site/src/docs/depot/tutorials/filters.xml (from rev
1622, trunk/central/site/src/docs/depot/tutorials/simple/filters.xml)

Copied: trunk/central/site/src/docs/depot/tutorials/imports.xml (from rev
1629, trunk/central/site/src/docs/depot/tutorials/simple/imports.xml)

Modified: trunk/central/site/src/docs/depot/tutorials/index.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/index.xml 2006-07-22
07:58:05 UTC (rev 1629)
+++ trunk/central/site/src/docs/depot/tutorials/index.xml 2006-07-22
08:22:35 UTC (rev 1630)
@@ -20,14 +20,97 @@

<table>
<tr>
- <td width="15%"><a href="simple/index.html">Getting
Started</a></td>
+ <td width="15%"><a href="simple.html">Getting Started</a></td>
<td width="60%">
- collection of tutorials dealing with the declaration of an
initial project
- and the usage of common functionality related to property and
filter declarations
- (including the usage of symbolic references).
+ Introduces the <tt>index.xml</tt> file.
</td>
<td/>
</tr>
+ <tr>
+ <td width="15%"><a href="properties.html">Definining
Properties</a></td>
+ <td width="60%">
+ Examples of project level property declarations.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="symbolic.html">Symbolic
References</a></td>
+ <td width="60%">
+ Demonstrates the usage of symbolic refernces to system and
project-level properties.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="filters.html">Global Filters</a></td>
+ <td width="60%">
+ Examples of the declaration and application of a simple
filter.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="types.html">Type Production</a></td>
+ <td width="60%">
+ Examines the impact of type production statements within a
project.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="automation.html">Build
Automation</a></td>
+ <td width="60%">
+ Introduces the Depot build template and the potential for
build automation.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="alias.html">Alias Declarations</a></td>
+ <td width="60%">
+ Demonstrates version and non-version symbolic alias creation
and usage.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="unit.html">Unit Testing</a></td>
+ <td width="60%">
+ Example of the addition of a testcase and the related
concerns of test-scoped dependnecies.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="imports.html">Using Module
Imports</a></td>
+ <td width="60%">
+ Demonstrates improvements in transitive dependency
information through the use of module imports
+ and resource references.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="complex.html">Multiproject
Builds</a></td>
+ <td width="60%">
+ An example of a multi-project scenario.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="modules.html">Working with
Modules</a></td>
+ <td width="60%">
+ Improving resource naming using module declarations.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="export.html">Exporting Module
Defintions</a></td>
+ <td width="60%">
+ Module artifact export and use by third-party projects.
+ </td>
+ <td/>
+ </tr>
+ <tr>
+ <td width="15%"><a href="versioned.html">Versioned
Builds</a></td>
+ <td width="60%">
+ Demonstration of a version build.
+ </td>
+ <td/>
+ </tr>
</table>

</subsection>

Added: trunk/central/site/src/docs/depot/tutorials/modules.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/modules.xml 2006-07-22
07:58:05 UTC (rev 1629)
+++ trunk/central/site/src/docs/depot/tutorials/modules.xml 2006-07-22
08:22:35 UTC (rev 1630)
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Working with Modules</title>
+ </properties>
+
+ <body>
+
+ <section name="Working with Modules">
+
+ <subsection name="Tutorial Objective">
+
+ <p>
+ 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
+ <tt>artifact:part:dpml/metro/dpml-metro-runtime#1.0.0</tt> is
referencing
+ a resource named <tt>dpml-metro-runtime</tt> in the
<tt>dpml/metro</tt>
+ module.
+ </p>
+
+ </subsection>
+
+ <subsection name="index.xml">
+
+ <p>
+ 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 <tt>org/acme</tt>.
+ </p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+ <font color="darkred"><module name="org/acme" basedir="."></font>
+
+ <project name="widget" basedir="widget"/>
+
+ <project name="gizmo" basedir="gizmo">
+ <dependencies>
+ <build>
+ <include key="widget"/>
+ </build>
+ </dependencies>
+ </project>
+
+ <font color="darkred"></module></font>
+
+</index>
+</pre>
+
+ </subsection>
+
+ <subsection name="Listing the Module">
+
+ <p>
+ 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 <tt>org/acme</tt>
+ namespace.
+ </p>
+
+<pre>
+$ cd tutorials\tooling\complex\modules
+$ build -list
+
+Selection: [3]
+
+ <font color="blue">[1] project:org/acme/widget#SNAPSHOT
+ [2] project:org/acme/gizmo#SNAPSHOT
+ [3] module:org/acme/#SNAPSHOT</font>
+
+$</pre>
+
+ <p>
+ Something imprant to note is that the above listing includes our two
+ projects <tt>widget</tt> and <tt>gizmo</tt> together with the
enclosing
+ module. In effect a module that declares a basedir is considered as
a
+ buildable project. Sometime 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.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+

Modified: trunk/central/site/src/docs/depot/tutorials/navigation.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/navigation.xml 2006-07-22
07:58:05 UTC (rev 1629)
+++ trunk/central/site/src/docs/depot/tutorials/navigation.xml 2006-07-22
08:22:35 UTC (rev 1630)
@@ -25,9 +25,18 @@
<body>

<menu>
- <item name="Getting Started" href="simple/index.html"/>
- <item name="Multiproject Builds" href="complex/index.html"/>
- <item name="Using Modules" href="modules/index.html"/>
+ <item name="Getting Started" href="simple.html"/>
+ <item name="General Properties" href="properties.html"/>
+ <item name="Symbolic References" href="symbolic.html"/>
+ <item name="Global Filters" href="filters.html"/>
+ <item name="Type Production" href="types.html"/>
+ <item name="Build Automation" href="automation.html"/>
+ <item name="Alias Declarations" href="alias.html"/>
+ <item name="Unit Testing" href="unit.html"/>
+ <item name="Module Imports" href="imports.html"/>
+ <item name="Multiproject Builds" href="complex.html"/>
+ <item name="Working with Modules" href="modules.html"/>
+ <item name="Exporting Modules" href="export.html"/>
<item name="Versioned Builds" href="versioned.html"/>
</menu>

Copied: trunk/central/site/src/docs/depot/tutorials/properties.xml (from rev
1622, trunk/central/site/src/docs/depot/tutorials/simple/properties.xml)

Copied: trunk/central/site/src/docs/depot/tutorials/simple.xml (from rev
1622, trunk/central/site/src/docs/depot/tutorials/simple/index.xml)

Copied: trunk/central/site/src/docs/depot/tutorials/symbolic.xml (from rev
1622, trunk/central/site/src/docs/depot/tutorials/simple/symbolic.xml)

Copied: trunk/central/site/src/docs/depot/tutorials/types.xml (from rev 1622,
trunk/central/site/src/docs/depot/tutorials/simple/types.xml)

Copied: trunk/central/site/src/docs/depot/tutorials/unit.xml (from rev 1629,
trunk/central/site/src/docs/depot/tutorials/simple/unit.xml)

r1630 - trunk/central/site/src/docs/depot/tutorials, mcconnell at BerliOS, 07/22/2006