<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation

  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="site:download">source snapshots</link> are available
          (automatically packed every six hours).
        </p>
      </section>
    </section>

   <section id="building">
     <title>Building and Installing Forrest</title>
     <p>
       To build Forrest, type '<code>build</code>' on Windows, or '<code>./build.sh</code>' on
       Unix. If everything is successful, you should see a message like this:
     </p>
     <source>
  *-----------------------------------------------------------------
  | installation notice
  *-----------------------------------------------------------------
  | You have built the distribution of Forrest.
  | Please set the environment variable FORREST_HOME point to src/core
  | 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>
~/apache/forrest$ export FORREST_HOME=`pwd`/src/core
~/apache/forrest$ export PATH=$PATH:$FORREST_HOME/bin
     </source>
     <p>
       After updating the Forrest source from SVN if there have been certain types of
       updates (to the Java source for xml-forrest.jar), you will have to build forrest again.
     </p>
    </section>

  <section id="run">
    <title>Run Forrest, run!</title>
    <p>Forrest is now ready to go. Type '<code>forrest run</code>' to see
    the local webapp using the bundled Jetty server. Edit some of Forrest's
    core documentation and see the effect.
    The document <link href="site:your-project">Using Forrest</link> is
    your next step.</p>
  </section>

</body>
</document>
