Skip to Content.
Sympa Menu

notify-dpml - r1629 - in trunk/central/site/src/docs/depot/tutorials: modules simple

notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

Chronological Thread  
  • 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>
+&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
+&lt;index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+ &lt;module name="org/acme" basedir="."&gt;
+
+ <font color="darkred">&lt;types&gt;
+ &lt;type id="module" version="1.0"&gt;
+ &lt;/types&gt;</font>
+
+ &lt;project name="widget" basedir="widget"/&gt;
+
+ &lt;project name="gizmo" basedir="gizmo"&gt;
+ &lt;dependencies>
+ &lt;build>
+ &lt;include key="widget"/&gt;
+ &lt;/build&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;
+
+ <font color="darkred">&lt;/module&gt;</font>
+
+&lt;/index&gt;
+</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>
-&lt;library xmlns="artifact:xsd:dpml/lang/dpml-module#1.0"&gt;
-
- &lt;imports&gt;
- &lt;import uri="link:module:ant"/&gt;
- &lt;/imports&gt;
-
- &lt;modules&gt;
-
- &lt;module name="acme" <font color="darkred">basedir="."</font>&gt;
-
- <font color="darkred">&lt;types&gt;
- &lt;type id="module"/&gt;
- &lt;/types&gt;</font>
-
- &lt;project name="acme-client" basedir="client"&gt;
- &lt;types&gt;
- &lt;type id="jar"/&gt;
- &lt;/types&gt;
- &lt;/project&gt;
+<pre>
+&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
+&lt;index xmlns="link:xsd:dpml/lang/dpml-module#1.0">
+
+ <font color="darkred">&lt;module name="org/acme" basedir="."&gt;</font>
+
+ &lt;project name="widget" basedir="widget"/&gt;
+
+ &lt;project name="gizmo" basedir="gizmo"&gt;
+ &lt;dependencies>
+ &lt;build>
+ &lt;include key="widget"/&gt;
+ &lt;/build&gt;
+ &lt;/dependencies&gt;
+ &lt;/project&gt;

- &lt;project name="acme-system" basedir="system"&gt;
- &lt;types&gt;
- &lt;type id="jar"/&gt;
- &lt;/types&gt;
- &lt;dependencies&gt;
- &lt;include key="acme-client"/&gt;
- &lt;/dependencies&gt;
- &lt;dependencies scope="test"&gt;
- &lt;include ref="ant/ant-junit"/&gt;
- &lt;/dependencies&gt;
- &lt;/project&gt;
-
- &lt;/module&gt;
+ <font color="darkred">&lt;/module&gt;</font>

- &lt;/modules&gt;
+&lt;/index&gt;
+</pre>

-&lt;/library&gt;
-</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>
-&lt;library&gt;
-
- &lt;imports&gt;
- &lt;import uri="<font
color="darkred">artifact:module:acme#SNAPSHOT</font>"/&gt;
- &lt;/imports&gt;
-
- &lt;modules&gt;
-
- ...
-
- &lt;/modules&gt;
-
-&lt;/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>
+&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
+&lt;index xmlns="link:xsd:dpml/lang/dpml-module#1.0"&gt;
+
+ <font color="darkred">&lt;imports&gt;
+ &lt;import uri="link:module:ant"/&gt;
+ &lt;/imports&gt;</font>
+
+ &lt;project name="demo" basedir="."&gt;
+ &lt;properties&gt;
+ &lt;property name="location" value="New York"/&gt;
+ &lt;property name="message" value="Hello from ${user.name} in
${location}"/&gt;
+ &lt;/properties&gt;
+ &lt;types&gt;
+ &lt;type id="jar" alias="true"/&gt;
+ &lt;/types&gt;
+ &lt;dependencies&gt;
+ &lt;test&gt;
+ <font color="darkred">&lt;include ref="ant/ant-unit"/&gt;</font>
+ &lt;/test&gt;
+ &lt;/dependencies&gt;
+ &lt;filters&gt;
+ &lt;filter token="MESSAGE" value="${message}"/&gt;
+ &lt;/filters&gt;
+ &lt;dependencies&gt;
+
+ &lt;/project&gt;
+
+&lt;/index&gt;
+</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>
+&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
+&lt;index xmlns="link:xsd:dpml/lang/dpml-module#1.0"&gt;
+
+ &lt;project name="demo" basedir="."&gt;
+ &lt;properties&gt;
+ &lt;property name="location" value="New York"/&gt;
+ &lt;property name="message" value="Hello from ${user.name} in
${location}"/&gt;
+ &lt;/properties&gt;
+ &lt;types&gt;
+ &lt;type id="jar" alias="true"/&gt;
+ &lt;/types&gt;
+ <font color="darkred">&lt;dependencies&gt;
+ &lt;test&gt;
+ &lt;include uri="artifact:jar:ant/ant-junit#1.6.5"/&gt;
+ &lt;include uri="artifact:jar:ant/ant#1.6.5"/&gt;
+ &lt;include uri="artifact:jar:junit/junit#3.8.1"/&gt;
+ &lt;/test&gt;
+ &lt;/dependencies&gt;</font>
+ &lt;filters&gt;
+ &lt;filter token="MESSAGE" value="${message}"/&gt;
+ &lt;/filters&gt;
+ &lt;dependencies&gt;
+
+ &lt;/project&gt;
+
+&lt;/index&gt;
+</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.

Top of Page