Building Forrest

Step-by-step Subversion (SVN) instructions for developers

1. Make sure you have a recent release of a Subversion client installed and properly configured.
2. Read the ASF notes about source repositories and version control and see Forrest's developer notes about our SVN.
3. At a command prompt, enter 'svn co http://svn.apache.org/repos/asf/forrest/trunk forrest' (committers should replace http with https).
4. This will create a directory called "forrest" where the Forrest source will be stored.
5. Pay attention to README.txt and LICENSE.txt and NOTICE.txt files.

Whenever you want to update your Forrest source tree to the current version, change to the top-level "forrest" directory and invoke 'svn update'.

To see what changes you've made, invoke 'svn status'

SVN is really powerful. See Version Control with Subversion - the opensource SVN book.

Sources are also available in the release

Each release of forrest contains a copy of all sources as at the time of the release. So the building instructions below do apply to that. Of course the svn method described above will provide the most up-to-date version for developers.

To build Forrest, change directory to 'forrest/main', and then type 'build' on Windows or './build.sh' on Unix. (Requires Java 1.5) If everything is successful, you should see a message similar to:

  *-----------------------------------------------------------------
  | 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/
  *-----------------------------------------------------------------
     

As the message says, you need to add the distribution's bin/ ("binary") directory to your PATH variable, so the 'forrest' command is available everywhere:

[~]$ cd /path/to/svn/forrest
[/svn/forrest]$ export FORREST_HOME=`pwd`
[/svn/forrest]$ export PATH=$PATH:$FORREST_HOME/bin
     

Forrest is now ready to go. To view and edit the local copy of Forrest core documentation, cd to site-author and do 'forrest run' to see the local webapp using the bundled Jetty server. Edit something in content/xdocs/*.xml see the immediate effect.

The document Using Forrest is your next step.