@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>
<@sect title="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.
@sect>
<@sect title="Extracting">
Extract the downloaded archive file (<@c>fmpp_<@r>X@r>.<@r>X@r>.<@r>X@r>.tar.gz@c> or <@c>fmpp_<@r>X@r>.<@r>X@r>.<@r>X@r>.zip@c>) 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@c> (where <@c>fmpp@c> is the extracted <@c>fmpp_<@r>X@r>.<@r>X@r>.<@r>X@r>@c> directory after renaming). From now on I will refer to this directory as <@c><@r><FMPP_HOME>@>@>.
@sect>
<@sect title="Setup the command-line tool" anchor="commandLineTool">
<@sect title="On Windows">
The steps are:
- Extract the downloaded archive file (<@c>fmpp_${pp.version}.tar.gz@c> or <@c>fmpp_${pp.version}.zip@c>) into <@c>C:\Program Files\fmpp@c> (note that "Program Files" may be shown in a localized form, like "Programme"), or into <@c>C:\fmpp@c>, or wherever you prefer to. From now on I will refer to this directory as <@c><@r><FMPP_HOME>@>@>
- For convenience (optional), add <@c><@r><FMPP_HOME>@>/bin@> to the <@c>PATH@c> environment variable. (How? Google: set path windows)
- Check if <@c>fmpp.bat@> isn't present in <@c>C:\Windows@c> (or in another directory in the <@c>PATH@c>) from an earlier installation. Delete it if it does.
- Check if the <@c>JAVA_HOME@c> environment variable is set correctly (should point to your Java installation directory, not its <@c>bin@c> subdirectory), or else that the intended version of the <@c>java@c> executable is in the <@c>PATH@c>. Otherwise FMPP may won't find Java.
- To check that everything works, open a command line window and issue: <@c>fmpp --version@c>
Note: Because of the limitations of <@c>.bat@c> 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>
<@sect title="On UN*X (Linux, FreeBSD, OS X, etc.)">
The steps are:
- Extract the downloaded archive file (<@c>fmpp_${pp.version}.tar.gz@c> or <@c>fmpp_${pp.version}.zip@c>) into the <@c>~/opt/fmpp@> or <@c>/opt/fmpp@> or <@c>/usr/lib/fmpp@c> directory (conventions vary by distribution), or wherever you prefer to. From now on I will refer to this directory as <@c><@r><FMPP_HOME>@r>@c>.
- For convenience (optional), create a soft link somewhere in the <@c>PATH@c>, like <@c>sudo ln -s <@r><FMPP_HOME>@r>/bin/fmpp /usr/bin/fmpp@c>. (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>@r>@c> as far as it's one of the above listed well known directories, or if you have set the <@c>FMPP_HOME@c> environment variable yourself.)
- Issue <@c>which fmpp@c> to see if it's not shadowed by an earlier installation elsewhere.
- Check if the intended version of the <@c>java@c> executable is in the <@c>PATH@c>, or else that the <@c>JAVA_HOME@c> environment variable is set correctly (should point to your Java installation directory, not its <@c>bin@c> subdirectory).
- To check that everything works, issue this in the command line: <@c>fmpp --version@c>
@sect>
<@sect title="Notes">
- If the <@c>FMPP_HOME@c> environment variable is set, <@c><@r><FMPP_HOME>@r>\bin\fmpp.bat@c> and <@c><@r><FMPP_HOME>@r>\bin\fmpp@c> will use that directory as <@c><@r><FMPP_HOME>@>@>.
- You can run FMPP without the provided shell scripts directly with the <@c>java@c> command, like <@c>java -jar <@r><FMPP_HOME>@r>/lib/fmpp.jar@c>. (You can also put all required jar-s and class directories into the <@c>CLASSPATH@> and then issue <@c>java fmpp.tools.CommandLine@c>.) Note though that you will lose console width detection with these approaches.
- You can move the jars into the <@c>lib@c> 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>C:\Program Files\ant@c>), or <@c>ANT_HOME@c> must be correctly set.
@sect>
@sect>
<@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@c>:
<@prg>@prg>
And then you can use the <@c><fmpp <@r>...@r>>@> task.
@sect>
<@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@c> directory, if you only use FMPP as Ant task). For the Ant task, either ensure that the required jars are in the <@c>CLASSPATH@c>, or drop the jars into the <@c>lib@c> directory of your Ant installation.
@sect>
<@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@c> with the <@c>freemarker.jar@c> of the FreeMarker release. (Of course, if you are using the FMPP Ant task, you may need to replace the <@c>freemarker.jar@c> in the <@c>lib@c> directory of the Ant installation too.)
@sect>
@page>