Previous Up Next

Chapter 2  Installation

This chapter contains the following sections:

2.1  Preliminaries

2.1.1  Platforms

Release 0.5.0 contains one source distribution and binary distributions for: Note: The binary distribution was compiled with O'Caml version 3.08, which is not backward compatible with earlier versions of O'Caml.

The source distribution is intended for Unix platforms with GNU compilers and binary utilities, or Windows platforms with Cygwin or MinGW compilers. There is no port for VC++ compilers or for non-GNU Unix compilers.

This release has been tested successfully with: Others have compiled earlier versions of Galax on: We have tried to isolate all the platform-dependent configuration options in config/Makefile.{unix,macos,mingw}. If you are trying to compile Galax on a new Unix target, you will certainly have to make changes to config/Makefile.unix, but you may also have to edit config/Makefile.gen.

Please send us the configuration options for your port and we will incorporate them into the next release.

2.1.2  General Requirements

Both the source and binary distributions require:
Perl Compatible Regular Expression Library -- PCRE (>= v4.5)
Galax requires the PCRE (Perl Compatible Regular Expression) Library version 4.5 or later. PCRE is standard on many Linux distributions (check your version!) or can be downloaded from: http://www.pcre.org/.

2.2  Source-code Distribution

2.2.1  Source Distribution Requirements

See Section 2.1.2.

We recommend that you install these required tools in order, because there are dependencies. For example, ocamlnet depends upon pcre-ocaml and findlib.
O'Caml (v3.08)
The Objective Caml compiler can be downloaded from: http://caml.inria.fr/. Installing on MacOS: See Section 2.4.4.

findlib (v1.0.4)
The findlib O'Caml library management tool can be downloaded from: http://www.ocaml-programming.de/programming/findlib.html.

pcre-ocaml (v5.09)
The pcre-ocaml O'Caml interface to PCRE library can be downloaded from: http://www.ai.univie.ac.at/ markus/home/ocaml_sources.html.

ocamlnet (v0.98)
The ocamlnet network protocol and string processing library can be downloaded from: http://www.ocaml-programming.de/programming/ocamlnet.html.

Requires: findlib and pcre-ocaml. Installing on all targets: See Section 2.4.

ulex (v0.5)
The lexer generator for Unicode and O'Caml can be downloaded from: http://www.cduce.org/download.html.

Requires: findlib. Installing on MacOS: See Section 2.4.4.

pxp (v1.1.95)
The pxp polymorphic XML parsers can be downloaded from: http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html.

Requires: findlib and ulex. Installing on MacOS: See Section 2.4.4.

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

MinGW can be downloaded from: http://www.mingw.org/.

Cygwin can be downloaded from: http://sourceware.cygnus.com/cygwin/.

GNU Make
The Makefiles for Galax require 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.

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

Java
If you want to compile the Java API, you will need a recent JDK. Galax 0.5.0 has been tested with SUN Java 2, version 1.4. Earlier versions of Galax have been reported to work with IBM(R) Developer Kit Version 1.3.1 and Blackdown Java 4.1 (SDK 1.3).

Jungle
If you are installing the optional Jungle tool -- Galax's secondary storage system for large XML documents (Section 7.2), you will need:
  1. Berkeley DB Version 4.1.25. Berkeley DB comes standard on many Linux distributions (e.g., RH 9.0 or Fedora) or can be downloaded from: http://www.sleepycat.com.
  2. The O'Caml IDL tool. You can download the O'Caml IDL tool from http://caml.inria.fr/camlidl/.

2.2.2  Source Installation

To build Galax from the source distribution:
  1. Copy the appropriate configuration file for your platform:

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

    Windows: cp ./config/Makefile.mingw ./config/Makefile

    Mac: cp ./config/Makefile.macos ./config/Makefile

  2. Edit the configuration file ./config/Makefile and set up your environment:

    Check the following required variables:
    OCAMLHOME
    Objective Caml library directory
    OCAMLBIN
    Objective Caml binaries
    GALAXHOME
    Where to install the Galax system once it has been compiled. Usually $(HOME)/Galax
    CLIBPCRE
    Directory where libpcre.a (version 4.5+) is found. Usually /usr/lib or /usr/local/lib

    Check the following optional variables:
    ENCODINGS
    Default character set is UTF-8, if you want additional encodings, uncomment them.

    OPTTOOLS
    If you are compiling an optional tool, uncomment the optional tool. For example, uncomment OPTTOOLS=jungle if you want to compile Jungle, Galax's secondary storage system. All other (unsupported) optional tools are listed in Makefile_opttools.conf.
    APIS
    Uncomment the APIs, if you want to build them. The O'Caml API is compiled by default.
    CC
    If you want to compile the C API, you should set CC to the C compiler.
    JAVAHOME and JAVAINCLUDE
    If you want to compile the Java API, you should set JAVAHOME to your Java development kit and JAVAINCLUDE to the Java include directory.

    If you are compiling for a Unix platform, uncomment the platform-specfic variables for your target under O/S Dependent Compilation and Linking Variables.

    If you are compiling the optional Jungle tool, uncomment the following:
    BERKELEYDBHOME
    Set to Berkeley DB installation directory, usually /usr/local/BerkeleyDB.4.1.


  3. Compile Galax: In galax/, make world
  4. Install Galax: make install
  5. Check installation:

    In galax/ directory, execute: make tests.

  6. (Optional) Check Jungle installation:

    In galax/examples/jungle directory, edit jungle1.xq and replace directory name by the path to your jungle directory, then execute: make tests.

