Installation

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 Subversion or from the nightly builds. However, you will need to install Ant, an excellent Java-based build tool. Ant is also a Jakarta project, and can be found here.

The directory tree of the distribution looks like :

jakarta-velocity /build - contains build scripts /bin - where the built jars / classes will go /src - source 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

Building

To make building Velocity easy and consistant, we require a Jakarta project called Ant 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.

In each case below, it is assumed that you were successful in getting the distribution from Subversion 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'.

Change to the build directory (cd build). Then, to build the jar file, simply type:

ant

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.

Note that to build any of the specific build targets simply add the target name to the command line. For example, to build the Javadoc API documentation :

ant javadocs

Some of the most useful targets are:

  • jar builds the complete Velocity jar in the bin directory. This jar will be called 'velocity-X.jar', where 'X' is the current version number. This jar does not include necessary dependencies for Velocity. If you use this target, you must get the Collections component jar from Jakarta Commons and add to your CLASSPATH (or WEB-INF/lib). If you wish to use the built-in logging or template conversion, you must include the appropriate jars in your CLASSPATH or webapp's WEB-INF/lib. For convenience, you can use the jar-dep target to build a jar with ORO, Logkit and Commons Collections included.
  • jar-dep builds the complete Velocity jar in the bin directory, including necessary support for logging from the Jakarta Avalon Logkit package, critical configuration support from the Jakarta Commons and the necesary support for WebMacro template conversion using the Jakarta ORO package.
  • jar-core builds a slimmer Velocity jar in the bin directory, called 'velocity-core-X.jar'. This jar contains the core Velocity functionality, and doesn't include example and utility things like Anakia, Texen or the VelocityServlet support baseclass. It has the same external dependency requirements as the regular jar target.
  • jar-util builds a utility Velocity jar in the bin directory, called 'velocity-util-X.jar'. This jar contains utility code, specifically Anakia, Texen, and the WebMacro template conversion utility. It has the same external dependency requirements as the regular jar target.
  • jar-J2EE builds a complete jar, like the 'jar' target, that includes any components that require J2EE support. Currently, this includes only org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader. As usual, it is placed in the bin directory, called 'velocity-j2ee-X.jar'. NOTE : if you wish to use this build target, you must place (or link) a copy of j2ee.jar into the build/lib directory. We do not provide it as part of the distribution. A good source is http://java.sun.com/. It has the same external dependency requirements as the regular jar target.
  • jar-J2EE-dep build a complete jar with J2EE support and includes logging support from the Jakarta Avalon Logkit and regexp support fromt the Jakarta ORO package. See the notes on the jar-dep target, above.
  • examples builds the example code in the example programs found in the examples directory. This build target will also build the forumdemo example project.
  • docs builds these docs in the docs directory using Velocity's Anakia XML transformation tool. Allowing you to use Velocity templates in place of stylesheets - give it a try!
  • jar-src bundles all the Velocity source code into a single jar, placed in the bin directory.
  • javadocs builds the Javadoc class documentation in the docs/api directory
  • test (after jar) will test Velocity against it's testbed suite of test routines
  • help lists the build targets that are available.

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 Subversion at the time of the nightly snapshot isn't complete) or refresh from Subversion (you might have gotten a Subversion 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.

Testing Your Installation

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 :

ant test

If all is well, you should see output similar to :

junittest: [junit] Running org.apache.velocity.util.TestSimplePool [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.025 sec test: test-template: [echo] Running Template tests... [java] Adding TemplateTestCase : arithmetic ... ... ... [java] Adding TemplateTestCase : foreach-introspect [java] Adding TemplateTestCase : settest [java] ....................................... [java] Time: 1.999 [java] OK (39 tests) test-velocityapp: [echo] Running app.Velocity tests... [java] . [java] Time: 0.004 [java] OK (1 tests) ... BUILD SUCCESSFUL Total time: 42 seconds

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.