How to run Forrest from within Maven
Intended Audience
Users who want to run Forrest from within Maven.
Purpose
One may want to generate their project's documentation and/or website using Forrest in lieu of Maven's site plugin.
Prerequisites
- Understand how to add goals to maven.xml.
Steps
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
Feedback
Please provide feedback about this document via the mailing lists.