1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
<?xml version="1.0" standalone="no"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- $Id$ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
<header>
<title>Apache FOP: Building from Source Code</title>
<version>$Revision$</version>
</header>
<body>
<section id="build-needed">
<title>Do You Need To Build?</title>
<p>
FOP distributions are either pre-compiled binary or source.
If you are using a binary distribution, it is already built and there is no need to build it again.
See the <a href="../download.html">Download Instructions</a> for information about whether a
binary or source distribution is best for your needs.
</p>
<p>
If you got the source code from a repository snapshot or via Subversion you will need to build FOP
in any case.
</p>
</section>
<section id="env">
<title>Set Up Your Environment</title>
<section id="env-jdk">
<title>JDK</title>
<p>
Building FOP requires a minimum Java Development Kit (JDK/SDK) of 1.3
(A Java Runtime Environment is not sufficient).
</p>
</section>
<section id="env-classpath">
<title>CLASSPATH</title>
<p>
There is generally no need to setup a classpath. All libraries needed to compile FOP are included
in the source distribution and are referenced by the build script.
You will only need to adjust the classpath if you build FOP in some other way. See the build
script build.xml for details.
</p>
</section>
<section id="env-java-home">
<title>JAVA_HOME</title>
<p>
The build script uses <a href="ext:ant">Apache Ant</a>, a popular
Java-based build tool, which usually requires that the environment variable JAVA_HOME point to
your local JDK root directory. This is true even if you use JDK 1.3 or above, which normally
does not need this setting.
</p>
</section>
<section id="env-ant">
<title>Apache Ant</title>
<p>
<a href="ext:ant">Apache Ant</a> must be installed in order to
build FOP. Following best practices we don't include Ant with FOP anymore. You can find the
<a href="ext:ant/manual/">instructions to install Ant in the Ant manual</a> on the web.
</p>
</section>
</section>
<section id="build-script">
<title>Run the Build Script</title>
<p>
Change to the FOP root directory and build FOP by executing the build script (build.xml)
using the "ant" command.
</p>
<note>
The "ant" command is only available on your system if you've properly
<a href="ext:ant/manual/">installed Apache Ant</a> and added Ant's location to the PATH
environment variable.
</note>
<p>
The file build.xml in the FOP root directory is the blueprint that Ant uses for the build. It
contains information for numerous build targets, many of which are building blocks to more
useful target, and others which are primarily used by the FOP developers.
You may benefit from looking through this file to learn more about the various build targets.
To obtain a complete list of useful build targets:
</p>
<source>ant -projecthelp</source>
<p>The most useful targets are:</p>
<ul>
<li>
<strong>package</strong>: Generates the JAR files (default). This is the normal build that
produces a jar file usable for running FOP.
</li>
<li>
<strong>clean </strong>: Cleans the build directory. This is useful for making sure that
any build errors are cleaned up before starting a new build. It should not ordinarily be
needed, but may be helpful if you are having problems with the build process itself.
</li>
<li>
<strong>javadocs</strong>: Creates the FOP API documentation.
<note>A minimum JDK version of 1.4.2 is required for generating the javadocs.</note>
</li>
</ul>
<p>To run the build:</p>
<source>ant [target ...]</source>
<p>For example to do a normal build for the "all" target (which is the default):</p>
<source>ant</source>
<p>OR</p>
<source>ant all</source>
<p>To clean the build directory first:</p>
<source>ant clean all</source>
<note>
If you want to shorten the build time you can just call the "package" target which
doesn't perform any automated tests during the build.
</note>
</section>
<section id="problems">
<title id="Troubleshooting">Troubleshooting</title>
<p>If you have problems building FOP, please try the following:</p>
<ul>
<li>Run the build with the target of "clean", then rerun the build.</li>
<li>Delete the build directory completely, then rerun the build.</li>
<li>
Make sure you do not have a non-FOP version of xerces.jar, xalan.jar, batik.jar,
or another dependency product somewhere in your CLASSPATH.
</li>
<li>
If the build still fails, see the <a href="../gethelp.html">Getting Help</a>
page for further help.
</li>
</ul>
</section>
</body>
</document>
|
