<?xml version="1.0"?>

<!--
   Copyright 2000-2004 The Apache Software Foundation

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->


<document>

 <properties>
  <title>Velocity Installation</title>
  <author email="jvanzyl@zenplex.com">Velocity Documentation Team</author>
 </properties>

<body>

<section name="Installation">

<p>
Velocity runs on a variety of platforms that have installed the Java 2
Virtual Machine. The J2SDK is required for users who want to compile
Velocity from its source code.
</p>

<p>
Everything required to build Velocity comes with the distribution, which
can be 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>.  However, you will need to install Ant, an excellent
Java-based build tool.  Ant is also a Jakarta project, and can be
found <a href="http://jakarta.apache.org/ant/">here</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/api     - 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="Building">

<p>
To make building Velocity easy and consistant, we require a Jakarta project
called <a href="http://jakarta.apache.org/ant/">Ant</a> version 1.3 or
higher to perform the build process. We assume that you have followed
Ant's installation instructions and have it properly installed.  It's not
difficult, and I think that you will find it an excellent addition to
your programmer's toolbox.
</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>
Change to the <filename>build</filename> directory (<code>cd
build</code>). Then, to build the jar file, simply type:
</p>

<source><![CDATA[
ant
]]></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-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>
Note that to build any of the specific build targets, as detailed in
the <a href="developer-guide.html">developers guide</a>, simply add
the target name to the command line.  For example, to build the Javadoc
API documentation :
</p>

<source><![CDATA[
ant javadocs
]]></source>

<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 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>
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[
ant 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>
</document>
