<@page title="Installing" keywords="installing, install, setup"> <@sect title="Warning!">

FMPP, as a bulk file processor, may generates high amount of output files, and <@e>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!

<@sect title="Pre-requirements"> <@sect title="Extracting">

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

<@sect title="Setup the command-line tool" anchor="commandLineTool"> <@sect title="On Windows">

The steps are:

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

Note: Because of the limitations of <@c>.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.

<@sect title="On UN*X (Linux, FreeBSD, OS X, etc.)">

The steps are:

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

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

<@prg>

And then you can use the <@c><fmpp <@r>...> task. <@sect title="Installing optional parts and custom extensions">

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

<@sect title="Updating FreeMarker" anchor="updatingFreeMarker">

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