Installing

Warning!

Please understand that 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 watch where will the output files go.

Also note that, according the license, the author does not take responsibly if the usage of FMPP causes harm for you somehow.

Pre-requirements

  • Java must be installed on your machine (version 1.4 or later). Note that Java is available for free, and on various platforms (Windows, OS X, "Linux", etc.), so FMPP works on many platforms.
  • If you want to use the FMPP Ant task, you need Ant 1.5.1 or later. If you don't know what's Ant then don't worry, you will not need it.

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:\fmpp or C:\Program Files\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:

  1. Extract the downloaded archive file (fmpp_0.9.15.tar.gz or fmpp_0.9.15.zip) into C:\Program Files\fmpp (note that "Program Files" may be shown in a localized form, like "Programme") or C:\fmpp or wherever you prefer to. From now on I will refer to this directory as <FMPP_HOME>
  2. For convenience, add <FMPP_HOME>/bin to the PATH environment variable. (How? Google: set path windows)
  3. 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.
  4. 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.
  5. 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 as "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:

  1. Extract the downloaded archive file (fmpp_0.9.15.tar.gz or fmpp_0.9.15.zip) into the /usr/lib/fmpp or /opt/fmpp directory (conventions vary by distribution), or wherever you prefer to. From now on I will refer to this directory as <FMPP_HOME>.
  2. For convenience, create a soft link somewhere in the PATH, like sudo ln -s <FMPP_HOME>/bin/fmpp /usr/bin/fmpp.
  3. Issue which fmpp to see if it's not shadowed by an earlier installation elsewhere.
  4. 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).
  5. To check that everything works, open a command line window and issue: fmpp --version

Notes

  • If there's a FMPP_HOME environment variable, it <FMPP_HOME>\bin\fmpp.bat and <FMPP_HOME>\bin\fmpp will use that directory instead of its own grandparent directory.
  • 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 Ant task, copy the required jar files from <FMPP_HOME>/lib into the lib directory of your Ant installation (issuing ant install from <FMPP_HOME> will do this for you), 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 required classes into the <FMPP_HOME>/lib directory (or, into the Ant lib directory, if you store fmpp.jar there only). 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 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.)