commit | de52b49e3ef49c8840528cab1d05a98545e921b5 | [log] [tgz] |
---|---|---|
author | ddekany <ddekany@apache.org> | Thu Jan 05 12:11:56 2023 +0100 |
committer | ddekany <ddekany@apache.org> | Thu Jan 05 12:11:56 2023 +0100 |
tree | ba7636f3d1964ef157de5aeacef125518033c679 | |
parent | 3018a7bd97aab21cf108184bda62bced3077727c [diff] |
Updated version for the coming release
For the latest version or to report bugs visit: https://freemarker.apache.org/
By sending a pull request you grant the Apache Software Foundation sufficient rights to use and release the submitted work under the Apache license. You grant the same rights (copyright license, patent license, etc.) to the Apache Software Foundation as if you have signed a Contributor License Agreement. For contributions that are judged to be non-trivial, you will be asked to actually signing a Contributor License Agreement.
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.
FreeMarker is licensed under the Apache License, Version 2.0.
See the LICENSE file for more details!
Online: https://freemarker.apache.org/docs/
Offline: The full documentation is available in the binary distribution in the documentation/index.html directory.
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.
Attention: If you upgrade to OpenJDK 9 or later, and you are using XPath queries in templates, you will need to add Apache Xalan as a dependency, as freemarker.ext.dom can‘t use the XPath support included in OpenJDK anymore. It’s not needed on Oracle Java 9, or if FreeMarker is configured to use Jaxen for XPath.
The minimum required Java version is currently Java SE 7. (The presence of a later version may be detected on runtime and utilized by FreeMarker.)
Online (for stable releases only): https://freemarker.apache.org/docs/app_versions.html
Offline: In the binary release, open documentation/index.html, and you will find the link.
If you haven't yet, download the source release, or checkout FreeMarker from the source code repository. See repository locations here: https://freemarker.apache.org/sourcecode.html
You need JDK 8 (not JDK 9!), Apache Ant (tested with 1.9.6) and Ivy (tested with 2.5.0) to be installed. To install Ivy (but be sure it's not already installed), issue ant download-ivy
; it will copy Ivy under ~/.ant/lib
. (Alternatively, you can copy ivy-<version>.jar
into the Ant home lib
subfolder manually.)
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
. (Depencies will be cached into the .ivy/cache
subdirectory of the project.)
To test your build, issue ant test
.
To generate documentation, issue ant javadoc
and ant manualOffline
.
Do these first, regardless of which IDE you are using:
Install Ant and Ivy, if you haven't yet; see earlier.
From the command line, run ant clean jar ide-dependencies
(Note that now the folders ide-dependencies
, build/generated-sources
and META-INF
were created.)
Below you find the step-by-step setup for Eclipse (originally done on Mars.1):
Originally done on IntelliJ IDEA Community 2018.2.4:
“New” -> “Project”. In order as the IntelliJ will prompt you:
Select “Java” on the left side, and “1.8” for SDK on the right side. Press “Next”.
Template selection: Don't chose anything, “Next”
Project name: “FreeMarker-2.3-gae”. Project location: Wherever you have checked out the 2.3-gae branch from Git. Press “Finish”
Open your newly created “FreeMarker-2.3-gae” project
“File” -> “Project Structure...”
Select “Modules” (on the left) / “Sources” (tab on the right). Now you see a Content Root that was automatically added (at the rightmost side, under the “Add Content Root” button). Remove it (click the “X” next to it); no Content Root should remain. Now “Add Content Root”, and select the FreeMarker project folder. IntelliJ will now add the new Content Root, and automatically add some “Source Folders” and maybe some more under it, but it won't be correct, so edit it until your newly added Source Root has this content:
Source Folders:
src/main/java,
build/generated-sources/java [generated]
Test Source folders:
src/test/java
Resource Folders:
src/main/resources
Test Resource Folders:
src/test/resources
Still inside the “Sources” tab, change the “Language level” to “7”. (Yes, we use Java 8 SDK with language level 7 in the IDE, due to the tricks FreeMarker uses to support different Java versions.)
Switch over to the “Dependencies” tab (still inside “Project Structure” / “Modules”), and add all the jar-s inside the ide-dependencies
directory as dependency. (How: Click the “+” icon at the right edge, select “JARs or directory”, navigate to ide-dependencies
directory, expand it, then range-select all the jars in it. Thus you add all of them at once.) After all jar-s were added, find dom4j-*.jar in the table, and move it to the bottom of the table (otherwise it shadows some Jaxen classes with a too old version).
“File” -> “Settings” -> “Build, Execution, Deployment” -> “Compiler” -> “Excludes”: Add source files that match these (you simply find them manually, and add their absolute path):
_Jython20*.java,
_Jython22*.java,
_FreeMarkerPageContext2.java,
FreeMarkerJspFactory2.java,
Java8*.java
You may do “Build” / “Build project” (Ctrl+F9) to see if everything compiles now.
“File” -> “Settings”
/*
and */
lines, and the *
prefixes (to select columns of text, hold Alt while selecting with the mouse.) Then go back to “Copyright” in the tree, and set “Default project copyright” to “ASL2”.