Merge pull request #40 from apache/dependabot/maven/freemarker-generator-tools/com...
[freemarker-generator.git] / README.md
index 26b8923c64634589cd8a519fba8613cf844a6a72..3c9770e66b90073378735bf0f8b5776ebdf049e6 100644 (file)
--- a/README.md
+++ b/README.md
-Apache FreeMarker Generator\r
-===========================\r
-\r
-For documentation or to report bugs visit:\r
-https://freemarker.apache.org/generator.html\r
-\r
-\r
-Regarding pull requests on Github\r
----------------------------------\r
-\r
-By sending a pull request you grant the Apache Software Foundation\r
-sufficient rights to use and release the submitted work under the\r
-Apache license. You grant the same rights (copyright license, patent\r
-license, etc.) to the Apache Software Foundation as if you have signed\r
-a [Contributor License Agreement](https://www.apache.org/dev/new-committers-guide.html#cla).\r
-For contributions that are judged to be non-trivial, you will be asked\r
-to actually signing a Contributor License Agreement.\r
-\r
-\r
-What is Apache FreeMarker Generator?\r
-------------------------------------\r
-\r
-FreeMarker Generator is a tool that generates files based on FreeMarker\r
-templates and data that's typically provided in files (such as JSON files) as\r
-well. It can be used to generated source code, configuration files, etc.\r
-\r
-Currently it can be invoked as a Maven plug-in, but in the future it might\r
-will be callable on other ways (say, from Gradle, or as a standalone command\r
-line tool).\r
-\r
-freemarker-generator-maven-plugin\r
----------------------------------\r
-## Table of contents\r
-\r
-- [Background](#background)\r
-- [Install](#install)\r
-- [Usage](#usage)\r
-  - [FreeMarker Template Files](#freemarker-template-files)\r
-  - [JSON Generator Files](#json-generator-files)\r
-  - [Using POM Properties During Generation](#using-pom-properties-during-generation)\r
-  - [FreeMarker Configuration](#freemarker-configuration)\r
-  - [Incremental Builds](#incremental-builds)\r
-- [Code Coverage](#code-coverage)\r
-- [Contributing](#contributing)\r
-- [License](#license)\r
-\r
-## Background\r
-This plugin generates source files from FreeMarker templates with a flexible process that includes the ability to:\r
-\r
-- Generate multiple source files from a single template,\r
-- Generate source files during multiple steps in the build process such as testing, and\r
-- Specify distinct locations for the templates and data models for different stages of the build. \r
-\r
-## Install\r
-### pom.xml\r
-\r
-Add the following snippet within the `<plugins>` tag of your pom.xml:\r
-\r
-```xml\r
-      <plugin>\r
-        <groupId>com.oath</groupId>\r
-        <artifactId>freemarker-maven-plugin</artifactId>\r
-        <version>${freemarker-maven-plugin.version}</version>\r
-        <configuration>\r
-          <!-- Required. Specifies the compatibility version for template processing -->\r
-          <freeMarkerVersion>2.3.23</freeMarkerVersion>\r
-        </configuration>\r
-        <executions>\r
-          <!-- If you want to generate files during other phases, just add more execution\r
-               tags and specify appropriate phase, sourceDirectory and outputDirectory values.\r
-          -->\r
-          <execution>\r
-            <id>freemarker</id>\r
-            <!-- Optional, defaults to generate-sources -->\r
-            <phase>generate-sources</phase>\r
-            <goals>\r
-              <!-- Required, must be generate -->\r
-              <goal>generate</goal>\r
-            </goals>\r
-            <configuration>\r
-              <!-- Optional, defaults to src/main/freemarker/generator -->\r
-              <sourceDirectory>src/main/freemarker</templateDirectory>\r
-              <!-- Optional, defaults to src/main/freemarker/generator/template -->\r
-              <templateDirectory>src/main/freemarker/template</templateDirectory>\r
-              <!-- Optional, defaults to src/main/freemarker/generator -->\r
-              <generatorDirectory>src/main/freemarker/generator/generator</generatorDirectory>\r
-              <!-- Optional, defaults to target/generated-sources/freemarker -->\r
-              <outputDirectory>target/generated-sources/freemarker/generator</outputDirectory>\r
-            </configuration>\r
-          </execution>\r
-        </executions>\r
-      </plugin>\r
-```\r
-\r
-## Usage\r
-\r
-### FreeMarker Template Files\r
-FreeMarker template files must reside in the `templateDirectory`. For the default configuration,\r
-this is: `src/main/freemarker/generator/template`.\r
-\r
-By convention, file names for FreeMarker template files use the .ftl extension. For details on the FreeMarker\r
-template syntax, see: [Getting Started](https://freemarker.apache.org/docs/dgui_quickstart.html) and\r
-[Template Language Reference](https://freemarker.apache.org/docs/ref.html).\r
-\r
-### JSON Generator Files\r
-The JSON generator files must reside in the `generatorDirectory`. For the default\r
-configuration, this is: `src/main/freemarker/generator/generator`.\r
-\r
-For each JSON generator file, freemarker-maven-plugin will generate a file under the outputDirectory.\r
-The name of the generated file will be based on the name of the JSON data file. For example,\r
-the following JSON file: \r
-```\r
-    <sourceDirectory>/data/my/package/MyClass.java.json\r
-```\r
-will result in the following file being generated:\r
-```\r
-    <outputDirectory>/my/package/MyClass.java\r
-```\r
-\r
-This plugin parses the JSON generator file's `dataModel` field into a `Map<String, Object>` instance (hereafter, referred\r
-to as the data model). If the dataModel field is empty, an empty map will be created.\r
-\r
-Here are some additional details you need to know.\r
-\r
-  - This plugin *requires* one top-level field in the JSON data file: `templateName`. This field is used to locate the template file under `<sourceDirectory>/template` that is used to generate the file. This plugin provides the data model to FreeMarker as the data model to process the template identified by `templateName`.\r
-  - The parser allows for comments.\r
-  - This plugin currently assumes that the JSON data file encoded using UTF-8.\r
-\r
-Here is an example JSON data file:\r
-```json\r
-{\r
-  // An end-of-line comment.\r
-  # Another end-of-line comment\r
-  "templateName": "my-template.ftl", #Required\r
-  "dataModel": { #Optional\r
-      /* A multi-line\r
-         comment */\r
-      "myString": "a string",\r
-      "myNumber": 1,\r
-      "myListOfStrings": ["s1", "s2"],\r
-      "myListOfNumbers": [1, 2],\r
-      "myMap": {\r
-        "key1": "value1",\r
-        "key2": 2\r
-      }\r
-  }\r
-}\r
-```\r
-\r
-### Using POM Properties During Generation\r
-After parsing the JSON file, the plugin will add\r
-a `pomProperties` entry into the data model, which is a map itself, that contains the properties defined in the pom. Thus, your template can reference the pom property `my_property` using `${pomProperties.my_property}`. If you have a period or dash in the property name, use `${pomProperties["my.property"]}`.\r
-\r
-\r
-\r
-### FreeMarker Configuration\r
-\r
-Typically, users of this plugin do not need to mess with the FreeMarker configuration. This plugin explicitly sets two FreeMarker configurations:\r
-\r
- 1. the default encoding is set to UTF-8\r
- 2. the template loader is set to be a FileTemplateLoader that reads from `templateDirectory`.\r
\r
-If you need to override these configs or set your own, you can put them in a \r
-`<sourceDirectory>/freemarker.properties` file. If that file exists, this plugin will read it into a java Properties instance and pass it to freemarker.core.Configurable.setSettings() to establish the FreeMarker configuration. See this [javadoc](https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-) for configuration details.\r
-\r
-\r
-### Incremental Builds\r
-This plugin supports incremental builds; it only generates sources if the generator file, template file, or pom file have timestamps newer than any existing output file.  To force a rebuild if these conditions are not met (for example, if you pass in a model parameter on the command line), first run `mvn clean`.\r
-\r
-## Code Coverage\r
-\r
-By default, the code coverage report is not generated. It is generated by screwdriver jobs. You can generate code coverage on your dev machine with the following maven command:\r
-```bash\r
-mvn clean initialize -Dclover-phase=initialize \r
-``` \r
-Bring up the coverage report by pointing your browser to target/site/clover/dashboard.html under the root directory of the local repository.\r
-\r
-\r
-Licensing\r
----------\r
-\r
-Apache FreeMarker Generator is licensed under the Apache License, Version 2.0.\r
-\r
-See the LICENSE file for more details!\r
+Apache FreeMarker Generator
+=============================================================================
+
+For documentation or to report bugs visit: [https://freemarker.apache.org](https://freemarker.apache.org)
+
+Regarding pull requests on GitHub
+-----------------------------------------------------------------------------
+
+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](https://www.apache.org/dev/new-committers-guide.html#cla).
+For contributions that are judged to be non-trivial, you will be asked
+to actually signing a Contributor License Agreement.
+
+What is Apache FreeMarker Generator?
+-----------------------------------------------------------------------------
+
+FreeMarker Generator is a set of tools that generates files based on FreeMarker
+templates and data that's typically provided in files (such as JSON files) as
+well. It can be used to generated source code, configuration files, etc.
+
+Currently it can be invoked as a 
+
+* Command-line interface `freemarker-generator`
+* Maven plug-in `freemarker-generator-maven-plugin`
+
+Building Apache FreeMarker Generator
+-----------------------------------------------------------------------------
+
+To create the artifacts locally run
+
+> mvn clean install
+
+To build the documentation site run
+
+> mvn clean site site:stage
+
+Licensing
+-----------------------------------------------------------------------------
+
+Apache FreeMarker Generator is licensed under the Apache License, Version 2.0.
+
+See the LICENSE file for more details!