| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <html>
|
| <head>
|
| <title>Apache Velocity - Building Velocity from Source</title>
|
| <style type="text/css" media="all">
|
| @import url("./css/maven-base.css");
|
| @import url("./css/maven-theme.css");
|
| @import url("./css/site.css");
|
| </style>
|
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
|
| <link rel="alternate" href="http://feeds.feedburner.com/ApacheVelocitySiteNews" type="application/rss+xml" title="Apache Velocity - Building Velocity from Source News" />
|
| <meta name="author" content="Velocity Documentation Team" />
|
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
| </head>
|
| <body class="composite">
|
| <div id="banner">
|
| <a href="../../../" id="bannerLeft">
|
|
|
| <img src="images/velocity_project_wide.png" alt="" />
|
|
|
| </a>
|
| <span id="bannerRight">
|
|
|
| <img src="images/velocity-logo.png" alt="" />
|
|
|
| </span>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| <div id="breadcrumbs">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <div class="xleft">
|
|
|
| <a href="http://www.apache.org/">Apache</a>
|
| >
|
|
|
| <a href="../../../">Velocity</a>
|
| >
|
|
|
| Velocity Engine
|
| </div>
|
| <div class="xright"> <a href="../../devel/">Engine</a>
|
| |
|
| <a href="../../../tools/devel/">Tools</a>
|
| |
|
| <a href="../../../anakia/devel/">Anakia</a>
|
| |
|
| <a href="../../../texen/devel/">Texen</a>
|
| |
|
| <a href="../../../docbook/">DocBook</a>
|
| |
|
| <a href="../../../dvsl/devel/">DVSL</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| <div id="leftColumn">
|
| <div id="navcolumn">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <h5>Velocity</h5>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="index.html">General</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="overview.html">Overview</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="getting-started.html">Getting Started</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="webapps.html">Web Applications</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="../../../download.cgi">Download</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/VelocityFAQ">FAQ (Wiki)</a>
|
| </li>
|
| </ul>
|
| <h5>Docs</h5>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="user-guide.html">User Guide</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="developer-guide.html">Developer Guide</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="vtl-reference-guide.html">VTL Reference</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="glossary.html">Glossary</a>
|
| </li>
|
| </ul>
|
| <h5>Developers</h5>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="license.html">License</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="apidocs/index.html">Javadoc</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="changes-report.html">Changes</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="jira-report.html">Resolved Issues</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="upgrading.html">Upgrading</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="jar-dependencies.html">Dependencies</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://svn.apache.org/viewvc/velocity/engine/trunk/">Source Code Repository</a>
|
| </li>
|
|
|
| <li class="none">
|
| <strong>Building from Source</strong>
|
| </li>
|
| </ul>
|
| <h5>Community</h5>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/">Wiki</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="../../../news.html">Recent News</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/PoweredByVelocity">Powered By Velocity</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/VelocityEditors">IDE/Editor Plugins</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/PublishedArticlesAndBooks">Articles and Books</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/GetInvolved">Get Involved</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="../../../contact.html">Mailing Lists</a>
|
| </li>
|
| </ul>
|
| <h5>Velocity Development</h5>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/RoadMap">Road Map</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/CodeStandards">Coding Standards</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="http://wiki.apache.org/velocity/DocumentationGuidelines">Documentation Guidelines</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="https://issues.apache.org/jira/browse/VELOCITY">Issues</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="../../../who-we-are.html">Who we are</a>
|
| </li>
|
| </ul>
|
| <h5>Translations</h5>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="http://www.jajakarta.org/velocity/">Site (Japanese)</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="translations/user-guide_fi.html">User's Guide (Finnish)</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="translations/user-guide_fr.html">User's Guide (French)</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="translations/user-guide_es.html">User's Guide (Spanish)</a>
|
| </li>
|
| </ul>
|
| <h5>Project Documentation</h5>
|
| <ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="collapsed">
|
| <a href="project-info.html">Project Information</a>
|
| </li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="collapsed">
|
| <a href="project-reports.html">Project Reports</a>
|
| </li>
|
| </ul>
|
|
|
|
|
|
|
| <a class="poweredBy" href="../../../" title="Apache Velocity" ><img class="poweredBy" alt="Apache Velocity" src="images/pbv90x30.png" /></a>
|
|
|
|
|
|
|
| <a class="poweredBy" href="../../../rss/news.rss" title="Velocity News Feed" ><img class="poweredBy" alt="Velocity News Feed" src="images/feed-icon-24x24.jpg" /></a>
|
|
|
| <iframe src="http://www.apache.org/ads/buttonbar.html"
|
| style="border-width:0; float: left" frameborder="0" scrolling="no"
|
| width="135"
|
| height="265" ></iframe>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| </div>
|
| </div>
|
| <div id="bodyColumn">
|
| <div id="contentBox">
|
| <div class="section"><h2><a name="Installation"></a>
|
| Installation</h2>
|
| <p> |
| 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. |
| </p>
|
| <p> |
| Everything required to build Velocity comes with the distribution, which |
| can be obtained from <a class="externalLink" href="http://www.apache.org/dev/version-control.html">Subversion</a>
|
| or |
| from the <a class="externalLink" href="http://vc.apache.org/snapshots/velocity/">nightly |
| snapshots</a>
|
| . However, you will need to install Ant to build the Velocity sources.</p>
|
| <p>Ant is also an Apache project, and can be |
| found <a class="externalLink" href="http://ant.apache.org/">here</a>
|
| . To build Apache Velocity, you need at least Version 1.6 of Apache Ant. |
| </p>
|
| <p> |
| The directory tree of the distribution looks like: |
| </p>
|
| <div class="source"><pre> |
| build/ This is where the build scripts live. |
| convert/ The WebMacro to Apache Velocity conversion program. |
| docs/ Velocity Documentation in HTML format. |
| docs/api/ Velocity Javadocs. |
| examples/ Examples how to use Velocity. |
| lib/ Dependencies for building and using Velocity. |
| lib/test/ Dependencies needed for the various unit tests. |
| src/ This is where all of the source code is located. |
| test/ Contains test files needed for the unit tests. |
| xdocs/ Here are the .xml files for building the .html files |
| related to the website and documentation. The files |
| located in docs/ have been built from these sources. |
| </pre>
|
| </div>
|
| </div>
|
| <div class="section"><h2><a name="Required_Tools"></a>
|
| Required Tools</h2>
|
| <p> |
| To make building Velocity easy and consistent, we require an Apache project |
| called <a class="externalLink" href="http://ant.apache.org/">Ant</a>
|
| 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. |
| </p>
|
| <p> |
| 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. |
| </p>
|
| <p> |
| Finally, if you wish to modify Velocity's grammar you will need to a tool |
| called <a class="externalLink" href="http://javacc.dev.java.net">JavaCC</a>
|
| . We recommend |
| version 3.2 or greater (for compatibility with JDK 1.5 syntax changes). |
| </p>
|
| </div>
|
| <div class="section"><h2><a name="Jar_Dependencies"></a>
|
| Jar Dependencies</h2>
|
| <p>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. You can |
| control the download with the <code>skip.jar.loading</code> and |
| <code>force.jar.loading</code> properties in the |
| <code>build.properties</code> file. |
| </p>
|
| <table class="bodyTable"><tr class="a"><th>Jar</th>
|
| <th>Purpose</th>
|
| <th>Required at Runtime?</th>
|
| </tr>
|
| <tr class="b"><td><code>antlr-2.7.5.jar</code></td>
|
| <td>XML parsing (XPath queries in particular)</td>
|
| <td>Only for Anakia</td>
|
| </tr>
|
| <tr class="a"><td><code>avalon-logkit-2.1.jar</code></td>
|
| <td>Possible means of logging</td>
|
| <td>No</td>
|
| </tr>
|
| <tr class="b"><td><code>commons-collection-3.1.jar</code></td>
|
| <td>Used in parsing configuration</td>
|
| <td>Yes</td>
|
| </tr>
|
| <tr class="a"><td><code>commons-lang-2.1.jar</code></td>
|
| <td>Various String utility functions</td>
|
| <td>Yes</td>
|
| </tr>
|
| <tr class="b"><td><code>commons-logging-1.1.jar</code></td>
|
| <td>To redirect log output to commons-logging</td>
|
| <td>Only for those using commons-logging</td>
|
| </tr>
|
| <tr class="a"><td><code>jdom-1.0.jar</code></td>
|
| <td>XML parsing</td>
|
| <td>Only for Anakia</td>
|
| </tr>
|
| <tr class="b"><td><code>log4j.1.2.12.jar</code></td>
|
| <td>Possible means of logging</td>
|
| <td>No</td>
|
| </tr>
|
| <tr class="a"><td><code>oro-2.0.8.jar</code></td>
|
| <td>For regular expression parsing in tests and event handlers</td>
|
| <td>Only for reference escaping event handlers</td>
|
| </tr>
|
| <tr class="b"><td><code>servletapi-2.3.jar</code></td>
|
| <td>For the deprecated VelocityServlet and redirecting log output to the servlet log.</td>
|
| <td>Only for VelocityServlet or ServletLogChute</td>
|
| </tr>
|
| <tr class="a"><td><code>werken-xpath-0.9.4.jar</code></td>
|
| <td>XML parsing</td>
|
| <td>Only for Anakia</td>
|
| </tr>
|
| <tr class="b"><td><code>junit-3.8.1.jar</code></td>
|
| <td>For running unit tests</td>
|
| <td>No</td>
|
| </tr>
|
| <tr class="a"><td><code>hsqldb-1.7.1.jar</code></td>
|
| <td>For running database related unit tests</td>
|
| <td>No</td>
|
| </tr>
|
| <tr class="b"><td><code>ant.jar</code></td>
|
| <td>Required for compilation. Provided by the ant build tool.</td>
|
| <td>No</td>
|
| </tr>
|
| </table>
|
| <p> |
| Note that you can always create a jar with all required run-time dependencies by executing the |
| <code>jar-dep</code> task. |
| </p>
|
| </div>
|
| <div class="section"><h2><a name="Building"></a>
|
| Building</h2>
|
| <p> |
| 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 'velocity' directory, the root of the distribution tree. |
| All directory references will be relative to 'velocity'. |
| </p>
|
| <p> |
| Change to the <b>build</b>
|
| directory (<code>cd |
| build</code>). Then, to build the jar file, simply type: |
| </p>
|
| <div class="source"><pre> |
| ant |
| </pre>
|
| </div>
|
| <p> |
| Executing this script will create a <b>bin</b>
|
| directory |
| within the Velocity distribution directory. The <b>bin</b>
|
| |
| directory will contain the compiled class files (inside a |
| <b>classes</b>
|
| directory) as well as a |
| <b>velocity-XX.jar</b>
|
| file, where XX is the current |
| version number. Be sure to update your classpath to include Velocity's |
| <b>.jar</b>
|
| file. |
| </p>
|
| <p> |
| 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: |
| </p>
|
| <div class="source"><pre> |
| ant javadocs |
| </pre>
|
| </div>
|
| <p>Some of the most useful targets are: |
| </p>
|
| <ul><li><b><code>jar</code></b>
|
| builds the complete Velocity jar in the |
| <code>bin</code> 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 <code>jar-dep</code> target to build |
| a jar with all required dependent classes included. |
| </li>
|
| <li><b><code>jar-dep</code></b>
|
| builds the complete Velocity jar in |
| the <code>bin</code> directory. |
| </li>
|
| <li><b><code>clean</code></b>
|
| deletes all generated classes, jars, documentation, and other files. |
| </li>
|
| <li><b><code>real-clean</code></b>
|
| like <code>clean</code> but also deletes all downloaded jars. |
| </li>
|
| <li><b><code>docs</code></b>
|
| builds these docs in the <code>docs</code> directory |
| using Velocity's <a href="anakia.html">Anakia</a>
|
| XML transformation tool. |
| Allows you to use |
| Velocity templates in place of stylesheets |
| - give it a try! |
| </li>
|
| <li><b><code>examples</code></b>
|
| builds the example code in the example programs |
| found in the <code>examples</code> directory. |
| </li>
|
| <li><b><code>jar-src</code></b>
|
| bundles all the Velocity source code into a single |
| jar, placed in the <code>bin</code> directory. |
| </li>
|
| <li><b><code>javadocs</code></b>
|
| builds the Javadoc class documentation in the |
| <code>docs/api</code> directory |
| </li>
|
| <li><b><code>package</code></b>
|
| will generate the complete Velocity distribution package. |
| </li>
|
| <li><b><code>parser</code></b>
|
| 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 <code>javacc.home</code> to contain a path to the installed JavaCC directory. |
| </li>
|
| <li><b><code>test</code></b>
|
| (after jar) will test Velocity against its testbed |
| suite of test routines. |
| </li>
|
| </ul>
|
| <p> |
| 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.) |
| </p>
|
| <p> |
| If the problems persist, do not hesitate to ask the Velocity community |
| via our mail lists. They can be found <a class="externalLink" href="http://velocity.apache.org/contact.html">here</a>
|
| . |
| </p>
|
| </div>
|
| <div class="section"><h2><a name="Testing_Your_Installation"></a>
|
| Testing Your Installation</h2>
|
| <p> |
| 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. |
| </p>
|
| <p>The tests are run with the ant task <junit>. For ant 1.6, this task requires that |
| <code>junit.jar</code> be copied into the <code>lib</code> subdirectory of your |
| ant directory. For ant 1.7 this is not required. |
| </p>
|
| <p> |
| To run the test suite, simply use the build target |
| <b>test</b>
|
| when you build: |
| </p>
|
| <div class="source"><pre> |
| ant test |
| </pre>
|
| </div>
|
| <p> |
| If all is well, you should see output similar to: |
| </p>
|
| <div class="source"><pre> |
| test: |
| [mkdir] Created dir: ..../bin/test-reports |
| [junit] Running org.apache.velocity.io.UnicodeInputStreamTestCase |
| [junit] Tests run: 8, Failures: 0, Errors: 0, Time elapsed: 0.011 sec |
| [junit] Running org.apache.velocity.test.AbsoluteFileResourceLoaderTestCase |
| [junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.015 sec |
| [junit] Running org.apache.velocity.test.ArithmeticTestCase |
| [junit] Tests run: 7, Failures: 0, Errors: 0, Time elapsed: 0.006 sec |
| [junit] Running org.apache.velocity.test.BuiltInEventHandlerTestCase |
| |
| ... |
| |
| BUILD SUCCESSFUL |
| Total time: 42 seconds |
| |
| </pre>
|
| </div>
|
| <p> |
| 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. |
| </p>
|
| </div>
|
|
|
| </div>
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| <div id="footer">
|
| <div class="xright">©
|
| 2000-2008
|
|
|
| The Apache Software Foundation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Last Published: 2008-12-15 08:38:22
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| </body>
|
| </html>
|
