| <!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/index.html">Engine</a> |
| | |
| <a href="../../../tools/devel/index.html">Tools</a> |
| | |
| <a href="../../../dvsl/devel/index.html">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="anakia.html">Anakia: XML->doc tool</a> |
| </li> |
| |
| <li class="none"> |
| <a href="texen.html">Texen: text generation</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 in 1.5</a> |
| </li> |
| |
| <li class="none"> |
| <a href="jira-report.html">Resolved Issues in 1.5</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/branches/Velocity_1.5_BRANCH/">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> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| |
| |
| |
| |
| |
| |
| <a name="installation"></a><div class="section"><h2>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 href="http://www.apache.org/dev/version-control.html" class="externalLink">Subversion</a> or |
| from the <a href="http://vc.apache.org/snapshots/velocity/" class="externalLink">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 href="http://ant.apache.org/" class="externalLink">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> |
| |
| <a name="required_tools"></a><div class="section"><h2>Required Tools</h2> |
| |
| <p> |
| To make building Velocity easy and consistent, we require an Apache project |
| called <a href="http://ant.apache.org/" class="externalLink">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 href="http://javacc.dev.java.net" class="externalLink">JavaCC</a>. We recommend |
| version 3.2 or greater (for compatibility with JDK 1.5 syntax changes). |
| </p> |
| |
| </div> |
| |
| <a name="jar_dependencies"></a><div class="section"><h2>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>jdom-1.0.jar</code></td> |
| <td >XML parsing</td> |
| <td >Only for Anakia</td> |
| </tr> |
| <tr class="a"> |
| <td ><code>log4j.1.2.12.jar</code></td> |
| <td >Possible means of logging</td> |
| <td >No</td> |
| </tr> |
| <tr class="b"> |
| <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="a"> |
| <td ><code>servletapi-2.3.jar</code></td> |
| <td >For the deprecated VelocityServlet</td> |
| <td >Only for VelocityServlet</td> |
| </tr> |
| <tr class="b"> |
| <td ><code>werken-xpath-0.9.4.jar</code></td> |
| <td >XML parsing</td> |
| <td >Only for Anakia</td> |
| </tr> |
| <tr class="a"> |
| <td ><code>junit-3.8.1.jar</code></td> |
| <td >For running unit tests</td> |
| <td >No</td> |
| </tr> |
| <tr class="b"> |
| <td ><code>hsqldb-1.7.1.jar</code></td> |
| <td >For running database related unit tests</td> |
| <td >No</td> |
| </tr> |
| <tr class="a"> |
| <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> |
| |
| <a name="building"></a><div class="section"><h2>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 href="http://velocity.apache.org/contact.html" class="externalLink">here</a>. |
| </p> |
| |
| </div> |
| |
| <a name="testing_your_installation"></a><div class="section"><h2>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> |
| 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-2007 |
| |
| The Apache Software Foundation |
| |
| |
| |
| |
| |
| |
| |
| |
| Last Published: 2007-03-06 19:34:54 |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |