User Manual
Installation is simple. Just unzip the
distribution into a directory on your machine, and set the
PATH to include the bin directory.
Installation - If Already Have Ant
Even easier. Just drop the jpp.jar
file into your ANT_HOME/lib directory. Ant will
automatically pick it up from there.
Adding The Task Definition To Ant
To add the task definition to Ant, place the
following line in your build.xml file:
<taskdef name='jpp' classname='com.javapreprocessor.ant.task.JPP' />
Adding the Task To Your Build File
The JPP task is based on the Ant
copy task, and supports most of the same attributes. The
simplest example is:
<!--
! Pre-process the files
! -->
<target name='preprocess'>
<!--
! Put everything in the 'preprocessed' directory
! -->
<jpp todir='preprocessed'>
<fileset dir='.'>
<include name='**/*' />
</fileset>
</jpp>
</target>
Filtering (see the Ant manual) is also supported:
<!--
! Pre-process the files with filtering. Everything instance
! of '@CUSTOMER' in any of the files will be replaced with
! 'My Customer'
! -->
<target name='preprocess-with-filtering'>
<!--
! Put everything in the 'preprocessed' directory
! -->
<filter token="CUSTOMER" value="My Customer"/>
<jpp todir='preprocessed' filtering='true'>
<fileset dir='.'>
<!--
! Exclude everything in the images folder - filtering
! can play havoc with binary files
! -->
<exclude name='**/images/*' />
</fileset>
</jpp>
</target>
Running The Preprocessor
The preoprocessor gets it definitions information from three places - in this order of priority:
-
The Ant command line
-
The Ant build file (including any .properties files read by the build file)
-
The inline preprocessing directives <code>#define</code> and <code>#undef</code>
To set a definition on the command-line, simply use the <code>-D</code> command-line option:
ant -DCUSTOMER1=defined ...
To set a definition in the build file, use the built-in Ant <code><&property></code> task:
<property name='CUSTOMER1' value='defined' />
or set it in a <code>.properties</code> file, and reference this in the build:
<property file='mybuild.properties' />
where the <code>mybuild.properties</code> file looks something like this:
# mybuild.properties
CUSTOMER1=defined
To set a definition in the preprocessor, use the <code>#define</code> or <code>#undef</code> preprocessor directives:
<!--#define CUSTOMER1 -->
<!--#undef CUSTOMER2 -->
There is no need to explicitly <code>#undef</code> a property, although it does help improve readability.
Adding Preprocessing Directives To Your Code
Simply include the preprocessing directives in your code using the syntax shown in the Supported File Types table.
The preprocessing directives will be invisible to normal applications, since they look like comments.
HTML / JSP Example
Suppose that you have some HTML / JSP files that you need to modify for different customers (say you need to change the customer name and logo). You simply add the preprocessing directives around the parts you want to include / exclude:
<html>
<head>
<!--#ifdef CUSTOMER1 -->
<!-- This section will only be included if the
! 'CUSTOMER1' property is defined.
! -->
<title>Welcome to Customer 1 Website!</title>
<link rel="stylesheet" href="/css/customer1.css"
type="text/css" />
<!--#endif -->
<!--#ifdef CUSTOMER2 -->
<!-- This section will only be included if the
! 'CUSTOMER2' property is defined.
! -->
<title>Welcome to Customer 2 Website!</title>
<link rel="stylesheet" href="/css/customer2.css"
type="text/css" />
<!--#endif -->
</head>
<body>
<!--#ifndef LICENCED -->
<!-- This section will only be included if the
! 'LICENCED' property is not defined.
! -->
<h1>This is an evaluation version</h1>
<!--#endif -->
</body>
</html>
Suppose that you were to execute a build that preprocessed this example, and you gave it the following command-line arguments:
ant -DCUSTOMER1=defined
The resulting file would look like this:
<html>
<head>
<!-- This section will only be included if the
! 'CUSTOMER1' property is defined.
! -->
<title>Welcome to Customer 1 Website!</title>
<link rel="stylesheet" href="/css/customer1.css" type="text/css"
/>
</head>
<body>
<!-- This section will only be included if the
! 'LICENCED' property is not defined.
! -->
<h1>This is an evaluation version</h1>
</body>
</html>
Whereas if you used the command-line arguments:
ant -DCUSTOMER2=defined -DLICENCED=defined
Then the resulting file would look like this:
<html>
<head>
<!-- This section will only be included if the
! 'CUSTOMER2' property is defined.
! -->
<title>Welcome to Customer 2 Website!</title>
<link rel="stylesheet" href="/css/customer2.css"
type="text/css" />
</head>
<body>
</body>
</html>
The actual values of 'CUSTOMER1' and 'LICENCED' do not matter - what matters is that they are set to something. The preprocessor does not check the values, it just checks that the properties are known.
The supported file types are shown in the table
below. The type of file is determined based on its filename (e.g.
foo.xml is assumed to be an XML file).
Supported File Types
The supported file types are shown in the table
below. The type of file is determined based on its filename (e.g.
foo.xml is assumed to be an XML file).
| File Type | Filenames | Command Syntax |
|---|---|---|
|
Java |
.java |
//#define SOMETHING |
|
Properties |
.properties |
#define SOMETHING |
|
CSS |
.css |
/*#define SOMETHING */ |
|
ASP |
.asp |
<!--#define SOMETHING --> |