geirm 01/02/28 22:01:13
Modified: docs install.html
Log:
follows the xml
Revision Changes Path
1.16 +162 -15 jakarta-velocity/docs/install.html
Index: install.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/install.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- install.html 2001/02/26 06:38:52 1.15
+++ install.html 2001/03/01 06:01:12 1.16
@@ -37,7 +37,7 @@
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td valign="top" nowrap="true">
- <strong>About</strong>
+ <p><strong>About</strong></p>
<ul>
<li> <a href="./index.html">Overview</a>
</li>
@@ -56,7 +56,7 @@
<li> <a href="./todo.html">TODO</a>
</li>
</ul>
- <strong>Guides</strong>
+ <p><strong>Guides</strong></p>
<ul>
<li> <a href="./user-guide.html">User's Guide</a>
</li>
@@ -67,7 +67,7 @@
<li> <a href="./differences.html">VM/WM Differences</a>
</li>
</ul>
- <strong>Tools</strong>
+ <p><strong>Tools</strong></p>
<ul>
<li> <a href="./anakia.html">Anakia</a>
</li>
@@ -96,21 +96,68 @@
obtained from <a href="http://jakarta.apache.org/getinvolved/cvsindex.html">CVS</a>
or from the <a
href="http://jakarta.apache.org/builds/jakarta-velocity/nightly/">nightly builds</a>.
</p>
+ <p>
+The directory tree of the distribution looks like :
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+jakarta-velocity
+ /build - contains build scripts
+ /bin - where the built jars / classes will go
+ /src - sourcecode for Velocity, Anakia, and Texen
+ /docs - documentation in HTML form
+ /docs/apidocs - Javadocs for Velocity source
+ /examples - example/demonstration code
+ /convert - tools to help convert WebMacro templates
+ /test - test programs and templates
+ /xdocs - source for our documentation
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <strong>Compiling</strong>
+ <strong>Building</strong>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
-On Unix, <code>cd</code> to the <filename>velocity/build</filename> directory
-and execute the following script:
+To make building Velocity easy and consistant, we have provided scripts to build
+Velocity for both Unix and Windows. We use a Jakarta project called
+<a href="http://jakarta.apache.org/ant/">Ant</a> to perform
+the build process and provide Ant with the distribution, so no
+external build utilities are required.
+</p>
+ <p>
+In each case below, it is assumed that you were successful in getting the
distribution from CVS
+or as a nightly build, and with the latter, were successful in unpacking. Also, it
is assumed that
+you are starting in the 'jakarta-velocity' directory, the root of the distribution
tree. All directory
+references will be relative to 'jakarta-velocity'.
</p>
+ <p>
+On Unix, change to the <filename>build</filename> directory (<code>cd
build</code>). Then, build the Velocity jar via the build-velocity.sh script :
+</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
@@ -133,21 +180,49 @@
</table>
</div>
<p>
-On Windows, executing <code>build-velocity.bat</code>, found in the <filename>
-velocity\build</filename> directory, will have the same effect.
+On Windows, change to the <filename>build</filename> directory (<code>cd
build</code>). Then, build the Velocity jar via the build-velocity.bat script :
</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+build-velocity.bat
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
<p>
Executing this script will create a <filename>bin</filename> directory within
the Velocity distribution directory. The <filename>bin</filename> directory will
contain the compiled class files (inside a <filename>classes</filename>
-directory) as well as a <filename>velocity.jar</filename> file. Be sure to
+directory) as well as a <filename>velocity-XX.jar</filename> file,
+where XX is the current version number. Be sure to
update your classpath to include Velocity's <filename>.jar</filename> file.
</p>
+ <p>
+Velocity should build 'out of the box', independent of your classpath.
+If you get an error building Velocity, try a different nightly build (as sometimes
+we make a mistake and the CVS at the time of the nightly snapshot isn't complete)
+or refresh from CVS (you might have gotten a CVS snapshot while a developer was
+checking things in.)
+</p>
<p>
-If you get a compiler error related to one or more packages that could not
-be found, ensure the <filename>build-velocity</filename> script you are using is
-edited to properly specify the paths to each of the packages that could not be
-found.
+If the problems persist, do not hesitate to ask the Velocity community via our mail
+lists. They can be found <a
href="http://jakarta.apache.org/site/mail.html">here</a>.
+Please read and understand the the guidelines for participating in any Jakarta mail
+list.
</p>
</blockquote>
</td></tr>
@@ -161,8 +236,80 @@
<tr><td>
<blockquote>
<p>
-There are testing scripts in the <filename>velocity/examples</filename>
-directory.
+The Velocity developers use an automated test facility, and it is included in the
+distribution. You can use it to make sure that all is well with your build of
Velocity.
+</p>
+ <p>
+To run the test suite, simply use the build target <filename>test</filename> when
you build :
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+Unix : ./build-velocity.sh test
+
+Windows : build-velocity.bat test
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+If all is well, you should see output like :
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+test:
+Running JUnit template tests for Velocity ...
+Adding TemplateTestCase : arithmetic
+Adding TemplateTestCase : array
+Adding TemplateTestCase : block
+ .
+ .
+ .
+Adding TemplateTestCase : math
+Adding TemplateTestCase : range
+Adding TemplateTestCase : get
+Adding TemplateTestCase : velocimacro2
+Adding TemplateTestCase : foreach-type
+Adding ContextSafetyTestCase.
+......................................
+Time: 2.553
+
+OK (38 tests)
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+Note that the number of tests may vary from those shown above, but if you see 'OK'
+after the tests are run, all is well. Now it's time to use Velocity.
</p>
</blockquote>
</td></tr>
