Project Goanna Installation Instructions ---------------------------------------- This document describes how to install and build the Project Goanna tools and examples. Installation ------------ 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 (http://sourceforge.net/projects/goanna/) in the Latest File Releases section. Download the latest tar file from here an 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 (http://sourceforge.net/cvs/group_id=14711) 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. Source Tree Contents -------------------- 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. Third-party Libraries --------------------- 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 third-party libraries used in Project Goanna include: eXML - XML Parser for Eiffel by Andreas Leitner and Julian Rogers. eXML is a wrapper for the expat library. This also includes the Unicode String library (ucstring). Location: http://sourceforge.net/projects/exml Environement variable: EXML expat - James Clark's expat XML parser. A non-validating fast XML parser with a similar event driven approach as SAX. Location: http://sourceforge.net/projects/expat Environment variable: EXPAT gobo16 - Portable Eiffel libraries and tools by Eric Bezault Location: http://www.gobosoft.com Environment variable: GOBO yaesockets - Portable Eiffel sockets library by Marcio Marchini and Andreas Scholz. Location: http://sourceforge.net/projects/yaesockets Environment variable: YAESOCKETS 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 .lib file. Follow the instructions included with each library. The Ace files and SmallEiffel build files reference any required C libraries in their default locations. Web Server ---------- 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. The web server must support the FastCGI protocol. That is, there must be a server module or plug-in available that implements the FastCGI protocol. Primarily Apache Web Server (http://www.apache.org) and the mod_fastcgi (http:/www.fastcgi.com) combination are used. There is also a FastCGI module for Microsoft Internet Information Server (IIS) but it is not freely available. 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). Web Server Configuration ------------------------ 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, however you may experience problems. 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" SetHandler fastcgi-script Options ExecCGI Allow from all 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 'text.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. Compiling the Tools ------------------- The tools included with Project Goanna include: xmle - XML to Eiffel compiler. Similar to the XMLC compiler provided with the Enhydra framework (http://www.enhydra.org>. XMLE allows you to compile an XML template into an Eiffel representation of the documents DOM objects. bdom_viewer - XMLE creates a binary representation of a DOM in a file. The bdom_viewer allows you to read and serialize any binary DOM file. To build the tools first make sure you have set all of the required environment variables. Next, check the Ace file or loadpath file of the example you are compiling to make sure all paths are correct and any external clauses point to the correct libraries. If building under ISE Eiffel open a new project in the location of the Ace file and build. For SmallEiffel, run the build-se file. Compiling the Examples ---------------------- Exactly the same as building the tools. Check your environment variables and, for each example, compile using the supplied Ace or build-se files.