<?xml version="1.0" encoding="UTF-8" ?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.    
-->

<document>
  <properties>
    <title>Velocity dependencies</title>
    <author email="dev@velocity.apache.org">Velocity Documentation Team</author>
  </properties>

  <body>
    <section name="Velocity dependencies" href="dependencies">
      <p>
       Velocity has a number of external jar dependencies. However, not all of these
       are needed every time. This document should help you do decide which jars must
       also be present if you want to integrate Velocity into your application.
      </p>

      <p>
       All of these jars must be present when building Apache Velocity. The build process
       downloads all of them automatically from the Internet.
      </p>

      <table>
        <tr>
          <th>jar name</th><th>Required</th><th>Explanation</th>
        </tr>
        <tr>
          <td>commons-collections</td><td>Yes</td>
          <td>Needed for all parts of Velocity</td>
        </tr>
        <tr>
          <td>commons-lang</td><td>Yes</td>
          <td>Needed for all parts of Velocity</td>
        </tr>
        <tr>
          <td>commons-logging</td><td>No</td>
          <td>Must be present if log system is configured to use
              <a href="apidocs/org/apache/velocity/runtime/log/CommonsLogLogChute.html">CommonsLogLogChute</a>.
              Otherwise, it is not needed.
          </td>
        </tr>
        <tr>
          <td>oro</td><td>Yes</td>
          <td>Must be present if you have Velocity configured to
              <a href="developer-guide.html#Configuring_Event_Handlers">automatically escape references</a>.
              Otherwise, it is not needed.
          </td>
        </tr>
        <tr>
          <td>log4j</td><td>No</td>
          <td>Must be present if log4j Logging has been selected.
              Not needed if any other logging style has been selected.</td>
        </tr>
        <tr>
          <td>logkit (or avalon-logkit)</td><td>No</td>
          <td>Must be present if Avalon Logging has been selected.
              Not needed if any other logging style has been selected.</td>
        </tr>
        <tr>
          <td>servletapi</td><td>No</td>
          <td>Only needed when the <a
              href="apidocs/org/apache/velocity/servlet/VelocityServlet.html">VelocityServlet</a>
              or <a href="apidocs/org/apache/velocity/runtime/log/ServletLogChute.html">ServletLogChute</a> are used.
              Should normally be supplied by the servlet container.
              <b>VelocityServlet is deprecated and should
              be replaced with VelocityViewServlet from the
              <a href="http://velocity.apache.org/tools/devel/">velocity-tools</a> distribution.</b></td>
        </tr>
        <tr>
          <td>jdom</td><td>No</td>
          <td>Only required for the deprecated Anakia tool / ant task</td>
        </tr>
        <tr>
          <td>werken-xpath</td><td>No</td>
          <td>Only required for the deprecated Anakia tool / ant task</td>
        </tr>
        <tr>
          <td>antlr</td><td>No</td>
          <td>Only required for the deprecated Anakia tool / ant task</td>
        </tr>
        <tr>
          <td>ant</td><td>No</td>
          <td>Only needed for compilation.</td>
        </tr>
        <tr>
          <td>junit</td><td>No</td>
          <td>Only needed for running the tests during compilation.</td>
        </tr>
        <tr>
          <td>hsqldb</td><td>No</td>
          <td>Only needed for running the tests during compilation.</td>
        </tr>
      </table>

      <p>
        The most common case is the integration of the Velocity runtime into your
        application. In this case, you must add commons-collections and commons-lang
        to your application (and optional Oro or commons-logging if
        required). If you already have one or more of these libraries in your application,
        you should check if you need to update their versions.
      </p>

      <p>The <a href="dependencies.html">auto-generated dependency report</a> lists all mandatory
         dependencies as <b>compile</b> and all optional dependencies as <b>provided</b>, though
         it fails to properly reflect the optional nature of the Oro and Commons-Logging dependencies.
      </p>
    </section>
  </body>
</document>
