source: trunk/docs/kernel/installation.txt @ 233

.. _kernel-installation:

Installation
============

.. contents:: Table of Contents
    :depth: 4
    :backlinks: top

This page provides documentation on how to compile then install the ZOO Kernel on Unix and Win32 platforms.

Obtaining the ZOO Kernel Source
-------------------------------

Use the following command to get the ZOO Kernel source code through Subversion:

::

  svn checkout http://svn.zoo-project.org/svn/trunk zoo-project

For users which get a developer account, use the following:

::

  sed "s:\[tunnels\]:\[tunnels\]\nzoosvn = /usr/bin/ssh -p 1046:g" -i ~/.subversion/config
  svn co svn+zoosvn://svn.zoo-project.org/var/svn/repos/trunk zoo-project

The first line of the instruction above defines a specific tunnel to access the svn server through 
the SSH protocol. Indeed, the ZOO SVN server listens on the 1046 (1024+22) port rather than the default one (22).

Prerequisites
-------------

The following libraries are required on your system before you can install the ZOO Kernel:

- autoconf (  http://www.gnu.org/software/autoconf/ ) 
- cgic (  http://www.boutell.com/cgic )
- cURL (  http://curl.haxx.se )
- FastCGI (  http://www.fastcgi.com )
- Flex & Bison (  http://flex.sourceforge.net/  http://www.gnu.org/software/bison/ )
- libxml2 (  http://xmlsoft.org )
- OpenSSL (  http://www.openssl.org )
- Python (  http://www.python.org )

Optional libraries include:

- PHP Embedded (optional) (  http://www.php.net )
- Java SDK (optional) (  http://java.sun.com )
- SpiderMonkey (optional) (  http://www.mozilla.org/js/spidermonkey/ ) 

Compile libcgic
---------------

The first step is to compile libcgic from the ``zoo-project/thirds`` directory. For such a task, please use 
the following command:

::

  cd thirds/cgic206
  make

Make sure that a ``libcgic.a`` is created in your ``zoo-project/thirds/cgic206`` directory. If yes, then 
you can go to the next step.

On Windows, rather than using the make command, please use:

::

  nmake /f makefile.vc. 
  
.. warning::
   If you don't compile libcgic first, and try to compile the ZOO Kernel, you will get an error such as *cannot find -lcgic*

Unix
----

For Unix users, the ZOO Kernel comes with a GNU autoconf "configure" script that should take care of (hopefully!) 
all compilation issues for you.

The configure script won't work on Windows. See section :ref:`WIN32 <win32>` for details on compiling 
on Windows systems. 

For the impatient
*****************

To build the ``zoo_loader.cgi`` CGI program with the default options, cd to the directory 
where you extracted the ZOO Kernel source code package and use the following commands:

::

  $ cd zoo-kernel
  $ autoconf  
  $ ./configure
  $ make

Unless something went wrong, you should have executables in the current directory for the ``zoo_loader.cgi`` 
CGI program. You can copy the ``zoo_loader.cgi`` program and the ``main.cfg`` file to your HTTP server's CGI 
directory and start using it.

At this step your ZOO-Kernel should work. Nevertheless, don't forget to correct the main.cfg settings 
to set ``tmpPath`` and ``tmpUrl`` to fit your web server configuration.

Configure Options
*****************

Here is the list of available options as returned by *./configure --help*:

::

  --with-gdal-config=FILE specify an alternative gdal-config file
  --with-xml2config=FILE  specify an alternative xml2-config file
  --with-python=PATH      To enable python support or specify an alternative
                          directory for python installation, disabled by
                          default
  --with-php=PATH         To enable php support or specify an alternative
                          directory for php installation, disabled by default
  --with-perl=PATH        To enable perl support or specify an alternative
                          directory for perl installation, disabled by default
  --with-java=PATH        To enable java support, specify a JDK_HOME,
                          disabled by default
  --with-js=PATH          specify --with-js=path-to-js to enable js support,
                          specify --with-js on linux debian like, js support
                          is disabled by default

All the options are described in more details below.

(Required) GDAL Support
^^^^^^^^^^^^^^^^^^^^^^^

If your gdal-config program is not found in your PATH then you can use the 
``--with-gdal-config`` option to specify its location. For instance, let's suppose that your gdal-config 
was installed in /usr/local/bin and this directory is not in your PATH, then you can use 
the following command:

::

  $ ./configure --with-gdal-config=/usr/local/bin/gdal-config

(Required) XML2 Support
^^^^^^^^^^^^^^^^^^^^^^^

If your xml2-config program is not found in your PATH then you can use the 
``--with-xml2config`` option to specify its location. For instance, let's suppose that 
your xml2-config was installed in /usr/local/bin and this directory is not in your PATH, 
then you can use the following command:

::

  $ ./configure --with-xml2config=/usr/local/bin/xml2-config

(Optional) Python Support
^^^^^^^^^^^^^^^^^^^^^^^^^

If you want to activate Python support for the ZOO Kernel then you will have to use the 
``--with-python`` option. If your python-config program is found in your PATH then you 
don't have to specify the path where Python was installed, such as:

::

  $ ./configure --with-python

This assumes that python-config is found in your PATH.

In the case that your python-config is not found in your PATH, then you can specify the Python 
installation directory you are using. For instance, let's suppose that you installed 
Python in /usr/local, then you can use the following command:

::

  $ ./configure --with-python=/usr/local

This assumes that /usr/local/bin/python-config exists.

(Optional) PHP Support
^^^^^^^^^^^^^^^^^^^^^^

To be able to activate PHP support for the ZOO Kernel you'll need to get a local PHP Embedded 
installation; for more information about the required configure options when compiling PHP you 
can refer to this page :

     http://zoo-project.org/trac/wiki/ZooKernel/Embed/PHP

If you want to activate the PHP support for the ZOO Kernel then you will have to use the 
``--with-php`` option. If your php-config program is found in your PATH then you don't have 
to specify the path where PHP was installed, then you can use the following commnd:

::

  $ ./configure --with-php

This assumes that php-config is found in your PATH.

In the case that your php-config is not found in your PATH, then you can specify the PHP installation 
directory you are using. For instance, let's suppose that you installed PHP in /usr/local, 
then you can use the following command:

::

  $ ./configure --with-php=/usr/local

This assumes that /usr/local/bin/php-config exists.

(Optional) Perl Support
^^^^^^^^^^^^^^^^^^^^^^^

If you want to activate Perl support for the ZOO Kernel then you will have to use the 
``--with-perl`` option. If you do not set any value to this option, then the perl program will 
be searched in your PATH. So in such a case, you can use the following command:

::

  $ ./configure --with-perl 

This assumes that perl is found in your PATH.

In the other case, for custom Perl installations, you can set the installation directory. For instance, 
let's suppose that you installed Perl in /usr/local and /usr/local/bin is not in your PATH, 
then you can use the following command:

::

  $ ./configure --with-perl=/usr/local

This assumes that /usr/local/bin/perl exists.

(Optional) Java Support
^^^^^^^^^^^^^^^^^^^^^^^

If you want to activate Java support for the ZOO Kernel then you will have to use the 
``--with-java`` option and set the installation path of your Java SDK. For instance, 
let's suppose that your Java SDK was installed in the /usr/lib/jvm/java-6-sun-1.6.0.22/ directory, 
then you can use the following command:

::

  $ ./configure --with-java=/usr/lib/jvm/java-6-sun-1.6.0.22/

This assumes that the include/linux and jre/lib/i386/client/ subdirectories exist in 
/usr/lib/jvm/java-6-sun-1.6.0.22/, include/linux contains the jni.h headers file and 
jre/lib/i386/client/ contains the libjvm.so file.

.. note:: 
   With Mac OS X you only have to set ``macos`` as the value for the ``--with-java`` option 
   to activate Java support. For example:

   ::

     $ ./configure --with-java=macos

(Optional) JavaScript Support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you want to activate JavaScript support for the ZOO Kernel then you will have to use 
the ``--with-js`` option. If you are using a "Debian-like" GNU/Linux distribution then 
dpkg will be used to detect if the required packages are installed and you don't have to 
specify anything here, so you can use the following command:

::

  $ ./configure --with-js 

This assumes that js_api.h and libmozjs.so are found in default directories.

If you have a custom installation of SpiderMonkey or you are not using a Debian packaging 
system, then you'll have to specify the directory where you installed it. For 
instance, let's suppose that you installed your SpiderMonkey in /usr, then you'll 
have to use the following command:

::

  $ ./configure --with-js=/usr

This assumes that the /usr/include/js exists and contains the js_api.h headers file and 
/usr/lib contains libmozjs.so file.

.. _win32:   

OpenSUSE
********

Zoo-Kernel is maintained as a package in `OpenSUSE Build Service (OBS) <https://build.opensuse.org/package/show?package=zoo-kernel&project=Application%3AGeo>`__. 
This way, rpm's are provided for all versions of openSUSE Linux (11.2, 11.3, 11.4, Factory).

Stable Releases
^^^^^^^^^^^^^^^

For installing Zoo-Kernel in openSUSE there are 3 ways available:

One Click Installer
###################

One-click installer that can be found  `here <http://software.opensuse.org/search?q=zoo-kernel&baseproject=openSUSE%3A11.4&lang=en&exclude_debug=true>`__. 
For openSUSE 11.4 this is the direct `link <http://software.opensuse.org/ymp/Application:Geo/openSUSE_11.4/zoo-kernel.ymp?base=openSUSE%3A11.4&query=zoo-kernel>`__.

Yast Software Manager using a GUI
#################################

The `Application:Geo <http://download.opensuse.org/repositories/Application:/Geo/>`__ repository has to be added 
to the Software Repositories and then Zoo-kernel can be found in Software Management through search.

Command line (as root for openSUSE 11.4)
########################################

::

  zypper ar http://download.opensuse.org/repositories/Application:/Geo/openSUSE_11.4/
  zypper refresh
  zypper install zoo-kernel

Unstable Version
^^^^^^^^^^^^^^^^

The latest development version of ZOO-Kernel can be found in OBS under the project `home:tzotsos <https://build.opensuse.org/project/show?project=home%3Atzotsos>`__. 
ZOO-Kernel packages are maintained and tested there before being released to the Application:Geo repository.

Installation methods are identical as the stable version. Make sure to use `this <http://download.opensuse.org/repositories/home:/tzotsos/>`__ repository instead.

Command line installation (as root for openSUSE 11.4)
#####################################################

::

  zypper ar http://download.opensuse.org/repositories/home:/tzotsos/openSUSE_11.4/
  zypper refresh
  zypper install zoo-kernel
  zypper install zoo-kernel-grass-bridge

Additionally, there is the option of adding the zoo-wps-grass-bridge package. This option will automatically install grass7 (svn trunk).

Try the Installation
^^^^^^^^^^^^^^^^^^^^

- http://localhost/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=GetCapabilities&Version=1.0.0
- http://localhost/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=DescribeProcess&Version=1.0.0&Identifier=HelloPy
- http://localhost/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=Execute&Version=1.0.0&Identifier=HelloPy&DataInputs=a=myname

CentOS
******

.. note::
   This documentation was created thanks to Guillaume Sueur from Neogeo Technologies which took time to test 
   installing the ZOO-Kernel on a CentOS 5.5 environment.

Requirements
^^^^^^^^^^^^

Install some standard tools to be able to run ZOO-Kernel on your platform :

::

  yum install apache2
  yum install build-essentials
  yum install gcc-c++
  yum install zlib-devel
  yum install libxml2-devel
  yum install bison
  yum install openssl 
  yum install python-devel
  yum install subversion

Compile then install FastCGI library from source

::

  wget http://www.fastcgi.com/dist/fcgi.tar.gz
  tar xzf fcgi-2.4.0.tar.gz 
  ./configure
  make
  make install
  echo /usr/local/lib >> /etc/ld.so.conf.d/local.conf
  ldconfig

Compile then install the autoconf tools :

::

  wget http://ftp.gnu.org/gnu/autoconf/autoconf-latest.tar.gz
  tar xzf autoconf-latest.tar.gz
  ./configure --prefix=/usr
  make 
  make install

Compile then install the flex tool :

::

  wget http://downloads.sourceforge.net/project/flex/flex/flex-2.5.35/flex-2.5.35.tar.gz?r=http%3A%2F%2Fflex.sourceforge.net%2F&ts=1292529005&use_mirror=switch
  tar xzf flex-2.5.35.tar.gz
  cd flex-2.5.35
  ./configure --prefix=/usr
  make
  make install

Using the curl provided in the CentOS distribution will produce a ZOO-Kernel unable to run any 
Service. Indeed, some segmentation faults occur when trying to run ``Execute`` requests on the ZOO-Kernel, 
compiling the ZOO-Kernel setting ``USE_GDB`` flag in the ``CFLAGS`` of your ``Makefile`` will let you run 
ZOO-Kernel from gdb and be able to get more information on what is going wrong with your ZOO-Kernel. 
Doing this we can figure out that code on `line 173 <http://zoo-project.org/trac/browser/trunk/zoo-kernel/ulinet.c#L173>`__ 
and `line 175 <http://zoo-project.org/trac/browser/trunk/zoo-kernel/ulinet.c#L175>`__ have to be commented in the 
``ulinet.c`` file to get a ZOO-Kernel working using the curl available in CentOS (curl version 7.15.5). 
If you don't apply the modification, you will get an error from a gdb session pointing 
segfault in ``Curl_cookie_clearall``.

You can optionally compile then install curl from source :

::

  wget http://curl.haxx.se/download/curl-7.21.3.tar.bz2
  tar xjf curl-7.21.3.tar.bz2
  cd curl-7.21.3
  ./configure --prefix=/usr
  make
  make install

Compile then install Python :

::
 
  wget http://www.python.org/ftp/python/2.6.6/Python-2.6.6.tar.bz2
  tar xjf Python-2.6.6.tar.bz2
  cd Python-2.6.6
  ./configure
  make
  make install

Compile then install your own GDAL library :

::

  wget http://download.osgeo.org/gdal/gdal-1.7.3.tar.gz
  tar xzf gdal-1.7.3.tar.gz
  cd gdal-1.7.3
  ./configure  # add your options here
  make
  make install

Install the Sun JAVA SDK into ``/usr/share`` then use the following command to ensure that the ``libjvm.so`` 
will be found at runtime from any context.

::

  echo /usr/share/java-1.6.0-openjdk-1.6.0.0/jre/lib/i386/client/ >> /etc/ld.so.conf.d/jvm.conf
  ldconfig

Compile ZOO-Kernel and ZOO-Services
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Compile then install ZOO-Kernel and your first ZOO-Services.

First of all, compile the cgic library providen in the SVN source tree:

::

  svn co http://svn.zoo-project.org/svn/trunk zoo-project
  cd zoo-project/thirds/cgic206
  make

Compile then install ZOO-Kernel.

::

  cd ../../zoo-kernel
  ./configure --with-java=/usr/share/jdk1.6.0_23/ --with-python
  make zoo_loader.cgi
  cp main.cfg /var/www/cgi-bin/
  cp  zoo_loader.cgi /var/www/cgi-bin/

Compile then deploy your first ZOO-ServicesProviders (simple HelloPy, line 1 and 2, and the OGR base-vect-ops 
ServiceProvider, line 3 to 6):

::

  cp ../zoo-services/hello-py/cgi-env/*.zcfg /var/www/cgi-bin/
  cp ../zoo-services/hello-py/test_service.py /var/www/cgi-bin/
  cd ../ogr/base-vect-ops/
  make
  cp ./cgi-env/* /var/www/cgi-bin/
  vi /var/www/cgi-bin/main.cfg --> set your own informations here

To ensure that the ``libjvm.so`` will be found from apache, please restart it :

::

  /etc/init.d/httpd restart

Testing your ZOO-Kernel
^^^^^^^^^^^^^^^^^^^^^^^

Test your ZOO-Kernel from command line:

::

  cd /var/www/cgi-bin
  ./zoo_loader.cgi "request=Execute&service=WPS&version=1.0.0&Identifier=HelloPy&DataInputs=a=Djay"
  ./zoo_loader.cgi "request=Execute&service=WPS&version=1.0.0&Identifier=Buffer&DataInputs=BufferDistance=1@datat

Debian / Ubuntu
***************

.. note::
   An Ubuntu 10.4 with ZOO virtual image is available at http://www.zoo-project.org/Ubuntu10.4_ZOO.zip
   (root: ZOO.test)

The following instructions were tested on Debian Squeeze, Ubuntu 10.04 and Ubuntu 10.10

Installation Workflow
^^^^^^^^^^^^^^^^^^^^^

- install some dependencies

::

  sudo apt-get install flex bison libfcgi-dev libxml2 libxml2-dev curl openssl autoconf checkinstall

- download ZOO  source

::

  svn checkout http://svn.zoo-project.org/svn/trunk zoo-project

- install cgic from packages

::

  cd zoo-project/thirds/cgic206/

- change the path of installation

::

  nano Makefile 
    - LIBS=-L./ -lcgic ../fcgi-2.4.0/libfcgi/.libs/libfcgi.a --> LIBS=/path/to/libfcgi.a
    - cp libcgic.a  ../../dist/lib --> cp libcgic.a /usr/lib
    - cp cgic.h  ../../dist//include --> cp cgic.h  /usr/include
    - @echo libcgic.a is in  ../../dist/lib and cgic.h is in  ../../dist//include. --> @echo libcgic.a is in  /usr/lib and cgic.h is in /usr/include.

- compile

::

  make

- install

::

  sudo make install

- go to kernel path

::

  cd ../../zoo-kernel/

- create configure file

::

  autoconf

- run configure

.. note::
   In Ubuntu 10.04 libmozjs-dev does not exist, so to use JS you can compile `SpiderMonkey <https://developer.mozilla.org/en/SpiderMonkey>`__ or use the xulrunner-dev package 
   which includes SpiderMonkey.  
   For PHP, you must make sure to compile PHP with `--enable-embed <http://www.zoo-project.org/trac/wiki/ZooKernel/Embed/PHP#ConfigureandInstallPHPEmbedlibrary>`__.

::

  ./configure --with-java=/path/to/java
  
  to JavaScript with XulRunner SpiderMonkey you have to edit configure file.
    - JS_CPPFLAGS="-I$JSHOME/include/js" --> JS_CPPFLAGS="-I$JSHOME/include"
    - JS_LDFLAGS="-L$JSHOME/lib -ljs -lm" --> JS_LDFLAGS="-L$JSHOME/lib -lmozjs -lm"
    - JS_LIB="js" --> JS_LIB="mozjs"
    
  ./configure --with-js=/usr/lib/xulrunner-devel.1.9.2.n

- compile

::

  make zoo_loader.cgi

- copy necessary files into your cgi-bin

::

  sudo cp main.cfg /usr/lib/cgi-bin
  sudo cp zoo_loader.cgi /usr/lib/cgi-bin

- Install ZOO ServiceProvider

::

  sudo cp ../zoo-services/hello-py/cgi-env/*.zcfg /usr/lib/cgi-bin
  sudo cp ../zoo-services/hello-py/*.py /usr/lib/cgi-bin/

- change some paths in the main.cfg

::

  sudo nano /usr/lib/cgi-bin/main.cfg
    - serverAddress = http://127.0.0.1
    - providerSite = http://127.0.0.1


- try the installation

  - http://127.0.0.1/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=GetCapabilities&Version=1.0.0
  - http://127.0.0.1/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=DescribeProcess&Version=1.0.0&Identifier=HelloPy
  - http://127.0.0.1/cgi-bin/zoo_loader.cgi?ServiceProvider=&metapath=&Service=WPS&Request=Execute&Version=1.0.0&Identifier=HelloPy&DataInputs=a=myname

.. note::
   If you have some problem in the execute request, add the following to ``main.cfg``: 

   ::
   
     [env]
     PYTHONPATH=<YOUR_PYTHONPATH>

Windows
-------

Using OSGeo4W
*************

ZOO4W is the easiest way to use ZOO Kernel on Windows platforms. It is based on the use of OSGeo4W, and some third-party libs. 
Please follow the steps bellow to install ZOO Kernel. Note that Win32 support for ZOO Kernel is still under development and 
that some bugs may still appear.

Install OSGeo4W
^^^^^^^^^^^^^^^

Download the OSGeo4W installer from  http://trac.osgeo.org/osgeo4w/, and install it with all the dependencies needed by your 
services (GDAL/OGR for example). The following libs are required: FastCGI, libxml, Python, cURL.

Install other tools and libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After installing OSGeo4W on your platform you'll need more GNU tools and libraries. `This package <http://www.zoo-project.org/dl/tool-win32.zip>`__ 
contains full dependencies required to compile on WIN32 platform and this one contains `full runtime dependencies to place <http://www.zoo-project.org/dl/zoo-runtime.zip>`__ 
in your c:\OSGeo4W\bin.

Download and Install ZOO Kernel
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Download the `binary version <http://www.zoo-project.org/dl/zoo_loader.cgi>`__  of the ZOO Kernel for WIN32 then place it in the 
``C:\OSGeo4W\bin`` directory. Don't forget to place a ``main.cfg`` file in the same directory, you can use a modified copy of 
`this file <http://www.zoo-project.org/trac/browser/trunk/zoo-kernel/main.cfg>`__.

Deploy ZOO Services Providers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Your can use the binary version of the OGR Services Provider available from `here <http://www.zoo-project.org/dl/zoo-services-win32.zip>`__. 
Then place the two libraries with their respective .zcfg files in your local ``C:\OSGeo4W\bin`` directory.

Testing
^^^^^^^

Now you should be able to query your local ZOO Kernel. 

Compiling Using Your Own Libraries
**********************************

The following steps are for use with the Microsoft Visual Studio compiler (and tested with MSVC 2008).

1. Make sure the gnuwin32 tools ``bison.exe`` and ``flex.exe`` are found in your path.  You can download the GNUwin32 tools `here <http://www.zoo-project.org/dl/tool-win32.zip>`__.

2. Modify the file ``zoo-project\zoo-kernel\nmake.opt`` to point to your local libraries.  You can find a modified nmake.opt that points to local libs `here <http://www.zoo-project.org/trac/attachment/ticket/27/nmake.opt>`__. 
   You can also find a modified ``zoo-project\zoo-kernel\makefile.vc`` file `here <http://www.zoo-project.org/trac/attachment/ticket/27/makefile.vc>`__.
   
3. Execute:

   ::
   
     nmake /f makefile.vc
     
4. A file ``zoo_loader.cgi`` should be created.  Note that if another file named ``zoo_loader.cgi.manifest`` is also created, you
   will have to run another command:
   
   ::
   
     nmake /f makefile.vc embed-manifest
     
5. Copy the files ``zoo_loader.cgi`` and ``main.cfg`` into your cgi-bin directory.

6. Using the command prompt, test the zoo-kernel by executing the following command:

   ::
   
     D:\ms4w\Apache\cgi-bin> zoo_loader.cgi
     
   which should display a message such as:
   
   ::
   
     Content-Type: text/xml; charset=utf-8
     Status: 200 OK
     
     <?xml version="1.0" encoding="utf-8"?>
     <ows:ExceptionReport xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xsi:schemaLocation="http://www.opengis.net/ows/1.1 http://schemas.opengis.net/ows/1.1.0/owsExceptionReport.xsd" xml:lang="en-US" version="1.1.0">
       <ows:Exception exceptionCode="MissingParameterValue">
         <ows:ExceptionText>Parameter &lt;request&gt; was not specified</ows:ExceptionText>
       </ows:Exception>
     </ows:ExceptionReport>
     
7. Edit the file ``cgi-bin/main.cfg`` so that it contains values describing your WPS service.  An example of such 
   a file running on Windows is:
   
   ::
   
     [main]
     encoding = utf-8
     version = 1.0.0
     serverAddress = http://localhost/
     lang = en-CA
     tmpPath=/ms4w/tmp/ms_tmp/
     tmpUrl = /ms_tmp/
     
     [identification]
     title = The Zoo WPS Development Server
     abstract = Development version of ZooWPS. See http://www.zoo-project.org
     fees = None
     accessConstraints = none
     keywords = WPS,GIS,buffer
     
     [provider]
     providerName=Gateway Geomatics
     providerSite=http://www.gatewaygeomatics.com
     individualName=Jeff McKenna
     positionName=Director
     role=Dev
     adressDeliveryPoint=1101 Blue Rocks Road
     addressCity=Lunenburg
     addressAdministrativeArea=False
     addressPostalCode=B0J 2C0
     addressCountry=ca
     addressElectronicMailAddress=info@gatewaygeomatics.com
     phoneVoice=False
     phoneFacsimile=False
     
8. Open a web browser window, and execute a GetCapababilites request on your WPS service: http://localhost/cgi-bin/zoo_loader.cgi?request=GetCapabilities&service=WPS

   The response should be displayed in your browser, such as:
   
   ::
   
     <wps:Capabilities xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsGetCapabilities_response.xsd" service="WPS" xml:lang="en-US" version="1.0.0">
     <ows:ServiceIdentification>
       <ows:Title>The Zoo WPS Development Server</ows:Title>
       <ows:Abstract>
         Development version of ZooWPS. See http://www.zoo-project.org
       </ows:Abstract>
       <ows:Keywords>
         <ows:Keyword>WPS</ows:Keyword>
         <ows:Keyword>GIS</ows:Keyword>
         <ows:Keyword>buffer</ows:Keyword>
       </ows:Keywords>
       <ows:ServiceType>WPS</ows:ServiceType>
       <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
       ...
       
Optionally Compile Individual Services
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An example could be the ``OGR base-vect-ops`` provider in the ``zoo-project\zoo-services\ogr\base-vect-ops`` directory.  

1. Edit the makefile.vc located in that directory, and execute:

   ::
   
     nmake /f makefile.vc
     
   Inside that same directory, the file ``cgi-env\ogr_service.zo`` should be created.
   
2. Copy all of the files inside ``zoo-services\ogr\base-vect-ops\cgi-env`` into your cgi-bin directory

3. Test this service provider through the following URL:

   http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Buffer&DataInputs=BufferDistance=1@datatype=interger;InputPolygon=Reference@xlink:href=http%3A%2F%2Fwww.zoo-project.org%3A8082%2Fgeoserver%2Fows%3FSERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dtopp%3Astates%26SRS%3DEPSG%3A4326%26FeatureID%3Dstates.15
   
   The response displayed in your browser should contain:
   
   ::
   
     <wps:ProcessSucceeded>Service "Buffer" run successfully.</wps:ProcessSucceeded>

Mac OS X
--------

Using the Installer
*******************

1. To install a default build of the ZOO-Project on your Mac OS X computer use the `installer <http://www.zoo-project.org/trac/raw-attachment/wiki/ZooDocumentation/ZOOKernel/MacOSX_installation/ZOO-Project-Installer.pkg>`__.

   .. note::
      The installer assumes that you are using the distributed Apache2 version that comes with your Mac.  The installer will
      place ZOO-Kernel and ZOO-Services into your cgi-bin at ``/Library/WebServer/CGI-Executables``, and the zoo-demo folder
      will be placed within your document root at ``/Library/WebServer/Documents``

2. Make sure that your Apache server is running, and then access the ZOO Project Demo at:

      http://localhost/zoo-demo/spatialtools.html
      
3. To add additional services, please follow the following intructions to compile your own ZOO Project instance.

Compiling from Source
*********************

1. Install `Xcode <http://developer.apple.com/technologies/tools/>`__.

2. Before you start downloading the ZOO-Project source code, you'll need to install some tools required to 
   compile ZOO-Kernel properly.

   First of all install PROJ, GEOS and GDAL frameworks from `here <http://www.kyngchaos.com/software/frameworks>`__.

   At this step, you should get the following directories on your local hard drive :

   ::
   
     /Library/Frameworks/PROJ.framework
     /Library/Frameworks/GEOS.framework
     /Library/Frameworks/GDAL.framework

3. Then, create a ``src`` directory and inside that directory download the `gettext source code <http://www.gnu.org/software/gettext/#TOCdownloading>`__ and uncompress it.

   now, compile gettext with the following commands to produce a universal binary :

   ::
   
     cd gettext-0.18.1.1
     CFLAGS="-O -g -arch i386 -arch ppc -arch x86_64"  \
       LDFLAGS="-arch i386 -arch ppc -arch x86_64"   ./configure
     make
     sudo make install

4. Compile and install your ZOO-Kernel

   - Download source from SVN, and use the following command to compile libcgic :

     ::
     
       svn co http://svn.zoo-project.org/svn/trunk zoo
       cd zoo/thirds/cgic206
       make

   - If you produced the ``libcgic.a`` file, you can run ``autoconf`` and then ``configure`` from zoo-kernel directory.

     ::
     
       cd zoo/zoo-kernel
       autoconf
       ./configure --with-python --with-java=macos \
          --with-gdal-config=/Library/Frameworks/GDAL.framework/Versions/1.8/Programs/gdal-config

     Obviously, if you don't need Python or Java support then you should remove the corresponding configure option.

     .. note:: 
        Note that we used the --with-java=macos configure option. Due to the generic location of the JDK on all 
        Mac OS X platforms, you don't have to provide its full path.

   - Now, run the following commands to compile and deploy your ZOO-Kernel on your Apache server :

     ::
     
       make
       cp zoo_loader.cgi main.cfg /Library/WebServer/CGI-Executables

     You should be ready to request your ZOO-Kernel installation using the following link :  http://localhost/cgi-bin/zoo_loader.cgi?request=GetCapabilities&service=WPS .

     If everything is ok, you can follow the next steps to deploy new Services Providers.
     
     .. note::
        If you are using your own libs (not the default libs on your system) then you must take care to create
        universal versions of those libs, as the ZOO-Kernel will try to create a universal binary.  If you are
        not following this advice, you might receive compile errors of ``symbol(s) not found for architecture ppc`` or ``file was built for 
        unsupported file format which is not the architecture being linked (ppc)``.
     
Deploy the OGR Services Provider
********************************

Requirements
^^^^^^^^^^^^

Before your try to use any service, please set the correct path in the ``main.cfg`` for tmpPath and tmpUrl.

You can use the following setup :

::

  tmpPath = /Library/WebServer/Documents/tmp
  tmpUrl = ../../tmp

Obviously you'll then need to create this directory, using the following command :

::

  mkdir /Library/WebServer/Documents/tmp

C Version
^^^^^^^^^

To compile the base-vect-ops ServicesProvider you'll need to edit the Makefile in *zoo/zoo-services/ogr/base-vect-ops/* 
directory. Add "-I/Library//Frameworks/GEOS.framework/Versions/3/Headers/" to the CFLAGS value on the first line. 
To compile, add GDAL framework to the PATH environmenet variable, to ensure that gdal-config tool will be found, 
run make and then copy cgi-env files in the /Library/WebServer/CGI-Executables directory.

::

  cd zoo/zoo-services/ogr/base-vect-ops/
  export PATH=$PATH:/Library/Frameworks/GDAL.framework/Versions/1.7/Programs/
  make
  cp cgi-env/* /Library/WebServer/CGI-Executables

You can test using this `url <http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=Buffer&DataInputs=BufferDistance=1@datatype=interger;InputPolygon=Reference@xlink:href=http%3A%2F%2Fwww.zoo-project.org%3A8082%2Fgeoserver%2Fows%3FSERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dtopp%3Astates%26SRS%3DEPSG%3A4326%26FeatureID%3Dstates.15>`__ 
if everything is ok with your setup.

Python Version
^^^^^^^^^^^^^^

**Requirements**

First of all run python from a Terminal.app and try the following import from the python interpreter :

::

  import osgeo.ogr
  import libxml2

If you get an issue when importing the libxml2 module from your python interpreter then that means you 
need to install the Python support for the libxml2 library which is already installed on your Mac OS X environment. 
To accomplish this, you have first to determine what version of libxml2 is installed on your platform, using the following command:

xml2-config --version

Download the source corresponding to your version (i.e. on 10.6.6 you get 2.7.3) from the libxml2  
`download page <ftp://xmlsoft.org/libxml2/>`__ into your ``src`` directory then uncompress it.

Use the following command to install the python support :

::

  cd src/libxml2-2.7.3/python/
  python setup.py install

**Deploy OGR Python Services Provider**

- Now copy the ``zoo-services/ogt/base-vect-ops/cgi-env`` files into ``/Library/WebServer/CGI-Executables``.

You can test using this `url <http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&service=WPS&version=1.0.0&Identifier=BufferPy&DataInputs=BufferDistance=1@datatype=interger;InputPolygon=Reference@xlink:href=http%3A%2F%2Fwww.zoo-project.org%3A8082%2Fgeoserver%2Fows%3FSERVICE%3DWFS%26REQUEST%3DGetFeature%26VERSION%3D1.0.0%26typename%3Dtopp%3Astates%26SRS%3DEPSG%3A4326%26FeatureID%3Dstates.15>`__ 
if everything is ok with your setup.

Test using Local Demo Page
**************************

- Download the `OpenLayers <http://openlayers.org>`__ library and uncompress it in your personal Sites directory 
  (located in your home directory). 
  
- Rename the OpenLayers directory as openlayers. 

- Download this `zip archive <http://www.zoo-project.org/trac/raw-attachment/wiki/ZooDocumentation/ZOOKernel/MacOSX_installation/zoo-demo.zip>`__ 
  and then uncompress it in your personal Sites directory. 
  
- Load your local demo pages using urls similar to the following (replacing MyUserName by your MacOS user name) :

    *  http://localhost/~MyUserName/zoo-demo/spatialtools.html
    *  http://localhost/~MyUserName/zoo-demo/spatialtools-py.html