How to run Forrest from within Maven

Users who want to run Forrest from within Maven.

One may want to generate their project's documentation and/or website using Forrest in lieu of Maven's site plugin.

• Understand how to add goals to maven.xml.

The procedure outlined below describes how to add a goal to your project's maven.xml that will invoke Forrest's site target.

Set the FORREST_HOME environment variable

Make sure the FORREST_HOME environment variable points to your Forrest home directory (i.e. the directory that contains forrest.build.xml) (e.g. C:\opt\apache-forrest-0.7)

Initialize an Ant environment property at the top of maven.xml

Paste the following line at the top of your maven.xml:

<property environment="env" />
      

Add forrest goal to maven.xml

Paste the following goal into your project's maven.xml:

<goal name="forrest" description="runs Forrest">
  <property name="forrest.home" location="${env.FORREST_HOME}" />
  <property name="forrest.ant.home" location="${forrest.home}/tools/ant" />
  <java classname="org.apache.tools.ant.Main" fork="true" failonerror="true" maxmemory="128M">
    <classpath>
      <fileset dir="${forrest.ant.home}/lib">
        <include name="*.jar" />
      </fileset>
      <pathelement path="${java.home}/../lib/tools.jar" />
    </classpath>
    <sysproperty key="ant.home" value="${forrest.ant.home}" />
    <sysproperty key="forrest.home" value="${forrest.home}" />
    <sysproperty key="basedir" value="${basedir}" />
    <sysproperty key="java.endorsed.dirs" value="${forrest.home}/lib/endorsed" />
    <arg line="-f ${forrest.home}/main/forrest.build.xml" />
  </java>
</goal>      
      

It is necessary to fork a separate java process because Maven 1.0 embeds Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. The goal makes use of the copy of Ant 1.6 that is bundled with Forrest, so it's not even necessary to have Ant 1.6 installed separately.

Alternative file

Under $FORREST_HOME/tools/targets/maven.xml

Please provide feedback about this document via the mailing lists.