Galax Manual: Installation

# Chapter 2 Installation

This chapter contains the following sections:

- Prerequisites (Section 2.1) : prerequisites for Galax installation.
- Source Distribution (Section 2.2) : Installation instructions for the source distribution.
- Running the W3C XQuery Test Suite (XQTS) (Section 2.3).
- Web-form interface (Section 2.4) : installation instructions for Galax’s web-form interface.

## 2.1 Prerequisites

- PCRE 5.0 or higher is required. If you do not have PCRE version 5.0 or higher1 installed.
- (Optional) If you plan to use Jungle, Galax’s secondary storage manager, you will need Berkeley DB version 4.4 or higher2 installed.

## 2.2 Source Installation

There are two methods for installing Galax from source:

1. RECOMMENDED METHOD: Use GODI installation and configuration tool to automatically install Galax and all the libraries on which it depends.
2. Install Galax and the libraries on which it depends manually.

   This method may be preferable if you are an OCaml user, already have an installation of OCaml and its libraries, and do not want to install a new version of OCaml. Even if you are already an OCaml user, the first method is always recommended.

### 2.2.1 Installing Galax using GODI installation and configuration tool

Warning: Installing packages using GODI is an ON-LINE process, so preferably, you should be connected to the Net by a fast, hard-wire connection.

1. Download GODI from : `http://godi.ocaml-programming.de/`

   Follow GODI installation instructions through "bootstrap_stage2" command, adding the
   `<godi-prefix-path>/bin` and `<godi-prefix-path>/sbin` directories to your PATH as instructed.

   Note: For OCaml users, after GODI bootstrapping phase, the OCaml executables are located in `<godi-prefix-path>/bin` and the OCaml libraries are located in `<godi-prefix-path>/lib/ocaml`.

2. Run `godi_console`
   1. Select `conf-pcre` package (Packages are listed in alphabetical order.)

      Select [b]uild & install, then e[x]it.

      GODI will give you the PCRE library configure options:

                  [ 1] GODI_BASEPKG_PCRE = no
                  [ 2]  GODI_PCRE_INCDIR =
                  [ 3]  GODI_PCRE_LIBDIR =

      Select 2 to set the path to the directory containing pcre.h (version 5.0 or higher).

      Select 3 to set the path to the directory containing libpcre.a (version 5.0 or higher).

      Select e[x]it twice to return to the main menu.

   2. (Optional) If you are planning to include support for Jungle, Galax’s secondary storage manager, then select `conf-bdb`.

      Select [b]uild & install, then e[x]it.

      GODI will give you the BDB library configure options:

                  [ 1] GODI_BDB_INCDIR =
                  [ 2] GODI_BDB_LIBDIR =

      Select 1 to set the path to the directory containing db.h. (version 4.4 or higher).

      Select 2 to set the path to the directory containing libdb.a (version 4.4 or higher).

      Select e[x]it twice to return to the main menu.

   3. Select `godi-galax` package.

      Select [b]uild & install, then e[x]it.

      This will add all of Galax’s dependencies to your GODI configuration. GODI will give you Galax’s configure options:

            [ 1] GODI_GALAX_INCLUDE_JUNGLE = no
            [ 2]  GODI_GALAX_INCLUDE_C_API = no
            [ 3] GODI_GALAX_INCLUDE_JAVA_$ = no
            [ 4]   GODI_GALAX_INCLUDE_UTF8 = yes
            [ 5] GODI_GALAX_INCLUDE_ISO88$ = yes
            [ 6]      GODI_GALAX_JAVA_HOME = unset
            [ 7]       GODI_GALAX_JAVA_BIN = unset
            [ 8]   GODI_GALAX_JAVA_INCLUDE = unset
            [ 9] GODI_GALAX_REGRESSION_SU$ = unset

      You can change the default Galax configuration as follows:

      Select 1 to include Jungle, Galax’s secondary storage manager.

      Select 2 to include Galax’s C API.

      Select 3 to include Galax’s Java API (requires the C API).

      Select 4(5) to exclude UTF8(ISO88) character set (reduces sizes of executables).

      Select 6(7,8) to set the Java home(bin,include) directories.

      Select 9 to set directory where XQuery 1.0 test suite is installed.

      Select e[xi]t.

      Select [s]tart/continue, which will report all dependencies.

      Then select [s]tart/continue, which will report actual dependencies based on your current GODI installation.

      Then select [o]k.

3. Take a long coffee break...while GODI downloads and installs packages.
4. Finish

   Add `<godi-prefix-path>/bin` to your `PATH`.

   When installation has completed, Galax will be installed in `<godi-prefix-path>/` with the following subdirectories:

   Directory | Sub-directory | Content
   `bin/` |  | Galax’s command-line executables
   `lib/` |  |
   | `pervasive.xq` | Signatures of XQuery 1.0 Function and Operators
   | `c/` | C libraries and API header files
   | `java/` | Java libraries and API interfaces
   | `ocaml/pkg-lib/galax/` | OCaml libraries and interfaces
   `share/galax/` |  |
   | `examples/` | Examples of using C, Java, and OCaml APIs
   | `regress/` | Test harness and configuration for the W3C XQuery Test Suite
   | `usecases/` | XQuery 1.0 usecases

### 2.2.2 Installing Galax source by hand

If you already have an OCaml installation, you can install the Galax source by hand. To do so, you need the following versions of the OCaml compiler and libraries, and C libraries:

