| <?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>Building Velocity from Source</title> |
| <author email="dev@velocity.apache.org">Velocity Documentation Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Installation"> |
| |
| <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">Subversion</a> or |
| from the <a |
| 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 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> |
| |
| <source><![CDATA[ |
| 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. |
| ]]></source> |
| |
| </section> |
| |
| <section name="Required Tools"> |
| |
| <p> |
| To make building Velocity easy and consistent, we require an Apache project |
| called <a 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 href="http://javacc.dev.java.net">JavaCC</a>. We recommend |
| version 3.2 or greater (for compatibility with JDK 1.5 syntax changes). |
| </p> |
| |
| </section> |
| |
| <section name="Jar Dependencies"> |
| |
| <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> |
| |
| <tr> |
| <th>Jar</th> |
| <th>Purpose</th> |
| <th>Required at Runtime?</th> |
| </tr> |
| |
| <tr> |
| <td><code>antlr-2.7.5.jar</code></td> |
| <td>XML parsing (XPath queries in particular)</td> |
| <td>Only for Anakia</td> |
| </tr> |
| <tr> |
| <td><code>avalon-logkit-2.1.jar</code></td> |
| <td>Possible means of logging</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><code>commons-collection-3.1.jar</code></td> |
| <td>Used in parsing configuration</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td><code>commons-lang-2.1.jar</code></td> |
| <td>Various String utility functions</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <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> |
| <td><code>jdom-1.0.jar</code></td> |
| <td>XML parsing</td> |
| <td>Only for Anakia</td> |
| </tr> |
| <tr> |
| <td><code>log4j.1.2.12.jar</code></td> |
| <td>Possible means of logging</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <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> |
| <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> |
| <td><code>werken-xpath-0.9.4.jar</code></td> |
| <td>XML parsing</td> |
| <td>Only for Anakia</td> |
| </tr> |
| <tr> |
| <td><code>junit-3.8.1.jar</code></td> |
| <td>For running unit tests</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td><code>hsqldb-1.7.1.jar</code></td> |
| <td>For running database related unit tests</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <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> |
| |
| </section> |
| |
| <section name="Building"> |
| |
| <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> |
| |
| <source><![CDATA[ |
| ant |
| ]]></source> |
| |
| <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> |
| |
| <source><![CDATA[ |
| ant javadocs |
| ]]></source> |
| |
| |
| <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">here</a>. |
| </p> |
| |
| </section> |
| |
| <section name="Testing Your Installation"> |
| |
| <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> |
| <source><![CDATA[ |
| ant test |
| ]]></source> |
| |
| <p> |
| If all is well, you should see output similar to: |
| </p> |
| |
| <source><![CDATA[ |
| 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 |
| |
| ]]></source> |
| |
| <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> |
| </section> |
| |
| </body> |
| </document> |