This document describes how to install and build the Project Goanna tools and examples.

You can install Project Goanna using a pre-packaged tar file or by checking out the latest source from its CVS repository at SourceForge.

A pre-packaged installation will normally give you a more stable version than a checkout from CVS. Tar files are created at every major milestone of the project and represent a tested release.

Pre-packaged tar files are available from SourceForge in the Downloads section. Download the latest tar file from here and extract into a directory of your choice.

If you wish to use the latest source from CVS follow the instructions on the Project Goanna CVS page for Anonymous CVS Access.

Due to a few limitations of CVS, and a major restructuring of the source tree, you may end up with a number of empty directories when you checkout the source. If you execute:

cvs update -Pd

these directories will be removed. You can also add the -P option to the initial checkout command.

Once installed, create an environment variable named GOANNA that points to the root directory of the installation.

The Project Goanna source tree contains the following top level directories:

• doc - documentation (including this file)
• library - library class texts
• examples - example applications and test harnesses for the library
• tools - Project Goanna tools including XMLE and BDOM viewer.

Installation of Project Goanna requires a number of third party Eiffel libraries to be installed and built. Each distinct library is reverenced using an environment variable that points to the
top level directory of the library.

The following table lists the third-party libraries used by Goanna

If the library includes C (or other external language source) then it must be compiled into an appropriate library for the platform you are working on. For example, under Windows you will need to compile the expat C code into a .obj file. Follow the instructions included with each library.

The build files for Goanna reference all required C libraries in their default locations.

Project Goanna provides a framework and environment for building dynamic internet applications and requires a web server to act as a front-end request processor. If you need to use a third-party web server, such as Apache, then you must use the FastCGI protocol to connect to Goanna. FastCGI modules are available for both Apache and IIS (not freely available). Primarily Apache Web Server and the mod_fastcgi combination are used.

To build mod_fastcgi for Apache, follow the instructions provided with the package. If building on Unix, make sure you have the Apache development libraries installed (ie, the apache-devel RPM module on RedHat Linux).

You can also use the Eiffel HTTP server that is provided with Goanna. This is the combination recommended for development and testing because it is simple to setup and everything is written in Eiffel. However, at this stage, it is not recommended that applications be deployed using the Goanna HTTP server because it does not provide any authentication facilities and has not been thoroughly tested.

NOTE: The following section describes configuration of Apache on Unix only. If you are using another server/FastCGI combination let us know what you had to do to get it going.

NOTE: The reason we currently use the Unix version of mod_fastcgi in Apache is because the Windows beta version of mod_fastcgi is very buggy. You may have success with a more recent version.

Once the FastCGI module is built and installed, you need to configure Apache so that it knows about your FastCGI applications.

Currently, the Project Goanna FastCGI implementation only supports external FastCGI servers. This is actually a good thing because it allows you to run your servers within your chosen IDE (ie, with a debugger!).

The simplest way to configure external FastCGI servers is to set up an alias and a FastCGI script directory. You will need the following lines in the httpd.conf file:

LoadModule fastcgi_module modules/mod_fastcgi.dll
Alias /fcgi-bin "/home/apache/fcgi-bin"

<Directory "/home/apache/fcgi-bin">
SetHandler fastcgi-script
Options ExecCGI
Allow from all
</Directory>

The configuration lines above load the FastCGI module, create an alias /fcgi-bin to the directory /home/apache/fcgi-bin and set the handler and permissions on that directory.

For each external server you run, you need to add a line similar to the following:

FastCgiExternalServer "/home/apache/fcgi-bin/test.exe -host localhost:8000

The name test.exe is just symbolic. For an external server it does not need to physically exist. The -host parameter can point to any host and any port. Configure this parameter to suit where you will be running the external server.

You can also add additional parameters to this line to adjust timeout values and so on. Refer to the mod_fastcgi documentation for more information.