avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mcconn...@apache.org
Subject svn commit: rev 21637 - in avalon/trunk/central/site/src/xdocs/central/tools: . magic magic/spells magic/templates
Date Thu, 24 Jun 2004 15:04:16 GMT
Author: mcconnell
Date: Thu Jun 24 08:04:15 2004
New Revision: 21637

Modified:
   avalon/trunk/central/site/src/xdocs/central/tools/index.xml
   avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml
   avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/advanced-magic.xml
   avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/index-creation.xml
   avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/my-first-spell.xml
   avalon/trunk/central/site/src/xdocs/central/tools/magic/templates/standard.xml
Log:
Updates to magic docs to include class, customized, and reactor based build examples.

Modified: avalon/trunk/central/site/src/xdocs/central/tools/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/index.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/index.xml	Thu Jun 24 08:04:15 2004
@@ -10,17 +10,17 @@
     <section name="Tools">
 
       <p>
-      The Avalon project represents over 60 versioned artifacts
+      The Avalon project represents over 70 versioned artifacts
       with many build, test and runtime interdependencies.  Across 
       this codebase with have a single container application, a 
       Eclipse plugin, a number of plugable platform facilities, 
-      plugins that load plugins, etc. resulting in a general 
+      plugins that load plugins, etc. resulting in a generally 
       complex build cycle.  Following experiments with Ant and 
       Maven, the Avalon team extended the concept of a POM (Project
       Object Model) with centralized version and dependency
       management - and combined this model with the Ant platform
-      to provide a powerful, fast and robust build system code-named
-      <a href="magic/index.html">Magic</a>.
+      to provide a powerful, fast and robust build system 
+      code-named <a href="magic/index.html">Magic</a>.
       </p>
 
       <p>

Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/index.xml	Thu Jun 24 08:04:15
2004
@@ -11,8 +11,7 @@
 
       <p class="caption">
         <i>"any sufficiently advanced technology is 
-        indistinguishable from magic"</i><br/>
-        Sir Arthur C Clarke.
+        indistinguishable from magic"</i> - Sir Arthur C Clarke.
       </p>
 
       <p>

Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/advanced-magic.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/advanced-magic.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/advanced-magic.xml	Thu
Jun 24 08:04:15 2004
@@ -10,7 +10,7 @@
     <section name="Advanced Magic">
 
       <p>IN PREPARATION</p>
-      <p>TAILORING BUILD FILES &amp; CREATING CUSTOM PLUGINS</p>
+      <p>CREATING CUSTOM PLUGINS</p>
 
     </section>
   </body>

Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/index-creation.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/index-creation.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/index-creation.xml	Thu
Jun 24 08:04:15 2004
@@ -15,8 +15,9 @@
       a minimal index file containing two projects. The 
       example is available under your merlin installation main
       repository (sub-directory avalon/tools/demos) or alternatively
-      from <code><a href="http://www.dpml.net/avalon/tools/demos/demo.zip">
-      ${magic.home}/main/avalon/tools/demos/demo.zip</a></code>.
+      just download 
+      <code><a href="http://www.dpml.net/avalon/tools/demos/demo.zip">
+      demo.zip</a></code>.
       </p>
 
       <p><i>index.xml</i></p>
@@ -46,8 +47,72 @@
 </system>
  ]]></source>
 
-    </section>
+      <p>
+      The index file show above contains two product defintions - 
+      one for gizmo and one for widget.  The basedir attributes tells
+      magic where to find these projects relative to the location of the
+      index.  
+      </p>
+
+      <p>
+      The following is the build file using for the gizmo project.  
+      </p>
+
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<project name="gizmo" default="install" basedir="." 
+    xmlns:x="antlib:org.apache.avalon.tools">
+
+  <x:home index=".."/>
+  <import file="${magic.templates}/standard.xml"/>
+
+</project>]]></source>
+
+      <p>
+      Some important things to note in the above build file:  
+      </p>
+      <ul>
+        <li>
+          the ant project name <code>gizmo</code> is used as 
+          the default key to an entry in the index file (you 
+          can provide an alternative key by declaring the 
+          property ${project.name} before the home declaration)</li>
+        <li>
+          The <code>xmlns:x="antlib:org.apache.avalon.tools"</code> 
+          declaration tells ant that we are using "x" as the short name 
+          for the antlib <code>antlib:org.apache.avalon.tools</code>.</li>
+        <li>
+          The default target "install" is a target declared in the 
+          imported buildfile <code>${magic.templates}/standard.xml</code>.</li>
+        <li>
+          The <code><![CDATA[<x:home index=".."/>]]></code> triggers
+          the loading of the index file located in the parent directory
+          and from this the construction of the project model that contains
+          version information, dependencies, etc.</li>
+        <li>
+          The <code><![CDATA[<import file="${magic.templates}/standard.xml"/>]]></code>

