Installing Forrest

The Axis website build system requires two components to perform a build.
Ant and Forrest.

Specifically the build has been tested to work with Ant version 1.6.1 and Forrest 0.5.1. To install these products download the distributions and follow the instructions in their documentation. Make sure you don't forget to set the environment variables FORREST_HOME and ANT_HOME. The ANT_HOME/bin directory should be in the path.

Checking out ws-axis and ws-site module

Check out 'http://svn.apache.org/repos/asf/webservices/axis/trunk/site/src/java' and 'http://svn.apache.org/repos/asf/webservices/axis/site' module via your favorite SVN tools.
Please follow the guideline written here.

Running the Build

Here's a list of targets for the ant task. But, what you need to do is just "ant".

Target Description
clean Erase all build work products (ie, everything in the build directory
run-forrest Run Forrest with Jetty server to review the target
run-browser Invoke a web browser (ie, Internet Explorer)
backcopy Reflect the updates on the build directory to the master source on 'ws-axis/site/src'
forrest Create the updated static contents
replace Copy the contents to ws-site/targets/axis directory
build-site (default) Do clean up and all tasks to the build site

For Committers (Highly recommended)

The procedure to make changes to http://ws.apache.org/axis/ is:

  • *cd* into the local 'ws-axis/site' CVS dir
  • execute "ant"
  • make changes to 'build/webapp/content/xdocs'
  • reload and review the contents with the autostarted browser
  • close the browser and the forrest window when you are ready to finish editing the site
  • cvs commit (ie, 'ws-axis/site/src' and 'ws-site/target/axis')

Manual update (If you want to realize the value of ant tasks above ...)

If you just want to update the site step-by-step, the followings are the instructions.

  1. Installing Forrest
    [Note] At this time, the version 0.5.1 of Forrest is tested version.
  2. Checking out 'ws-axis/site' module
    [ex]
    'ws-axis/site/src/documentation/content/xdocs/java/user-guide.ihtml'
  3. Make changes to the target
  4. Confirming the change with "forrest run"
    1. cd into the local "ws-axis/site" CVS dir
    2. execute "forrest run"
    3. have an access to http://localhost:8888/ to see the site
  5. Generating a static content with "forrest"
    1. execute "forrest" in the "ws-axis/site" dir
    2. check the generated contents in "ws-axis/site/build/site/"
  6. Make commitments
    1. commit the original source (xml/ihtml/gif/jpg) to "ws-axis"
    2. copy the generated contents into "ws-site/targets/axis"
    3. commit the generated contents to "ws-site"
  7. (Optional) If you are in a hurry to reflect the change to the site, cd to /www/ws.apache.org, and execute "cvs update -P" on minotaur.

    [Note] *** VERY IMPORTANT ***
    YOU HAVE TO CHECK YOUR UMASK IS "002" BEFORE DOING THE COMMAND, OR THE SITE WILL BECOME A NON-UPDATABLE SITE FROM THEN ON.
    The site will be updated automatically twice a day 12 midnight and 12 noon PST by a cron job of dims.

F.A.Q.

Q1.
I encountered

The <xmlcatalog> data type doesn't support the nested "catalogpath" element.
error, during the build.

A1.
Please make sure that your Ant version is later than 1.6 alpha. You can check the Ant version, by running "ant -version".

Q2.
I see an error like this regarding mirrors.pdf

[java] X [0]  mirrors.pdf BROKEN ....

A2.
This is a known issue, but does not affect the site itself.

( more to be come )

by Toshiyuki Kimura