Building FOray

• Introduction
• Downloading Source Code
• Setting Up Your Environment
• Run the Build Script
• Building a Subset of FOray

Introduction

Before building FOray from source code, make sure that you need to. Unless you need access to source code or to an unreleased feature, you probably just need to download a FOray binary distribution.

Downloading Source Code

FOray source code can be obtained two ways:

• Current releases can be obtained from the FOray download page.
• Up-to-the-minute source code can be obtained from the "trunk" of the source code repository.

Setting Up Your Environment

In order to successfully build FOray, you must have the following items installed on your system:

• A Java Development Kit (JDK), version 5.0 or higher.
• A recent version of Apache Ant.
• A current build of the aXSL libraries. If you are building from released source code, the aXSL library in the distribution is the correct one to use. If building from repository source code between releases, you will need to download and build aXSL as well. After building aXSL, either copy the built jar files to the FOray lib directory, or reference them from the FOray build, using the "axsl.build" configuration option described below.

Before running the build scripts, you must tell them about your environment. Set and export the following environment variables:

• $JAVA_HOME. Set this to the location of the JDK you wish to use.
• $ANT_HOME. Set this to the location of the root of your Ant installation.
• $FORAY_CONFIG (optional). The default location of the FOray configuration directory is the FOray "scripts" directory, but this environment variable can be used to point to a different directory. If a file named "foray-build.properties" is found in the FOray configuration directory, it will be used by the build process. The useful properties that can be configured in that file are:
  • foray.sandbox = The root directory for FOray itself.
  • axsl.build = The location of an aXSL build that should be used instead of the build in the FOray "lib" directory. This does not need to be set if the built aXSL jar files have been copied to the FOray lib directory.
  • checkstyle.home = Directory containing Checkstyle.

Run the Build Script

The actual build process can be started from foray/scripts/build.sh (for Unix/Linux) or foray/scripts/build.bat (for Windows). The results of the build can be found in foray/build/ant/. Most IDEs also have mechanisms for running Ant build scripts.

Building a Subset of FOray

Most FOray users will want to build and use the entire product, which is the default of the build script. However, some software developers may wish to use a subset of FOray in their "lib". For example, a project might wish to use FOray's font and fotree systems, but want to use non-FOray modules for everthing else. The FOray build system allows the modules to be built in any combination, automatically including all FOray dependencies. To use this feature, select the "clean" target first, followed by the names of the module(s) that you wish to include in the build, then followed by the "package" target. So for the example above, run "ant clean font fotree package".

The module targets available are: common, xml, ps, graphic, mif, font, hyphen, text, pdf, fotree, areatree, output, layout, pioneer, render, core, app. For more information on the meaning of these targets, see Modules.

When a subset is built, the resulting jar file includes the word "subset" in its name. In all cases, the jar manifest includes a list of the modules that were included in the build, in a heading entitled "FOray-Modules".

Note that if a subset is built, some FOray lib entries may not be needed.