notify-dpml AT lists.ibiblio.org
Subject: DPML Notify
List archive
r1629 - in trunk/central/site/src/docs/depot/tutorials: modules simple
- From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
- To: notify-dpml AT lists.ibiblio.org
- Subject: r1629 - in trunk/central/site/src/docs/depot/tutorials: modules simple
- Date: Sat, 22 Jul 2006 09:58:06 +0200
Author: mcconnell
Date: 2006-07-22 09:58:05 +0200 (Sat, 22 Jul 2006)
New Revision: 1629
Added:
trunk/central/site/src/docs/depot/tutorials/modules/export.xml
trunk/central/site/src/docs/depot/tutorials/simple/imports.xml
trunk/central/site/src/docs/depot/tutorials/simple/unit.xml
Modified:
trunk/central/site/src/docs/depot/tutorials/modules/index.xml
trunk/central/site/src/docs/depot/tutorials/modules/navigation.xml
trunk/central/site/src/docs/depot/tutorials/simple/navigation.xml
Log:
add tutorial content on module imports and unit tests
Added: trunk/central/site/src/docs/depot/tutorials/modules/export.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/modules/export.xml
2006-07-22 07:57:11 UTC (rev 1628)
+++ trunk/central/site/src/docs/depot/tutorials/modules/export.xml
2006-07-22 07:58:05 UTC (rev 1629)
@@ -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>
+
Modified: trunk/central/site/src/docs/depot/tutorials/modules/index.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/modules/index.xml
2006-07-22 07:57:11 UTC (rev 1628)
+++ trunk/central/site/src/docs/depot/tutorials/modules/index.xml
2006-07-22 07:58:05 UTC (rev 1629)
@@ -8,182 +8,88 @@
<body>
- <section name="Creating a group Module">
+ <section name="Working with Modules">
<subsection name="Tutorial Objective">
<p>
- The objective of this tutorial is to intrioduce the concept of a
module
- and walk through the process of module creation. The tutorial
concludes
- with the summary of the generated module artifact and a description
of
- how a module can be used when sharing your project resources with
others.
+ 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="dev/library.xml">
+ <subsection name="index.xml">
<p>
- We need to update our library.xml file to include the declaration of
a
- module basedir and the assignment of an output artifact type.
+ 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>
-<source>
-<library xmlns="artifact:xsd:dpml/lang/dpml-module#1.0">
-
- <imports>
- <import uri="link:module:ant"/>
- </imports>
-
- <modules>
-
- <module name="acme" <font color="darkred">basedir="."</font>>
-
- <font color="darkred"><types>
- <type id="module"/>
- </types></font>
-
- <project name="acme-client" basedir="client">
- <types>
- <type id="jar"/>
- </types>
- </project>
+<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>
- <project name="acme-system" basedir="system">
- <types>
- <type id="jar"/>
- </types>
- <dependencies>
- <include key="acme-client"/>
- </dependencies>
- <dependencies scope="test">
- <include ref="ant/ant-junit"/>
- </dependencies>
- </project>
-
- </module>
+ <font color="darkred"></module></font>
- </modules>
+</index>
+</pre>
-</library>
-</source>
-
</subsection>
- <subsection name="Validating Module Definition">
+ <subsection name="Listing the Module">
<p>
- To validate that the module has been declared correctly you should
be able
- list information about the module project using the following
command:
+ 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>
-$ build -list -select acme
+$ cd tutorials\tooling\complex\modules
+$ build -list
-Listing module [acme]
+Selection: [3]
-module:acme
+ <font color="blue">[1] project:org/acme/widget#SNAPSHOT
+ [2] project:org/acme/gizmo#SNAPSHOT
+ [3] module:org/acme/#SNAPSHOT</font>
- version: SNAPSHOT
- basedir: C:\dev\osm\trunk\tutorial\tooling\104
- imports: (1)
- module:ant
- resources: (2)
- project:acme/acme-client
- project:acme/acme-system
-</pre>
+$</pre>
<p>
- Building the module will result in the creation of a module resource
- under the <tt>target/deliverables/modules</tt> subdirectory.
+ 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>
-<pre>
-$ build -select acme
-</pre>
-
- <p>
- The resulting module file is shown below. The principal differences
- between the original library file and the generated module is the
removal
- of build-time concerns. For example, projects are represented as
resource,
- basedir info has been removed along with build and test pahse
dependency
- information.
- </p>
-
-<source><![CDATA[
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<module name="acme" version="SNAPSHOT"
- xmlns="link:xsd:dpml/lang/dpml-module#1.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";>
-
- <types>
- <type id="module" alias="true"/>
- </types>
-
- <resource name="acme-client" version="SNAPSHOT">
- <types>
- <type id="jar"/>
- </types>
- </resource>
-
- <resource name="acme-system" version="SNAPSHOT">
- <types>
- <type id="jar"/>
- </types>
- <dependencies>
- <runtime>
- <include ref="acme/acme-client"/>
- </runtime>
- </dependencies>
- </resource>
-
-</module>
-]]></source>
-
</subsection>
-
- <subsection name="Referencing the Module Resource">
-
- <p>
- The contents of the module resources created as an output of the
build is
- an encoded XML file. It contains all module property declarations
and our
- two projects in the form of resource definitions suitable for use by
external
- projects in the same way we imported the ant module during the
testcase
- tutorial.
- </p>
-
- <p><i>Example of an import by an external library of the module
created above:</i></p>
-
-<source>
-<library>
-
- <imports>
- <import uri="<font
color="darkred">artifact:module:acme#SNAPSHOT</font>"/>
- </imports>
-
- <modules>
-
- ...
-
- </modules>
-
-</library>
-</source>
-
- </subsection>
-
- <subsection name="Summary">
-
- <p>
- This tutorial has demonstrated the creation of a stand-alone module
definition
- suitable for import by external projects - hoewever - the tutorial
has introduced
- an issue in that we have added a SNAPSHOT reference to our library
defintion and
- that is a bad thing. Our next torial addresses this issue through
the declaration
- and usage of <a href="alias.html">platform independent symbolic
links</a>.
- </p>
-
- </subsection>
-
+
</section>
</body>
Modified: trunk/central/site/src/docs/depot/tutorials/modules/navigation.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/modules/navigation.xml
2006-07-22 07:57:11 UTC (rev 1628)
+++ trunk/central/site/src/docs/depot/tutorials/modules/navigation.xml
2006-07-22 07:58:05 UTC (rev 1629)
@@ -25,7 +25,7 @@
<body>
<menu>
- <!--<item name="Runtime Dependencies" href="runtime.html"/>-->
+ <item name="Exporting a Module" href="export.html"/>
</menu>
</body>
Added: trunk/central/site/src/docs/depot/tutorials/simple/imports.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/simple/imports.xml
2006-07-22 07:57:11 UTC (rev 1628)
+++ trunk/central/site/src/docs/depot/tutorials/simple/imports.xml
2006-07-22 07:58:05 UTC (rev 1629)
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Alias Declaration</title>
+ </properties>
+
+ <body>
+
+ <section name="Using Module Imports">
+
+ <p>
+ This tutorial introduces the use of external modules as a reliable
+ method of declaring dependencies. In this example we are replacing
+ the somewhere error-prone manual declaration of test-scope dependnecies
+ with a single resource reference defined in an external module.
+ </p>
+
+ <subsection name="index.xml">
+
+ <p>
+ The first update to our index file is the addition of a module
+ import statement. The import statement is directing Depot to load
+ a module defintion for the Ant system which contains information
about
+ Ant resources and their respective dependencies. The second change
+ is the replacement of the manual uri-based dependency includes with
+ a single resource reference to <tt>ant/ant-junit</tt>. When Depot
+ resolves the transitive dependencies it will take into account the
+ dependencies declared by the <tt>ant/ant-junit</tt> resource
resulting
+ in a reliable and complete dependency set.
+ </p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+ <font color="darkred"><imports>
+ <import uri="link:module:ant"/>
+ </imports></font>
+
+ <project name="demo" basedir=".">
+ <properties>
+ <property name="location" value="New York"/>
+ <property name="message" value="Hello from ${user.name} in
${location}"/>
+ </properties>
+ <types>
+ <type id="jar" alias="true"/>
+ </types>
+ <dependencies>
+ <test>
+ <font color="darkred"><include ref="ant/ant-unit"/></font>
+ </test>
+ </dependencies>
+ <filters>
+ <filter token="MESSAGE" value="${message}"/>
+ </filters>
+ <dependencies>
+
+ </project>
+
+</index>
+</pre>
+
+ </subsection>
+
+ <subsection name="Listing the expanded dependencies ...">
+
+ <p>
+ The following command request a listing of our sample projects
+ dependencies. The <tt>-expand</tt> commandline option is telling
+ Depot that we want to see the fully expanded dependencies (i.e.
+ the dependnecies that will end up in the test classloader).
+ </p>
+
+<pre>
+$ cd tutorials\tooling\simple\import
+$ build -list -expand
+
+Listing project: demo
+
+project:demo#SNAPSHOT
+
+ version: SNAPSHOT
+ basedir: D:\dpml\tutorials\tooling\simple\import
+ types: (1)
+ jar
+ test providers: (6)
+ resource:ant/ant-launcher#1.6.5
+ resource:ant/ant-trax#1.6.5
+ resource:ant/ant-xslp#1.6.5
+ resource:ant/ant#1.6.5
+ resource:junit/junit#3.8.1
+ resource:ant/ant-junit#1.6.5
+</pre>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ This tutorial has presented the benefits arrising from the usage of
+ modules - and in-effect, leveraging dependency information from
external
+ projects.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+
Modified: trunk/central/site/src/docs/depot/tutorials/simple/navigation.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/simple/navigation.xml
2006-07-22 07:57:11 UTC (rev 1628)
+++ trunk/central/site/src/docs/depot/tutorials/simple/navigation.xml
2006-07-22 07:58:05 UTC (rev 1629)
@@ -31,6 +31,8 @@
<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"/>
</menu>
</body>
Added: trunk/central/site/src/docs/depot/tutorials/simple/unit.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/simple/unit.xml 2006-07-22
07:57:11 UTC (rev 1628)
+++ trunk/central/site/src/docs/depot/tutorials/simple/unit.xml 2006-07-22
07:58:05 UTC (rev 1629)
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Alias Declaration</title>
+ </properties>
+
+ <body>
+
+ <section name="Unit Testing">
+
+ <p>
+ In order to create a test-case we need to declare test scopped
+ dependencies on Ant's Junit runner. A simple approach is shown
+ in the following index.xml file.
+ </p>
+
+ <subsection name="index.xml">
+
+ <p>
+ In the following update to index.xml we have declared three
+ jar files under the test scope for our sample project. The ant-junit
+ file is dependent on both ant and junit so we need to declare the
+ dependencies as well (or risk a NoClassDefFoundException).
+ </p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+ <project name="demo" basedir=".">
+ <properties>
+ <property name="location" value="New York"/>
+ <property name="message" value="Hello from ${user.name} in
${location}"/>
+ </properties>
+ <types>
+ <type id="jar" alias="true"/>
+ </types>
+ <font color="darkred"><dependencies>
+ <test>
+ <include uri="artifact:jar:ant/ant-junit#1.6.5"/>
+ <include uri="artifact:jar:ant/ant#1.6.5"/>
+ <include uri="artifact:jar:junit/junit#3.8.1"/>
+ </test>
+ </dependencies></font>
+ <filters>
+ <filter token="MESSAGE" value="${message}"/>
+ </filters>
+ <dependencies>
+
+ </project>
+
+</index>
+</pre>
+
+ </subsection>
+
+ <subsection name="Executing the build ...">
+
+ <p>
+ Assuming that testcase sources are placed under the
<tt>src/test</tt> directory
+ the Depot build task will automatically trigger compilation and
testcase execution.
+ </p>
+
+<pre>
+$ cd tutorials\tooling\simple\testing
+$ build
+
+-------------------------------------------------------------------------
+demo#SNAPSHOT
+-------------------------------------------------------------------------
+
+init:
+
+prepare:
+[x:prepare] Created dir: D:\dpml\tutorials\tooling\simple\testing\target
+[x:prepare] Created dir:
D:\dpml\tutorials\tooling\simple\testing\target\build\main
+[x:prepare] Copying 1 file to
D:\dpml\tutorials\tooling\simple\testing\target\build\main
+[x:prepare] Created dir:
D:\dpml\tutorials\tooling\simple\testing\target\build\test
+[x:prepare] Copying 1 file to
D:\dpml\tutorials\tooling\simple\testing\target\build\test
+[x:prepare] Created dir: D:\dpml\tutorials\tooling\simple\testing\target\test
+
+build:
+ [javac] Created dir:
D:\dpml\tutorials\tooling\simple\testing\target\classes\main
+ [javac] Compiling 1 source file to
D:\dpml\tutorials\tooling\simple\testing\target\classes\main
+ [javac] Created dir:
D:\dpml\tutorials\tooling\simple\testing\target\classes\test
+ [javac] Compiling 1 source file to
D:\dpml\tutorials\tooling\simple\testing\target\classes\test
+
+package:
+ [jar] Created dir:
D:\dpml\tutorials\tooling\simple\testing\target\deliverables\jars
+ [jar] Building jar:
D:\dpml\tutorials\tooling\simple\testing\target\deliverables\jars\demo-SNAPSHOT.jar
+ [jar] Creating md5 checksum
+
+<font color="blue">test:
+ [junit] Created dir:
D:\dpml\tutorials\tooling\simple\testing\target\reports\test
+ [junit] Executing forked test.
+ [junit] Running org.acme.test.DemoTestCase
+ [junit] 22/07/2006 16:24:14 org.acme.test.DemoTestCase testTheClock
+ [junit] INFO: 4:24 PM, CST
+ [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.141
sec</font>
+
+install:
+[x:install] Copying 2 files to D:\system\dpml\data\cache
+
+BUILD SUCCESSFUL
+Total time: 4 seconds</pre>
+
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ This example has demonstrated the relatively easy process of adding
testcases
+ to a project. In addition we have demonstrated one mechanism
concerning the declaration
+ of dependencies - specifically the usage of the <tt>uri</tt>
attribute on dependency
+ include statements. However this approach is error-prone as it
assumes that the
+ dependencies listed fully complement each other. For example in the
dependencies listed
+ above we have not included ant-lancher, ant-trax or ant-xslp.
Futhermore this approach
+ presumes that we have the version combination correct.
+ </p>
+
+ <p>
+ An alternative (and more reliable) approach is presented in the <a
href="imports.html">
+ next tutorial</a> where we import an ant module and simply reference
the ant-junit
+ resource as a single dependency entry.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
+
- r1629 - in trunk/central/site/src/docs/depot/tutorials: modules simple, mcconnell at BerliOS, 07/22/2006
Archive powered by MHonArc 2.6.24.