<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2005 The Apache Software Foundation or its licensors,
  as applicable.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
<document>
  <header>
    <title>Building Forrest</title>
  </header>
  <body>
    <section id="getting_from_source">
      <title>Getting the Forrest source</title>
      <section>
        <title>Step-by-step Subversion (SVN) instructions</title>
          <note>If you are behind a proxy, see 
          <link href="http://subversion.tigris.org/project_faq.html#proxy">this FAQ</link>.</note>
        <ol> 
          <li>Make sure you have a recent release of a
           <link href="http://subversion.tigris.org/">Subversion</link>
           client installed and properly configured.</li>
          <li>Read the ASF notes about source repositories and
           <link href="http://www.apache.org/dev/version-control.html">version control</link>.
          </li>
          <li>At a command prompt, enter
           '<code>svn co http://svn.apache.org/repos/asf/forrest/trunk forrest</code>'
           (committers should replace <code>http</code> with <code>https</code>).</li>
          <li>This will create a directory called "<code>forrest</code>" where the Forrest source will be stored.</li> 
        </ol> 
        <p>Whenever you want to update your Forrest source tree to the current
         version, change to the top-level
"<code>forrest</code>" directory and invoke '<code>svn update</code>'.</p> 
        <p>To see what changes you've made, invoke '<code>svn status</code>'</p>
        <p>SVN is really powerful. See
          <link href="http://svnbook.red-bean.com/">Version Control with Subversion</link> - the opensource SVN book.
        </p>
      </section> 

      <section id="snapshot">
        <title>Using source snapshots</title>
        <p>It is preferable to use SVN, but if you cannot for some reason, then
          <link href="ext:forrest/download">source snapshots</link> are available
          (automatically packed every six hours).
        </p>
      </section>
    </section>

   <section id="building">
     <title>Building and installing Forrest</title>
<note>
This document applies to the current 0.7 release version.
See other instructions for the current development
<link href="http://forrest.apache.org/docs/dev/build.html">0.8-dev</link> version.
</note>
     <p>
       To build Forrest, change directory to '<code>forrest/main</code>', and
       then type '<code>build</code>' on Windows or '<code>./build.sh</code>' on
       Unix. (Requires Java 1.4)
       If everything is successful, you should see a message similar to:
     </p>
     <source>
  *-----------------------------------------------------------------
  | Installation notice
  *-----------------------------------------------------------------
  | You have built the X.Y-dev version of Forrest.
  | Please set the environment variable FORREST_HOME point to
  |  /svn/forrest
  | It is recommended to add
  |    unix: $FORREST_HOME/bin: to your $PATH
  |    win: %FORREST_HOME%\bin; to your %PATH%
  | Then do 'forrest -projecthelp' to list options for the 'forrest' command
  | More help at http://forrest.apache.org/
  *-----------------------------------------------------------------
     </source>
     <p>
       As the message says, you need to add the distribution's <code>bin/</code>
       ("binary") directory to your PATH variable, so the <code>'forrest'</code>
       command is available everywhere:
     </p>
     <source>
[~]$ cd /path/to/svn/forrest
[/svn/forrest]$ export FORREST_HOME=`pwd`
[/svn/forrest]$ export PATH=$PATH:$FORREST_HOME/bin
     </source>
     <warning>
       After updating the Forrest source from SVN, if there have been certain types of
       updates (e.g. Java sources, supporting libraries, build system, etc.) you will
       need to clean and build forrest again. Do 'cd forrest/main; build clean; build".
     </warning>
    </section>

  <section id="run">
    <title>Run Forrest, run!</title>
    <p>
      Forrest is now ready to go. To view and edit the local copy of
      Forrest core documentation, cd to site-author and do
      '<code>forrest run</code>' to see
      the local webapp using the bundled Jetty server. Edit something in
      content/xdocs/*.xml see the immediate effect.
    </p>
    <p>
      The document <link href="site:v0.70//your-project">Using Forrest</link> is
      your next step.</p>
  </section>

</body>
</document>
