Author: brondsem
Date: Mon May 24 08:31:32 2004
New Revision: 20352
Modified:
xml/forrest/trunk/src/documentation/content/xdocs/site.xml
xml/forrest/trunk/src/documentation/content/xdocs/upgrading_06.xml
xml/forrest/trunk/src/documentation/content/xdocs/your-project.xml
Log:
document upgrading from forrest.antproxy.xml to Ant's <import>
Modified: xml/forrest/trunk/src/documentation/content/xdocs/site.xml
==============================================================================
--- xml/forrest/trunk/src/documentation/content/xdocs/site.xml (original)
+++ xml/forrest/trunk/src/documentation/content/xdocs/site.xml Mon May 24 08:31:32 2004
@@ -38,7 +38,7 @@
<new_content_type href="#adding_new_content_type"/>
<new_dtd href="#new_dtd"/>
<webapp href="#webapp"/>
- <get-cvs href="#getting_from_source"/>
+ <invoking_from_ant href="#invoking_from_ant"/>
</your-project>
<validation label="XML Validation" href="validation.html"/>
<linking label="Menus and Linking" href="linking.html">
Modified: xml/forrest/trunk/src/documentation/content/xdocs/upgrading_06.xml
==============================================================================
--- xml/forrest/trunk/src/documentation/content/xdocs/upgrading_06.xml (original)
+++ xml/forrest/trunk/src/documentation/content/xdocs/upgrading_06.xml Mon May 24 08:31:32
2004
@@ -68,7 +68,8 @@
For further information, see Issue
<link href="http://issues.cocoondev.org/jira/secure/ViewIssue.jspa?key=FOR-146">FOR-146</link>.
</p>
- </section>
+ </section>
+
<section>
<title>To be continued...</title>
Modified: xml/forrest/trunk/src/documentation/content/xdocs/your-project.xml
==============================================================================
--- xml/forrest/trunk/src/documentation/content/xdocs/your-project.xml (original)
+++ xml/forrest/trunk/src/documentation/content/xdocs/your-project.xml Mon May 24 08:31:32
2004
@@ -821,96 +821,31 @@
<section id="invoking_from_ant">
<title>Invoking Forrest from Ant</title>
<p>
- Established Java projects which use Ant will typically wish to subsume
- Forrest's build targets ('site', 'webapp', 'validate' etc) into their
- own build system, to provide a unified interface for users. This
- section describes how to invoke Forrest operations from an external
- Ant build file.
- </p>
- <p>
- Here are the targets that can be included in a project's build.xml
- file to invoke Forrest:
+ Ant has an <link href="http://ant.apache.org/manual/CoreTasks/import.html"><import></link>
+ task which can be used to invoke Forrest from Ant. All targets and properties
+ are imported and can be used in your project. Here's a simple example:
</p>
<source><![CDATA[
- <target name="site" description="Generates static HTML documentation">
- <ant antfile="${forrest.home}/forrest.antproxy.xml" target="site"/>
- </target>
-
- <target name="webapp"
- description="Generates an unpackaged webapp of the website">
- <ant antfile="${forrest.home}/forrest.antproxy.xml" target="webapp"/>
- </target>
-
- <target name="war"
- description="Generates a .war file containing the website">
- <ant antfile="${forrest.home}/forrest.antproxy.xml" target="war"/>
- </target>
-
- <target name="validate" description="Validates XML documentation files">
- <ant antfile="${forrest.home}/forrest.antproxy.xml" target="validate"/>
- </target>
+<project name="myproject" default="hello">
+ <!-- FORREST_HOME must be set as an environment variable -->
+ <property environment="env"/>
+ <import file="${env.FORREST_HOME}/forrest.build.xml"/>
+
+ <!-- 'site' is a target imported from forrest.build.xml -->
+ <target name="post-build" depends="site">
+ <echo>something here</echo>
+ </target>
+</project>
]]></source>
- <note>
- Always use <code>forrest.antproxy.xml</code>, not
- <code>forrest.build.xml</code>. The <code>forrest.antproxy.xml</code>
- script invokes <code>forrest.build.xml</code> using Forrest's own
- bundled version of Ant.
+ <note>If you do not use Ant 1.6+, the <import> task will not be
available for you to use. Forrest
+ includes the latest version of Ant so you can invoke your project like this: <code>forrest
-f myproject.xml</code>.
+ This will not run forrest; it will just use Forrest's Ant to execute your buildfile.
</note>
<p>
- You'll notice that these targets require <code>${forrest.home}</code>
- to be set. <code>${forrest.home}</code> must point to the user's
- shbat distribution of Forrest. Thus we need a mechanism for the user
- to inform the build script of their Forrest's location. Typically
- this is done by setting a property in a properties file like
- <code>project.properties</code>, but can also be done by looking for
the
- <code>FORREST_HOME</code> environment variable.
- </p>
- <p>
- Forrest comes with an Ant snippet file,
- <code>forrest-targets.ent</code> that supplies the targets listed
- above, as well as searching for a <code>${forrest.home}</code>
- definition in a number of likely places:
- </p>
- <ul>
- <li>In the <code>FORREST_HOME</code> environment variable.</li>
- <li>In the <code>project.properties</code> file.</li>
- <li>In the <code>build.properties</code> file.</li>
- <li>In the <code>ant.properties</code> file.</li>
- <li>In the <code>.ant.properties</code> file.</li>
- </ul>
- <p>
- <code>forrest-targets.ent</code> also prints out an informative error
- message if <code>${forrest.home}</code> cannot be resolved.
- </p>
- <p>
- <code>forrest-targets.ent</code> is supplied as part of the template
- Forrest project (<code>'forrest seed'</code>). The comments at the
- top describe how to use it in a project's build.xml. Typical usage
- is:
- </p>
- <source><![CDATA[
- <!DOCTYPE project [
- <!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
- ]>
-
- <project .... >
-
- ....
-
- <!-- Include Forrest targets -->
- &forrest-targets;
-
- </project>
- ]]></source>
- <p>
- Having done this, the Forrest targets (<code>site, webapp, war,
- validate</code>) are automatically added to your project.
+ The <link href="site:forrestbot">Forrestbot</link> provides workstages
to get source, build, deploy, and notify.
+ This is very useful for automating builds; you may want to consider using the Forrestbot
if your Ant project
+ does those things.
</p>
- <note>
- Take care if you set forrrest.home using <code>build.properties</code>
- because if your build already reads build.properties then the forrest
- targets will not be able to re-set the forrest.home property.
- </note>
</section>
</body>
</document>
|