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.

Everything required to build Velocity comes with the distribution, which can be obtained from CVS or from the nightly builds.

The directory tree of the distribution looks like :

	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

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 Ant to perform the build process and provide Ant with the distribution, so no external build utilities are required.

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'.

On Unix, change to the build directory (cd build). Then, build the Velocity jar via the build.sh script :

	./build.sh

On Windows, change to the build directory (cd build). Then, build the Velocity jar via the build.bat script :

	build.bat

Executing this script will create a bin directory within the Velocity distribution directory. The bin directory will contain the compiled class files (inside a classes directory) as well as a velocity-XX.jar file, where XX is the current version number. Be sure to update your classpath to include Velocity's .jar file.

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.)

If the problems persist, do not hesitate to ask the Velocity community via our mail lists. They can be found here. Please read and understand the the guidelines for participating in any Jakarta mail list.

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.

To run the test suite, simply use the build target test when you build :

	Unix : ./build.sh test Windows : build.bat test

If all is well, you should see output like :

	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)

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.