Building Forrest within Eclipse

Persons who wish to invoke Apache- Forrest's Ant tasks from Eclipse".

To run, within Eclipse, Ant builds that include Forrest tasks.

• Forrest v. 0.7.0, downloaded from the CVS repository /usr/local/cvsrep/third-party/apache
• Environment variable FORREST_HOME set to the root of the Forrest installation (for 0.7; for 0.6 it was the /src/core directory within Forrest), per Forrest upgrade docs.
• Configure Oxygen to find Forrest's DTDs [this is not, strictly speaking, a prerequisite, but it is a mighty convenience]

Calling Forrest's Ant tasks from within Eclipse requires some initial set-up, and proper calling syntax. The Forrest team's description of invocation from Ant is available on the Forrest site; however, the simple descriptions below might prove more useful.

Add catalog entity resolver to Ant runtime classpath

In Eclipse, the Ant runtime classpath can be set from navigating to Ant : Runtime in the Preferences dialog.

Under Global Entries in the Classpath pane, add the JAR file forrest/lib/core/xml-commons-resolver-1.1.jar (i.e., the jar file xml-commons-resolver-1.1.jar located in the /lib/core directory of your Forrest installation).

Invoke Forrest targets from Ant

The following is an example of a target that invokes Forrest from within Ant. This invocation will run from within Eclipse. It is assumed that the property forrest.home has been set to the value of FORREST_HOME as described in the Prerequisites section, above.

<target name="forrest-site" description="Generates static HTML documentation">
  <ant antfile="${forrest.home}/forrest.build.xml" target="site"/>
</target>
      

Specify plugin version numbers

As of June 2007 (post-release of forrest version 0.8), it is necessary to specify the version numbers of plugins used by Forrest if forrest 0.7 is being used. For example, the default pdf plugin as of this date (0.2) is incompatible with Forrest 0.7. This specification must occur in the forrest.properties file of each forrest project (whether built from Eclipse or from the command-line).

A good place to start is to specify the input.projectInfo and output.pdf plugins at v. 0.1 for each, as shown below.

        # The names of plugins that are required to build the project
        # comma separated list (no spaces)
        # [...]
        project.required.plugins=org.apache.forrest.plugin.input.projectInfo-0.1,org.apache.forrest.plugin.output.pdf-0.1
      

In general, using older plugins than are current is described in one of the forrest FAQs How to use older versions of specific plugins?.

Plugin-download errors

In Forrest's documentation on running builds within Ant, there is a warning regarding a bug in the plugin downloader. If this error occurs, two options may resolve it:

• specify the plugin version number in forrest.properties, as described in the documentation
• the first time you run Forrest on the tree, run it from the command line, e.g., forrest site (where $FORREST_HOME/bin is on the path)

Note that following the instruction given in the prior section of this HowTo, Specify plugin version numbers may eliminate the errors described here before they ever occur...