Library | Version | GODI-Package
OCaml compiler3 | 3.10 | godi-ocaml
OCaml Libraries
findlib4 | 1.1.2pl1 | godi-findlib
Pcre-ocaml5 | 5.12.2 | godi-pcre
Ocamlnet6 | 2.2.8.1 | godi-ocamlnet
Caml IDL7 | 1.05 | godi-camlidl
PXP8 | 1.2.0test1 | godi-pxp
Camomile9 | 0.7.1 | godi-camomile
C Libraries
Berkeley DB (libdb) | 4.3 | Only for Jungle
PCRE | `>`4.5 |

1. Download Galax source from .
2. Unzip and untar Galax in a directory of your choice. `gunzip galax-1.0.tar.gz`

   `tar xvf galax-1.0.tar`

3. Configure Galax.

   From the `galax/` you just created, run:

   `./configure -galax-home $GALAXHOME`

   Where `$GALAXHOME` is the target installation directory.

   If you want the C API, add `-with-c`.

   If you want the Java API, add `-with-java -java-home <Top-level Java directory>`.

   The configure script will try to find your OCaml installation and other necessary libraries by itself. Review the default configuration before proceeding. If you need to change the default configuration, run `./configure -help` for all options.

4. Build Galax.

   In `galax/` run:

   `make world`

   Go get more coffee...

5. Install Galax.

   In `galax/` run:

   `make install`

6. Finish

   Add `$GALAXHOME/bin` to your `PATH` environment variable.

   When installation has completed, Galax will be installed in `$GALAXHOME` with these subdirectories:

   Directory | Content
   `bin/` | Command-line executables
   `examples/` | Examples of using C, Java, and OCaml APIs
   `regress/` | Test harness and configuration for the W3C XQuery Test Suite
   `usecases/` | XQuery 1.0 usecases

## 2.3 XQuery Test Suite

The Galax distribution includes a test harness for the W3C XQuery tests suite. It can be run by following the steps listed below.

1. Download and install the XQuery Test Suite. The latest version of the XQuery Test Suite can be found on the W3C XQuery Web page at the following address:

   `http://www.w3.org/XML/Query/test-suite/`

   The Test Suite comes as a `zip` archive, which can be unzipped in a directory of your choice (We use `$XQTS` in the following instructions).

2. Configure Galax’s test harness. If you followed the GODI installation path, you need to select option 9 as indicated above to specify the directory in which the test suite has been installed. If you followed the “by hand” installation path, you must specify the directory in which the test suite has been installed using the following configure option:

       -regression $XQTS

3. Run the test suite. You can run the test suite by calling:

   `make`

   from the `$GALAXHOME/regress` directory. This will produce a file called:

   `testresults-W3C.xml`

   which contains the result of running the test suite (following the format required for test results by the XQTS).

4. Generate a test suite summary. The XQTS distribution contains an XSLT style sheet which can be used to produced a summary of the test results in HTML form. The corresponding style sheet is located in the directory:

       $XQTS/ReportingResults

   The stylesheet can be run by:
   1. Specifying the path to the test results obtained from the previous step in the configuration file:

          $XQTS/ReportingResults/Results.xml

      as follows:

          <results>
             <result>$GALAXHOME/regress/testresults-W3C.xml</result>
          </results>

   2. Changing to the directory:

          $XQTS/ReportingResults/Results.xml

      and running one of the two following commands (you will need a working installation of ant, and of an XSLT processor):

          ant -f Build.xml create
          ant -f Build.xml createsimple

      which should respectively produce the following HTML files:

          XQTSReportSimple.html
          XQTSReport.html

## 2.4 Web Site Interface

The Galax Web site and on-line demo are bundled with the source distribution (only).

### 2.4.1 Prerequisites

The Galax Web site has only been tested with Apache Web servers. We recommend you use Apache as some of the CGI scripts might be sensitive to the server you are using. Apache is commonly installed with most Linux distributions, or can be downloaded from: `http://www.apache.org/`.

### 2.4.2 Installation of Website Interface

1. From the source directory, edit `galax/website/Makefile.config` and initialize the following variables:
   `WEBSITE`
     Location of the Apache directory for Galax.
   `CGIBIN_PREFIX`
     Prefix of directory that may contain CGI executables. If empty, then they are placed in `WEBSITE`.
2. Compile the the demo scripts: `make`
3. Install the web site and demo scripts: `sudo make install`
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 proper `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. The Galax demo is available at `http://localhost/galax`.
5. OR Configure 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),

         AddHandler cgi-script .cgi
         <DirectoryMatch "/galax/cgi-bin">
           AllowOverride AuthConfig
           Options ExecCGI
           SetHandler cgi-script
         </DirectoryMatch>

   In that case, simply follow the comments in `website/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.

1
  `http://www.pcre.org/`
2
  `http://dev.sleepycat.com/downloads/releasehistorybdb.html`
3
  `http://caml.inria.fr/ocaml/release.en.html`
4
  `http://www.ocaml-programming.de/packages/findlib-1.1.2pl1.tar.gz`
5
  `http://www.ocaml.info/ocaml_sources/pcre-ocaml-5.12.2.tar.gz`
6
  `http://www.ocaml-programming.de/packages/ocamlnet-2.2.8.1.tar.gz`
7
  `http://caml.inria.fr/pub/old_caml_site/distrib/bazar-ocaml/camlidl-1.05.tar.gz`
8
  `http://www.ocaml-programming.de/packages/pxp-1.2.0test1.tar.gz`
9
  `http://prdownloads.sourceforge.net/camomile/camomile-0.7.1.tar.bz2`