| <?xml version="1.0" encoding="UTF-8" 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> |
| Apache™ 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.4 |
| (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.4 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> (Version 1.7 or later) 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> |
