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

Required Tools

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

Note that there is an experimental Maven build included with the distribution, but Ant remains the recommended method.

Velocity requires JDK 1.4 or greater to compile. It's possible to use JDK 1.3 to compile but several useful features will not be included. Velocity requires a minimum of JDK 1.3 to run.

Finally, if you wish to modify Velocity's grammar you will need to a tool called JavaCC. We recommend version 3.2 or greater (for compatibility with JDK 1.5 syntax changes).

Jar Dependencies

Velocity requires various third party jar files for compiling and for running. Not all jar files are required in all cases. When building, all dependencies will be downloaded automatically unless the skip.jar.loading property is set.

Jar Purpose Required at Runtime?
antlr-2.7.5.jar XML parsing (XPath queries in particular) Only for Anakia
avalon-logkit-2.1.jar Possible means of logging No
commons-collection-3.1.jar Used in parsing configuration Yes
commons-lang-2.1.jar Various String utility functions Yes
jdom-1.0.jar XML parsing Only for Anakia
log4j.1.2.8.jar Possible means of logging No
oro-2.0.8.jar For regular expression parsing in tests and event handlers Only for reference escaping event handlers
servletapi-2.3.jar For the deprecated VelocityServlet Only for VelocityServlet
werken-xpath-0.9.4.jar XML parsing Only for Anakia
junit-3.8.1.jar For running unit tests No

Note that you can always create a jar with all required run-time dependencies by running the task jar-dep.

Building

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 put the required dependent jars in your CLASSPATH (or WEB-INF/lib). For convenience, you can use the jar-dep target to build a jar with all required dependent classes included.
  • jar-dep builds the complete Velocity jar in the bin directory.
  • clean deletes all generated classes, jars, documentation, and other files.
  • docs builds these docs in the docs directory using Velocity's Anakia XML transformation tool. Allows you to use Velocity templates in place of stylesheets - give it a try!
  • examples builds the example code in the example programs found in the examples directory.
  • 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
  • package will generate the complete Velocity distribution package.
  • parser will compile the JavaCC parser files from src/Parser.jjt into the appropriate Java source files. Requires JavaCC 3.2+ to be installed, and the property javacc.home to contain a path to the installed JavaCC directory.
  • test (after jar) will test Velocity against its testbed suite of test routines.

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.

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.