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 :
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 cd
build
). Then, to build the jar file, simply type:
Executing this script will create a
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 :
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.
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
If all is well, you should see output similar to :
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.