| /* |
| * 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. |
| */ |
| |
| =============================================================================== |
| |
| Apache FreeMarker {version} |
| |
| For the latest version or to report bugs visit: |
| |
| http://freemarker.org/ |
| |
| =============================================================================== |
| |
| DISCLAIMER |
| |
| Apache FreeMarker is an effort undergoing incubation at The Apache |
| Software Foundation (ASF). Incubation is required of all newly accepted |
| projects until a further review indicates that the infrastructure, |
| communications, and decision making process have stabilized in a manner |
| consistent with other successful ASF projects. While incubation status is |
| not necessarily a reflection of the completeness or stability of the |
| code, it does indicate that the project has yet to be fully endorsed by |
| the ASF. |
| |
| |
| What is Apache FreeMarker? |
| -------------------------- |
| |
| FreeMarker is a "template engine"; a generic tool to generate text |
| output (anything from HTML to auto generated source code) based on |
| templates. It's a Java package, a class library for Java programmers. |
| It's not an application for end-users in itself, but something that |
| programmers can embed into their products. FreeMarker is designed to |
| be practical for the generation of HTML Web pages, particularly by |
| servlet-based applications following the MVC (Model View Controller) |
| pattern. |
| |
| |
| Licensing |
| --------- |
| |
| FreeMarker is licensed under the Apache License, Version 2.0. |
| |
| See the LICENSE file for more details! |
| |
| |
| Documentation |
| ------------- |
| |
| Online: http://freemarker.org/docs/ |
| |
| Offline: The full documentation is available in the binary distribution |
| in the documentation/index.html directory. |
| |
| |
| Installing |
| ---------- |
| |
| If you are using Maven, just add this dependency: |
| |
| <!-- |
| Attention: Be sure nothing pulls in an old dependency with groupId |
| "freemarker" (without the "org."), because then you will end up with |
| two freemarker.jar-s and unpredictable behavior on runtime! |
| --> |
| <dependency> |
| <groupId>org.freemarker</groupId> |
| <artifactId>freemarker</artifactId> |
| <version>{version}</version> |
| </dependency> |
| |
| Otherwise simply copy freemarker.jar to a location where your Java |
| application's ClassLoader will find it. For example, if you are using |
| FreeMarker in a web application, you probably want to put |
| freemarker.jar into the WEB-INF/lib directory of your web application. |
| |
| FreeMarker has no required dependencies. It has several optional |
| dependencies, but usually you don't have to deal with them, because if |
| you are using an optional feature that's certainly because your |
| application already uses the related library. |
| |
| |
| Change log |
| ---------- |
| |
| Online (for stable releases only): |
| http://freemarker.org/docs/app_versions.html |
| |
| Offline: |
| In the binary release, open documentation/index.html, and you will find the |
| link. |
| |
| |
| Building |
| -------- |
| |
| First of all, if you haven't yet, download the source release, or check |
| out FreeMarker from the source code repository. |
| |
| You need JDK 8(!), Apache Ant and Ivy to be installed. (As of this writing |
| it was tested with Ant 1.8.1 and Ivy 2.3.0.) Note that the ivy-<version>.jar |
| should be copied to your Ant home directory "lib" subfolder. |
| |
| It's recommended to copy build.properties.sample into build.properties, and |
| edit its content to fit your system. (Although basic jar building should |
| succeeds without the build.properties file too.) |
| |
| To build freemarker.jar, just issue "ant" in the project root |
| directory, and it should download all dependencies automatically and |
| build freemarker.jar. |
| |
| If later you change the dependencies in ivy.xml, or otherwise want to |
| re-download some of them, it will not happen automatically anymore. |
| You have to issue "ant update-deps" for that. |
| |
| |
| Eclipse and other IDE setup |
| --------------------------- |
| |
| Below you find the step-by-step setup for Eclipse Mars.1. If you are using a |
| different version or an entierly different IDE, still read this, and try to |
| apply it to your development environment: |
| |
| - Install Ant and Ivy, if you haven't yet; see earlier. |
| - From the command line, run `ant clean javacc ide-dependencies`. (Note that |
| now the "ide-dependencies" and "build/generated-sources" was created.) |
| - Start Eclipse |
| - You may prefer to start a new workspace (File -> "Switch workspace"), but |
| it's optional. |
| - Window -> Preferences |
| - General -> Workspace, set the text file encoding |
| to "UTF-8". (Or, you can set the same later on project level instead.) |
| - Java -> Code Style -> Formatter -> Import... |
| Select src\ide-settings\Eclipse-Mars\Formatter-profile-FreeMarker.xml |
| inside the FreeMarker project directory. |
| This profile uses space-only indentation policy and 120 character line |
| width, and formatting rules that are pretty much standard in modern Java. |
| - Java -> Installed JRE-s: |
| Ensure that you have JDK 6 installed, and that it was added to Eclipse. |
| Note that it's not JRE, but JDK. |
| - Create new "Java Project" in Eclipse: |
| - In the first window popping up: |
| - Change the "location" to the directory of the FreeMarker project |
| - Press "Next" |
| - In the next window, you see the build path settings: |
| - On "Source" tab, ensure that exactly these are marked as source |
| directories (be careful, Eclipse doesn't auto-detect these well): |
| build/generated-sources/java |
| src/main/java |
| src/main/resources |
| src/test/java |
| src/test/resources |
| - On the "Libraries" tab: |
| - Delete everyhing from there, except the "JRE System Library [...]" |
| - Edit "JRE System Library [...]" to "Execution Environment" "JavaSE 1.6" |
| - Add all jar-s that are directly under the "ide-dependencies" directory |
| (use the "Add JARs..." and select all those files). |
| - On the "Order and Export" tab find dom4j-*.jar, and send it to the |
| bottom of the list (becase, an old org.jaxen is included inside |
| dom4j-*.jar, which casues compilation errors if it wins over |
| jaxen-*.jar). |
| - Press "Finish" |
| - Eclipse will indicate many errors at this point; it's expected, read on. |
| - Project -> Properties -> Java Compiler |
| - Set "Compiler Compliance Level" to "1.5" (you will have to uncheck |
| "Use compliance from execution environment" for that) |
| - In Errors/Warnings, check in "Enable project specific settings", then set |
| "Forbidden reference (access rules)" from "Error" to "Warning". |
| - You will still have errors on these java files (because different java |
| files depend on different versions of the same library, and Eclipse can't |
| handle that). Exclude those java files from the Build Path (in the Package |
| Explorer, right click on the problematic file -> "Build Path" -> "Exclude"). |
| _Jython20*.java |
| _Jython22*.java |
| _FreeMarkerPageContext2.java |
| FreeMarkerJspFactory2.java |
| Also, close these files if they are open. Now you shouldn't have any errors. |
| - At Project -> Properties -> Java Code Style -> Formatter, check in "Enable |
| project specific settings", and then select "FreeMarker" as active profile. |
| - Right click on the project -> Run As -> JUnit Test |
| It should run without problems (all green). |
| - It's highly recommened to use the Eclipse FindBugs plugin. |
| - Install it from Eclipse Marketplace (3.0.1 as of this writing) |
| - Window -> Preferences -> Java -> FindBugs: |
| Set all bug marker ranks from Warning to Error. (For false alarms we add |
| @SuppressFBWarnings(value = "...", justification = "...") annotations.) |
| - Project -> Properties -> FindBugs -> [x] Run Automatically |
| - There should 0 errors. But sometimes the plugin fails to take the |
| @SuppressFBWarnings annotations into account; then use Project -> Clean. |