
                     Galax: An XQuery 1.0 Implementation
                     -----------------------------------
                             INSTALLATION NOTES
                     
** Galax Release: 0.3.5
December 2003

INDEX
=====
  I. PRELIMINARIES
 II. COMPILING FROM THE SOURCE
III. BINARY VERSIONS
 IV. THE WEBSITE & DEMO (Forms-based interface to Galax)

I. PRELIMINARIES
================

I.1 Platforms
-------------

  Release 0.3.5 comes in a source form or in a binary form.

  The source form is intended for Unix platforms with GNU compilers,
  or Windows platforms with Cygwin or MinGW compilers. There is no
  port for VC++ compilers at this point.

  The binary form comes as a set of standalone precompiled executables
  and libraries. Currently available architectures includes:
    * Linux Redhat 7.0+
    * Win32 (Win98, Win2000, NT) [Compiled using ocaml-3.06 and MinGW]
    * Solaris/SunOS 5.8

  This release has been effectively tested under:
    * Linux i686, Red Hat Linux 7.2, with gcc 2.96
    * Solaris/SunOS 5.8
    * Windows 2000, with MinGW compilers
    * Windows 1998, with MinGW compilers


I.2 Prerequisites
-----------------

  You do not need anything for using the binary form, you can go
  directly to III. below.

  If you are installing from the source, you will need the Objective
  Caml compiler and basic unix tools (notably make and sed).

   * Galax has been tested with Objective Caml version 3.04 and
     3.06. The Objective Caml compilers can be found at:

       http://caml.inria.fr/

   * If your target platform is Windows, you will need to compile
     Objective Caml from its source under MinGW or Cygwin.

        http://www.mingw.org/
        http://sourceware.cygnus.com/cygwin/

   * The Makefiles in galax assume you are using GNU make. If your
     Unix platform's default make, or the make in your default $PATH
     is not GNU make, then your need to make sure GNU make is
     installed on your system and use it instead.

   * If you want to compile the C API, you will need a C
     compiler. Galax has only been tested with recent versions of gcc,
     so there is no guarantees it will work with anything else
     (although it has also been reported to work with Solaris standard
     compiler).

   * If you want to compile the Java API, you will need a recent
     JDK. This has been reported to work with IBM(R) Developer Kit
     Version 1.3.1., SUN Java 2 1.4, and Blackdown Java 4.1 (SDK
     1.3). 

I.3 Documentation
-----------------

For more details about how Galax aligns with various specifications,
see ./STATUS.

For changes made in current release, see ./RELEASE_NOTES.

For open & closed bugs, see ./Bugs.

For info on Galax's APIS, see ./README_API or galapi/README.


II. COMPILING FROM THE SOURCE
=============================

To compile Galax from its source you should:

  1. Configure the system. For that,

     1.a) copy the right configuration file for your platform,

       Unix:
     	  cp ./config/Makefile.unix ./config/Makefile
  
       Windows:
     	  cp ./config/Makefile.win ./config/Makefile

     1.b) edit the configuration file, e.g.,

          emacs ./config/Makefile

       which contains a number of variables that you should
       check/set.

       * You should check at least the following variables:
  
       	  OCAMLHOME   (should point to the Objective Caml library directory)
       	  OCAMLBIN    (should point where to find Objective Caml binaries)
   
          GALAXHOME   (where to install the Galax system once it has
                       been compiled)

       * Default character set is UTF-8, if you want something
         different, you should check:

         ENCODINGS    (which character encoding(s) should be supported)

       * If you are using the APIS, you should check: 
          APIS        ("c" and/or "java")
          OPTAPIS     ("c" for native code implementation)

       * If you want to compile the C API, you should check:
  
          CC          (which C compiler to use)
          CPP	      (which C++ compiler to use)
       	
          WITH_CLIBS  (Additional C libraries to compile the C API)

       * If you want to compile the Java API, you should check:
  
          JAVAHOME    (where is your Java development kit)
          JAVAINCLUDE (Java include files)

  2. Compile the Galax engine:

          make world

  3. Install galax to its selected target location:

          make install

  4. (Optional) You can run all of the use cases, to check that
     everything went well. -- Note, this takes some time to run.

          make usecases


III. BINARY VERSIONS
====================

To install Galax, you should:

  1. Uncompress the distribution:

  Windows:
    unzip Galax-0.3.5-Win32.zip

  Linux:
    cat Galax-0.3.5-Linux.tar.gz | gunzip | tar xvf -

  Solaris:
    cat Galax-0.3.5-Solaris.tar.gz | gunzip | tar xvf -

  The directory Galax/ should contains:

    INSTALL        Installation instructions (this file)
    LICENSE        Terms of software licence
    README         About Galax
    README_API     About Galax APIs
    RELEASE_NOTES  Changes in current release.
    STATUS         Detailed documentation on alignment of Galax with
                   W3C specs and additional Galax features.
    bin/           Command-line tools
    lib/           Galax libraries
    usecases/      XML Query Use Cases and XMark benchmark queries

  2. Add the directory where Galax/bin is installed to your path so
     that executables in Galax/bin are found. 

  3. Read usecases/README to learn how to run the usecases.

IV. THE WEBSITE & DEMO (Forms-based interface to Galax)
======================

  The Galax website and on-line is distributed in the source distribution.

IV.1 PREREQUESITES FOR WEBSITE/DEMO
-----------------------------------

  This demo has only been tested with apache Web server. We recommend
  you use it as some of the CGI scripts might be sensitive to the
  server you are using. Apache can be downloaded from:

  * http://www.apache.org/

IV.2 INSTALLATION OF WEBSITE/DEMO
---------------------------------

  1. Configure the demo:

     cd website 
     edit Makefile.config

  2. Compile the the demo scripts:

     make depend
     make all
     make opt

  3. Install the scripts:

     make install

  Next, you can will either configure your own Apache server (see 4)
  or put the demo files into appropriate places on a system that
  already have a configured Apache server that can execute CGI
  programs (see 5).

  4. Configure your own Apache server:

     If all the galax demo files (HTML, XML and CGIs) are placed in
     one directory where the HTTP daemon is expecting to find them,
     then it is necessary to add the following config info to the
     /etc/httpd/conf/http.conf file:

     <Directory "/var/www/html/galax">
	 Options All
	 AllowOverride None
	 AddHandler cgi-script .cgi 
	 Order allow,deny
	 Allow from all
     </Directory>

     This permits scripts with suffix .cgi in /var/www/html/galax to
     be executed.

     Now your galax demo is at URL: http://localhost/galax

  5. Configure for an existing multi-user Apache server.

     Your sysadmin may already have set up an Apache server for
     general use, and allows CGI programs by any user.  You can
     verify by finding directives similar to the following in
     httpd.conf (wherever it might be located on your system),

	<DirectoryMatch "^/home/[^/]+/cgi-bin">
	AllowOverride AuthConfig
	Options ExecCGI
	SetHandler cgi-script
	</DirectoryMatch>

     In that case, simply follow the comments in Makefile.config to
     choose installation destinations for your cgi programs and the
     html documents should suffice.  The url for accessing the
     installed site will depend on how your webserver is set up.
     Consult your sysadmin or webadmin for further help.
     

