Installing - FMPP

Warning!

FMPP, as a bulk file processor, may generates high amount of output files, and overwrites all files with the same names as the names of output files without warning. It's a practical decision comes from the usage pattern of the tool. So be careful with where the output files go!

Pre-requirements

Java must be installed on your machine (version 5 or later). Java is available for free, and on various platforms (Windows, OS X, "Linux", etc.), so FMPP works on many platforms. There are some variations, all is fine: OpenJDK (popular on Linux), Oracle Java SE JRE, Oracle Java SE JDK, etc.
If you want to use FMPP as an Apache Ant task, you need Apache Ant 1.5.1 or later.

Extracting

Extract the downloaded archive file (fmpp_X.X.X.tar.gz or fmpp_X.X.X.zip) into the directory where you prefer to store FMPP. For Windows users it is typically C:\Program Files\fmpp or C:\fmpp, for UN*X users it is typically ~/opt/fmpp or /opt/fmpp or /usr/lib/fmpp (where fmpp is the extracted fmpp_X.X.X directory after renaming). From now on I will refer to this directory as <FMPP_HOME>.

Setup the command-line tool

On Windows

The steps are:

Extract the downloaded archive file (fmpp_0.9.16.tar.gz or fmpp_0.9.16.zip) into C:\Program Files\fmpp (note that "Program Files" may be shown in a localized form, like "Programme"), or into C:\fmpp, or wherever you prefer to. From now on I will refer to this directory as <FMPP_HOME>
For convenience (optional), add <FMPP_HOME>/bin to the PATH environment variable. (How? Google: set path windows)
Check if fmpp.bat isn't present in C:\Windows (or in another directory in the PATH) from an earlier installation. Delete it if it does.
Check if the JAVA_HOME environment variable is set correctly (should point to your Java installation directory, not its bin subdirectory), or else that the intended version of the java executable is in the PATH. Otherwise FMPP may won't find Java.
To check that everything works, open a command line window and issue: fmpp --version

Note: Because of the limitations of .bat files, you may get error messages like "The input line is too long". To solve this, install FMPP in a more "shallow" directory, so that the path to the FMPP related files will be shorter.

On UN*X (Linux, FreeBSD, OS X, etc.)

The steps are:

Extract the downloaded archive file (fmpp_0.9.16.tar.gz or fmpp_0.9.16.zip) into the ~/opt/fmpp or /opt/fmpp or /usr/lib/fmpp directory (conventions vary by distribution), or wherever you prefer to. From now on I will refer to this directory as <FMPP_HOME>.
For convenience (optional), create a soft link somewhere in the PATH, like sudo ln -s <FMPP_HOME>/bin/fmpp /usr/bin/fmpp. (Alternatively, you can copy that shell script directly into /usr/bin/, or into other standard directory, and it will still automatically find the <FMPP_HOME> as far as it's one of the above listed well known directories, or if you have set the FMPP_HOME environment variable yourself.)
Issue which fmpp to see if it's not shadowed by an earlier installation elsewhere.
Check if the intended version of the java executable is in the PATH, or else that the JAVA_HOME environment variable is set correctly (should point to your Java installation directory, not its bin subdirectory).
To check that everything works, issue this in the command line: fmpp --version

Notes

If the FMPP_HOME environment variable is set, <FMPP_HOME>\bin\fmpp.bat and <FMPP_HOME>\bin\fmpp will use that directory as <FMPP_HOME>.
You can run FMPP without the provided shell scripts directly with the java command, like java -jar <FMPP_HOME>/lib/fmpp.jar. (You can also put all required jar-s and class directories into the CLASSPATH and then issue java fmpp.tools.CommandLine.) Note though that you will lose console width detection with these approaches.
You can move the jars into the lib subdirectory of Ant (if you want to use the Ant task anyway). If you do this, the command line tool need Ant be installed on a "standard" location (like C:\Program Files\ant), or ANT_HOME must be correctly set.

Setup the Ant task

If you want to use FMPP as Apache Ant task, copy the required jar files from <FMPP_HOME>/lib into the lib directory of your Ant installation, or ensure that the jars are in the CLASSPATH environment variable. Then, whenever you need the FMPP task in a project, add this line to your build.xml:

<taskdef name="fmpp" classname="fmpp.tools.AntTask"/>

And then you can use the <fmpp ...> task.

Installing optional parts and custom extensions

For the command-line tool, simply drop the jar file that contains the additional classes into the <FMPP_HOME>/lib directory (or, into the Apache Ant lib directory, if you only use FMPP as Ant task). For the Ant task, either ensure that the required jars are in the CLASSPATH, or drop the jars into the lib directory of your Ant installation.

Updating FreeMarker

You can replace the included Apache FreeMarker version with a later version. Download the latest backward compatible FreeMarker release, and overwrite <FMPP_HOME>/lib/freemarker.jar with the freemarker.jar of the FreeMarker release. (Of course, if you are using the FMPP Ant task, you may need to replace the freemarker.jar in the lib directory of the Ant installation too.)