@page title="Installing" keywords="installing, install, setup">
<@sect title="Warning!">
Please understand that 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 watch where will the output files go.
Also note that, according <@a href="license.html">the license@a>, the author does not take responsibly if the usage of FMPP causes harm for you somehow.
@sect>
<@sect title="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.
@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:\fmpp@> or <@c>C:\Program Files\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 <@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, 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>.
- 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 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.
@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>/usr/lib/fmpp@c> or <@c>/opt/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, 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>.
- 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, open a command line window and issue: <@c>fmpp --version@c>
@sect>
<@sect title="Notes">
- If there's a <@c>FMPP_HOME@c> environment variable, it <@c><@r><FMPP_HOME>@r>\bin\fmpp.bat@c> and <@c><@r><FMPP_HOME>@r>\bin\fmpp@c> will use that directory instead of its own grandparent directory.
- 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 Ant task, copy the required jar files from <@c><@r><FMPP_HOME>@>/lib@> into the <@c>lib@> directory of your Ant installation (issuing <@c>ant install@c> from <@c><@r><FMPP_HOME>@>@> will do this for you), 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 required classes into the <@c><@r><FMPP_HOME>@>/lib@> directory (or, into the Ant <@c>lib@c> directory, if you store <@c>fmpp.jar@c> there only). 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 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>