WHY_TWO_JARS.txt

WHY ARE THERE TWO JARS?  WHAT'S THE DIFFERENCE?
===============================================

We are including two jars with the Velocity distribution. This
document describes the differences and what they are intended for.

Both jars are included in the root directory of the Velocity
distribution.

CAVEAT: Up and including the 1.4 release of Velocity, there was a
wealth of different jars including J2EE code, containing just the
runtime or the tools. This lead to some confusion about the naming and
the purpose of the various jars.

Starting with the 1.5 release of Velocity, there is now one jar,
velocity-<version>.jar, which contains all Velocity code and a second
jar, velocity-dep-<version>.jar, which contains all Velocity code and
its external dependencies. 


velocity-<version>.jar
----------------------

  This jar contains only the velocity specific code in the
  org.apache.velocity.* packages. 

  If you want to integrate Velocity in your own code or a larger
  project, we recommend that you use this jar.

  It has some external dependencies which are listed in the developer
  docs. Make sure that you have these dependencies present in your
  application.

  Please see the developers guide for more information.


velocity-dep-<version>.jar
--------------------------

  This jar is intended to be used when you do standalone development
  with Velocity. It contains all of the Velocity engine code (runtime,
  anakia, texen and their respective ant tasks) and also all external
  dependencies from other jars, repackaged into a single jar. Currently
  that is:

  oro           org.apache.oro.* packages,
                from http://jakarta.apache.org/oro/

  commons-lang  org.apache.commons.lang.* packages,
                from http://jakarta.apache.org/commons/lang/

  Avalon Logkit org.apache.log.* packages

  and a subset of

  commons-collections org.apache.commons.collections.* packages
                      from http://jakarta.apache.org/commons/collections/

  These classes are strictly intended for Velocity use! If you want to use
  the velocity-dep jar, do not rely on any of the other classes being present.
  We reserve the right to change the supporting classes (those not in the
  org.apache.velocity.* packages) at any time for any release.

  When using this jar without anything else, you are also restricted to
  using the Avalon Logkit for logging (or JDK 1.4 logging if you run under
  JDK 1.4 or newer).

  This jar should only be used for the Velocity runtime. The various tools
  (Anakia, Texen, Webmacro converter) have additional dependencies that are
  not inside this jar!