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>
