You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by ge...@apache.org on 2001/03/01 07:00:53 UTC
cvs commit: jakarta-velocity/xdocs install.xml
geirm 01/02/28 22:00:53
Modified: xdocs install.xml
Log:
Expanded and added more on building and testing.
Revision Changes Path
1.12 +94 -12 jakarta-velocity/xdocs/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/install.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- install.xml 2001/02/26 06:38:54 1.11
+++ install.xml 2001/03/01 06:00:52 1.12
@@ -23,48 +23,130 @@
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>
+
+<source><![CDATA[
+
+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
+
+]]></source>
+
</section>
-<section name="Compiling">
+<section name="Building">
<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>
+
<source><![CDATA[
./build-velocity.sh
]]></source>
<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>
+<source><![CDATA[
+build-velocity.bat
+]]></source>
+
<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>
-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.
+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 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>
</section>
<section name="Testing Your Installation">
<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>
+<source><![CDATA[
+Unix : ./build-velocity.sh test
+
+Windows : build-velocity.bat test
+]]></source>
+
+<p>
+If all is well, you should see output like :
+</p>
+<source><![CDATA[
+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)
+
+]]></source>
+
+<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>
</section>
</body>