+          tells ant to import a template build file from the ${magic.templates}
+          directory.  The ${magic.templates} directory defaults to 
+          ${magic.home}/templates. The ${magic.home} property defaults to the 
+          value of the environment variable MAGIC_HOME (if defined) otherwise
+          it will return <code>${user.home}/.magic</code></li>
+        <li>
+          The file <code>${magic.templates}/standard.xml</code> contains several
+          <a href="../templates/standard.html">standard build targets</a>.  
+        </li>
+      </ul>
+
+      <p>
+      You should have a general idea of the structure of an index based on 
+      the information described above.  While there are several notions we have not
+      discussed yet (external resources, plugins defintions, index importing, 
+      etc.) we will move on to actually building widget and gizmo - described 
+      under the next subject - <a href="my-first-spell.html">My First Spell</a>.
 
+      </p>
+
+    </section>
   </body>
-
+
 </document>
 

Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/my-first-spell.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/my-first-spell.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/spells/my-first-spell.xml	Thu
Jun 24 08:04:15 2004
@@ -14,10 +14,128 @@
       an index and two sub-directories - one for the <code>widget</code> project
       and another for the <code>gizmo</code> project.
       </p>
+
+      <subsection name="Classic Builds">
+
+      <p>
+      The following command invokes a classic build using magic's standard
+      template.
+      </p>
+
+<source>
+$ cd demo/gizmo
+$ ant
+</source>
+
+<pre>
+$ ant
+Buildfile: build.xml
+
+info:
+------------------------------------------------------------------------
+name: gizmo
+------------------------------------------------------------------------
+
+init:
+
+prepare:
+[x:prepare] creating target directory
+    [mkdir] Created dir: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target
+    [mkdir] Created dir: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\build\main
+     [copy] Copying 1 file to F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\build\main
+    [mkdir] Created dir: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\build\test
+     [copy] Copying 1 file to F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\build\test
+
+build:
+    [mkdir] Created dir: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\classes
+    [javac] Compiling 1 source file to F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\classes
+
+package:
+    [mkdir] Created dir: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\deliverables\jars
+      [jar] Building jar: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\deliverables\jars\gizmo.jar
+    [x:jar] Creating md5 checksum
+
+test:
+    [mkdir] Created dir: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\test\classes
+    [javac] Compiling 1 source file to F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\test\classes
+    [mkdir] Created dir: F:\dev\avalon\tools\magic\etc\test\demo\gizmo\target\test\reports
+    [junit] Running org.apache.playground.gizmo.test.GizmoTestCase
+    [junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.078 sec
+
+
+install:
+     [copy] Copying 2 files to F:\system\magic\main\demo
+
+BUILD SUCCESSFUL
+Total time: 8 seconds
+</pre>
+
+      </subsection>
+
+      <subsection name="Customizing a build">
+
+      <p>
+      Ant provides a framework for the customization of a build by overriding
+      and/or delegating to a imported template.  Using magic's standard targets
+      as the framework you can easily add custom ant content to you build file.
+      The following xml demonstrates the customization of the gizmo build.xml
+      file to include some project specific ant content.
+      </p>
+
+<source><![CDATA[
+  <import file="${magic.templates}/standard.xml"/>
+
+  <target name="build" depends="standard.build">
+    <echo>
+Hi! This is classic ant.  I'm being invoked after the 
+standard.xml build target has been completed.
+    </echo>
+  </target>]]></source>
+
+<pre>
+$ ant
+Buildfile: build.xml
+
+info:
+------------------------------------------------------------------------
+name: gizmo
+------------------------------------------------------------------------
+
+init:
+
+prepare:
+
+standard.build:
+
+build:
+     [echo]
+     [echo] Hi! This is classic ant.  I'm being invoked after the 
+     [echo] standard.xml build target has been completed.
+     [echo]
+
+package:
+
+test:
+    [junit] Running org.apache.playground.gizmo.test.GizmoTestCase
+    [junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.078 sec
+
+
+install:
+
+BUILD SUCCESSFUL
+Total time: 6 seconds
+</pre>
+
+      </subsection>
+
+      <subsection name="Reactor Builds">
+
       <p>
       The following command invokes a reactor build that initates 
       the build of all registered projects with a basedir within
-      the scope of the current directory (i.e. widget and gizmo).
+      the scope of the current directory (i.e. widget and gizmo) relative to
+      the demo directory.  Magic will ensure that the project are built in 
+      the correct order taking into account respective project dependencies.
       </p>
 
 <source>
@@ -110,8 +228,19 @@
 Total time: 14 seconds
 </pre>
 
+      </subsection>
+
+      <subsection name="Advanced Magic ...">
+
+      <p>
+      The <a href="advanced-magic.html">next section</a> deals with build 
+      customization using magic plugins.
+      </p>
+
+      </subsection>
 
-    </section>
+    </section>
+
   </body>
 
 </document>

Modified: avalon/trunk/central/site/src/xdocs/central/tools/magic/templates/standard.xml
==============================================================================
--- avalon/trunk/central/site/src/xdocs/central/tools/magic/templates/standard.xml	(original)
+++ avalon/trunk/central/site/src/xdocs/central/tools/magic/templates/standard.xml	Thu Jun
24 08:04:15 2004
@@ -10,57 +10,68 @@
 
     <section name="Standard Project Template">
 
-<source><![CDATA[
-<?xml version="1.0" encoding="UTF-8" ?>
-<project name="standard" xmlns:x="antlib:org.apache.avalon.tools">
+      <p>
+      The <code>standard.xml</code> template provides a set of 
+      common build targets backed by magic tasks that automate the 
+      resolution of working directories, classpaths for source
+      and test compilation, naming of produced artifacts such as 
+      jar files, artifact publication, and a number of content 
+      generation tasks including javadoc and xdoc management.
+      </p>
 
-  <x:home/>
+<source>
 
-  <target name="info">
-    <x:info/>
-  </target>
+&lt;-- standard.xml --&gt;
 
-  <target name="init" depends="info">
-    <x:init/>
-  </target>
+&lt;project name="standard" xmlns:x="antlib:org.apache.avalon.tools"&gt;
 
-  <target name="clean" depends="info">
-    <x:clean/>
-  </target>
+  <a href="../tasks/common/home.html">&lt;x:home/&gt;</a>
 
-  <target name="prepare" depends="init">
-    <x:prepare/>
-  </target>
+  &lt;target name="info"&gt;
+    <a href="../tasks/common/info.html">&lt;x:info/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="build" depends="prepare">
-    <x:javac/>
-  </target>
+  &lt;target name="init" depends="info"&gt;
+    <a href="../tasks/management/init.html">&lt;x:init/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="package" depends="build">
-    <x:jar/>
-  </target>
+  &lt;target name="clean" depends="info"&gt;
+    <a href="../tasks/common/clean.html">&lt;x:clean/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="test" depends="package">
-    <x:junit/>
-  </target>
+  &lt;target name="prepare" depends="init"&gt;
+    <a href="../tasks/common/prepare.html">&lt;x:prepare/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="install" depends="test">
-    <x:install/>
-  </target>
+  &lt;target name="build" depends="prepare"&gt;
+    <a href="../tasks/production/javac.html">&lt;x:javac/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="javadoc" depends="prepare">
-    <x:javadoc/>
-  </target>
+  &lt;target name="package" depends="build"&gt;
+    <a href="../tasks/production/jar.html">&lt;x:jar/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="xdoc" depends="prepare">
-    <x:xdoc theme="modern"/>
-  </target>
+  &lt;target name="test" depends="package"&gt;
+    <a href="../tasks/production/junit.html">&lt;x:junit/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="site" depends="javadoc,xdoc"/>
+  &lt;target name="install" depends="test"&gt;
+    <a href="../tasks/production/install.html">&lt;x:install/&gt;</a>
+  &lt;/target&gt;
 
-  <target name="dist" depends="install,site"/>
+  &lt;target name="javadoc" depends="prepare"&gt;
+    <a href="../tasks/publication/javadoc.html">&lt;x:javadoc/&gt;</a>
+  &lt;/target&gt;
+
+  &lt;target name="xdoc" depends="prepare"&gt;
+    <a href="../tasks/publication/xdoc.html">&lt;x:xdoc theme="modern"/&gt;</a>
+  &lt;/target&gt;
+
+  &lt;target name="site" depends="javadoc,xdoc"/&gt;
+
+  &lt;target name="dist" depends="install,site"/&gt;
   
-</project>]]></source>
+&lt;/project&gt;</source>
 
     </section>
 

---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message