2.3  Binary Distribution

2.3.1  Binary Distribution Requirements

See Section 2.1.2.
O'Caml (v3.08)
If you plan to use the Galax O'Caml API, you will need the Objective Caml compiler version 3.08. If you don't plan to use the O'Caml API, then you do not need to install O'Caml.

The Objective Caml compilers can be downloaded from: http://caml.inria.fr/. Note: The binary distribution was compiled with O'Caml version 3.08, which is not backward compatible with earlier versions of O'Caml.

GNU Make
The Makefiles for Galax require 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.

gcc
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 guarantee it will work with anything else. Installing on Solaris: See Section 2.4.2.

Java
If you want to compile the Java API, you will need a recent JDK. Galax 0.5.0 has been tested with SUN Java 2, version 1.4. Earlier versions of Galax have been reported to work with IBM(R) Developer Kit Version 1.3.1 and Blackdown Java 4.1 (SDK 1.3). Installing on Solaris: See Section 2.4.2.

2.3.2  Binary Installation

To install Galax, you should:
  1. Uncompress the distribution:

    Windows: unzip Galax-0.5.0-MinGW.zip

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

    MacOS: cat Galax-0.5.0-MacOS.tar.gz | gunzip | tar xvf -

    The directory Galax/ should contain:
    README
    Pointer to documentation
    LICENSE
    Terms of software licence
    bin/
    Command-line tools
    doc/
    This documentation
    examples/
    Galax API examples for calling Galax from Caml, C and Java
    lib/
    Galax libraries
    usecases/
    XML Query Use Cases and XMark benchmark queries


  2. Set up your environment: Edit config/Makefile and initialize variables:
    GALAXHOME
    The Galax directory. Usually $(HOME)/Galax
    OCAMLHOME
    If you are compiling O'Caml API example, the Objective Caml library directory.
    OCAMLBIN
    If you are compiling O'Caml API example, the Objective Caml binaries directory.
    CC
    If you are compiling the C API example, the C compiler.
    JAVAHOME and JAVAINCLUDE
    If you are compiling the Java API example, you should set JAVAHOME to your Java development kit and JAVAINCLUDE to the Java include directory.

    Add $(GALAXHOME)/bin to your PATH.

    Add $(GALAXHOME)/lib/c:$(GALAXHOME)/lib/java to your library path variable (LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on MacOS.

  3. (Optional) Check installation:

    In $(GALAXHOME)/usecases execute: make all

    In $(GALAXHOME)/examples execute: make all

2.4  Operating-System Installation Notes

2.4.1  Linux

ocamlnet

If you have compiled O'Caml with no shared libraries, you will get an error when compiling ocamlnet, because the src/netstring/tools/unimap_to_ocaml/unimap_to_ocaml executable is a pre-compiled ocamlrun (bytecode) executable that assumes O'Caml supports shared libraries.

Remove src/netstring/tools/unimap_to_ocaml/unimap_to_ocaml, remake in that directory, then proceed with compilation and installation.

2.4.2  Solaris

2.4.3  APIs

The Solaris implementation requires gcc and the GNU binary utilities. If your gcc compiler is configured to invoke the native binary utilities (e.g., as, ld, etc.) and not the GNU utilities, you need to set up your environment so gcc will use the GNU utilities. Set $LD_LIBRARY_PATH to gcc library directory and $GCC_EXEC_PREFIX to the gcc binary utilities directory.

2.4.4  MacOS

O'Caml:

We recommend that when you configure the O'Caml compiler, use the -no-shared-libs options, which means that the O'Caml compiler will only create static libraries.

If you get linking errors when compiling the C API, you may have to rebuild your O'Caml compiler using the -fno-common compiler option. Edit your O'Caml config/Makefile and add -fno-common to BYTECCCOMPOPTS and NATIVECCCOMPOPTS.

ocamlnet

If you have compiled O'Caml with no shared libraries, you will get an error when compiling ocamlnet, because the src/netstring/tools/unimap_to_ocaml/unimap_to_ocaml executable is a pre-compiled ocamlrun (bytecode) executable that assumes O'Caml supports shared libraries.

Remove src/netstring/tools/unimap_to_ocaml/unimap_to_ocaml, remake in that directory, then proceed with ocamlnet compilation and installation.

If you get errors from ocamlfind, try:

ocamlopt -o unimap_to_ocaml $(OCAMLHOME)/str.cmxa unimap_to_ocaml.ml

I had to generate unimap_to_ocaml by hand, because ocamlfind did note find str.cmxa correctly.

pxp

I was not able to build PXP successfully using the wlex and ulex lexers and all the character encodings. Instead, I configured PXP with just two character encodings and the standard lexers:

./configure -without-wlex -without-ulex -lexlist utf8,iso88591 -without-pp

Then proceed with compilation and installation.

2.4.5  Windows

2.5  Web-site Interface

The Galax website and on-line demo is in the source distribution, only.

2.5.1  Prerequesites for demo website

The Galax website has only been tested with Apache Web server. We recommend you use Apache as some of the CGI scripts might be sensitive to the server you are using. Apache can be downloaded from: http://www.apache.org/

2.5.2  Installation of Website Interface

  1. Edit website/Makefile.config and initialize 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 world
  3. Install the web site and demo scripts: 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 /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. 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), 
      <DirectoryMatch "^/home/[^/]+/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.
Previous Up Next