1Title: Apache Velocity Engine 2 3# Apache Velocity 4 5Welcome to Apache Velocity Engine! Apache Velocity is a general purpose 6template engine written in Java. For more information about Velocity, 7please look at the HTML documentation on the [Velocity web site](http://velocity.apache.org/index.html). 8 9Here's a description of the top level directories: 10 11 velocity-engine-core/ The Velocity Engine core module 12 velocity-engine-examples/ Several simple examples 13 velocity-engine-scripting/ JSR-223 implementation for Velocity scripting 14 spring-velocity-support Velocity Engine factory bean for Spring framework 15 src/ Source for parent modules, mainly changelog 16 17## REQUIREMENTS 18 19Apache Velocity 2.2 will run with any Java runtime engine v1.8 or greater. 20 21Building from source requires Java development kit v1.8 or greater and Maven 3 (3.0.5+). 22 23At compile time, Maven should fetch all engine needed dependencies, which are: 24 25* commons-lang v3.9 26* slf4j-api v1.7.30 27 28plus the following ones, needed for the integrated tests: 29 30* slf4j-simple v1.7.30 31* junit v4.13 32* hsqldb v2.5.0 33* commons-io 2.8.0 34 35At runtime, Velocity only needs: 36 37* commons-lang v3.9+ 38* slf4j-api and an slf4j binding, v1.7.30+ 39 40## BUILDING APACHE VELOCITY 41 42In order to use the latest version of Apache Velocity, you may want to 43build it. 44 45Building is easy. All components necessary to build are included or 46get downloaded from the internet during the build, except for the Java 47 SDK and the Maven build tool. You can find details online on [how to build 48Velocity](http://velocity.apache.org/engine/devel/build.html). 49 50*IMPORTANT* As the Apache Velocity build process wants to download a 51number of jars from the internet, you must be online when you are 52building for the first time. 53 54To build Velocity's jar, just run maven using the command: 55 56 mvn 57 58This will create a target/ directory containing the Velocity .jar 59file in each sub-module directory. 60 61Be sure to update your classpath to include Velocity's .jar 62file, or when using a modern servlet container, put it in the 63WEB-INF/lib directory. 64 65## CUSTOMIZING THE PARSER 66 67Since 2.2, it's possible to [build a custom parser](http://velocity.apache.org/engine/2.2/developer-guide.html#customizing-the-vtl-parser), to change some of the characters used by in the VTL syntax: `*`, `@`, `$` and `#`. 68 69Let's say you want to merge some templatized jQuery code full of `$` characters, you can for instance build you own parser which will use the `§` character as references prefix instead of `$`. 70 71## TRYING THE EXAMPLES 72 73After building Velocity, you can also build the examples that are 74included with the Velocity distribution. These examples show how to 75use Velocity in your Java applications. 76 77For more information, please see the [examples README](velocity-engine-examples) in the `velocity-engine-examples` directory. 78 79___ 80 81- The Apache Velocity Team 82 83