Repository: incubator-freemarker Updated Branches: refs/heads/2.3 bfb836b25 -> a5fb3511f
converted the readme from txt to md and added the build status from travis Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/f871237b Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/f871237b Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/f871237b Branch: refs/heads/2.3 Commit: f871237b3101c9ce531b6b675a77d39793179644 Parents: 93dea88 Author: Pradeep Murugesan <pradeepmuruge...@outlook.com> Authored: Thu Apr 13 12:30:54 2017 +0200 Committer: Pradeep Murugesan <pradeepmuruge...@outlook.com> Committed: Thu Apr 13 12:30:54 2017 +0200 ---------------------------------------------------------------------- README | 237 ---------------------------------------------------- README.md | 256 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ build.xml | 10 +-- 3 files changed, 260 insertions(+), 243 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/f871237b/README ---------------------------------------------------------------------- diff --git a/README b/README deleted file mode 100644 index c5cfc1e..0000000 --- a/README +++ /dev/null @@ -1,237 +0,0 @@ -/* - * 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. - -The minimum required Java version is currently Java SE 5. (The presence -of a later version may be detected on runtime and utilized by -FreeMarker.) - - -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.) To install Ivy (but be sure -it's not already installed), issue `ant download-ivy`, which will copy it -under ~/.ant/lib. Alternatively, you can copy ivy-<version>.jar into your -Ant home directory "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. - -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 jar ide-dependencies`. (Note that - now the folders "ide-dependencies", "build/generated-sources" and "META-INF" - were 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.) - - General -> Editors, set: - - Insert space for tabs - - Show print margin, 120 columns - - Java -> Code Style -> Formatter -> Import... - Select src\ide-settings\Eclipse\Formatter-profile-FreeMarker.xml - inside the FreeMarker project directory. - (On IntelliJ IDEA, import - src/ide-settings/IntelliJ-IDEA/Java-code-style-FreeMarker.xml instead) - This profile uses space-only indentation policy and 120 character line - width, and formatting rules that are pretty much standard in modern Java. - - Java -> Code Style -> Organize imports - (On IntelliJ IDEA, this was already configured by the Java code style - import earlier.) - The order is this (the Eclipse default): java, javax, org, com. - Number of imports required for .*: 99 - Number of static imports needed for .*: 1 - - Java -> Installed JRE-s: - Ensure that you have JDK 8 installed, and that it was added to Eclipse. - Note that it's not JRE, but JDK. - - Java -> Compiler -> Javadoc: - "Malformed Javadoc comments": Error - "Only consider members as visible": Private - "Validate tag argunebts": true - "Missing tag descriptions": Validate @return tags - "Missing Javadoc tags": Ignore - "Missing Javadoc comments": Ignore -- 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.8" - - 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 - Java8*.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. -- At Project -> Properties -> Java Editor -> Save Actions, check "Enable project - specific settings", then "Perform the selected actions on save", and have - only "Organize imports" and "Additional actions" checked (the list for the - last should contain "Add missing @Override annotations", - "Add missing @Override annotations to implementations of interface methods", - "Add missing @Deprecated annotations", and "Remove unnecessary cast"). -- 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. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/f871237b/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md new file mode 100644 index 0000000..7b1b039 --- /dev/null +++ b/README.md @@ -0,0 +1,256 @@ +``` + + 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} [![Build Status](https://travis-ci.org/apache/incubator-freemarker.svg?branch=2.3-gae)](https://travis-ci.org/apache/incubator-freemarker) +=========================== + 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: + +```xml + <!-- + 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. + +The minimum required Java version is currently Java SE 5. (The presence +of a later version may be detected on runtime and utilized by +FreeMarker.) + + +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. + + +Local setup +=========== + +First of all, if you haven't yet, download the source release, or checkout FreeMarker from the source code repository. + +You need +1. JDK 8(!), +2. Apache Ant and +3. Ivy + +to be installed. (As of this writing it was tested with Ant 1.8.1 and Ivy 2.3.0.). + +Ivy Installation +--------------------------- +To install Ivy (but be sure it's not already installed). +Issue +``` +ant download-ivy +``` +which will copy it under ~/.ant/lib. Alternatively, you can copy ivy-<version>.jar into your Ant home directory "lib" subfolder manually. + + +Building +--------------------------- + +To build freemarker.jar, just issue +``` +ant +``` +in the project root directory, and it should download all dependencies automatically and build freemarker.jar. + +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.) + +Managing dependencies +--------------------------- +If later you change the dependencies in ivy.xml, or otherwise want to re-download some of them, it will not happen automatically anymore. Issue +``` +ant update-deps +``` + + +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 jar ide-dependencies + ``` + (Note that now the folders "ide-dependencies", "build/generated-sources" and "META-INF" + were 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.) + - General -> Editors, set: + - Insert space for tabs + - Show print margin, 120 columns + - Java -> Code Style -> Formatter -> Import... + Select src\ide-settings\Eclipse\Formatter-profile-FreeMarker.xml + inside the FreeMarker project directory. + (On IntelliJ IDEA, import + src/ide-settings/IntelliJ-IDEA/Java-code-style-FreeMarker.xml instead) + This profile uses space-only indentation policy and 120 character line + width, and formatting rules that are pretty much standard in modern Java. + - Java -> Code Style -> Organize imports + (On IntelliJ IDEA, this was already configured by the Java code style + import earlier.) + The order is this (the Eclipse default): java, javax, org, com. + Number of imports required for .*: 99 + Number of static imports needed for .*: 1 + - Java -> Installed JRE-s: + Ensure that you have JDK 8 installed, and that it was added to Eclipse. + Note that it's not JRE, but JDK. + - Java -> Compiler -> Javadoc: + "Malformed Javadoc comments": Error + "Only consider members as visible": Private + "Validate tag argunebts": true + "Missing tag descriptions": Validate @return tags + "Missing Javadoc tags": Ignore + "Missing Javadoc comments": Ignore +- 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.8" + - 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 + Java8*.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. +- At Project -> Properties -> Java Editor -> Save Actions, check "Enable project + specific settings", then "Perform the selected actions on save", and have + only "Organize imports" and "Additional actions" checked (the list for the + last should contain "Add missing @Override annotations", + "Add missing @Override annotations to implementations of interface methods", + "Add missing @Deprecated annotations", and "Remove unnecessary cast"). +- 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. http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/f871237b/build.xml ---------------------------------------------------------------------- diff --git a/build.xml b/build.xml index cf8be0a..861a1b5 100644 --- a/build.xml +++ b/build.xml @@ -54,8 +54,6 @@ </condition> <condition property="has.all.explicit.boot.classpaths"> <and> - <isset property="has.explicit.boot.classpath.j2se1.5"/> - <isset property="has.explicit.boot.classpath.j2se1.6"/> <isset property="has.explicit.boot.classpath.j2se1.8"/> </and> </condition> @@ -670,7 +668,7 @@ <!-- Copy txt-s --> <copy todir="${dist.bin.dir}" includeEmptyDirs="no"> <fileset dir="." defaultexcludes="no"> - <include name="README" /> + <include name="README.md" /> <!-- LICENSE is binary-distribution-specific, and is copied later. --> <include name="NOTICE" /> <include name="DISCLAIMER" /> @@ -678,7 +676,7 @@ </fileset> </copy> <replace - file="${dist.bin.dir}/README" + file="${dist.bin.dir}/README.md" token="{version}" value="${version}" /> @@ -719,7 +717,7 @@ <!-- Copy extensionless files: --> <copy todir="${dist.src.dir}" includeEmptyDirs="no"> <fileset dir="." defaultexcludes="no"> - <include name="README" /> + <include name="README.md" /> <include name="LICENSE" /> <include name="NOTICE" /> <include name="DISCLAIMER" /> @@ -727,7 +725,7 @@ </fileset> </copy> <replace - file="${dist.src.dir}/README" + file="${dist.src.dir}/README.md" token="{version}" value="${version}" />