Program Compilation / Installation
                        ==================================

Compilation

   This program has been written to run on Linux, no cross-platform
   compatibility has been specifically included but on the other hand nothing
   platform specific has been included.

   Any information on improving the compilation process on anything other than
   32-bit x86 Linux is welcome.

   No external libraries are required and the programs are written in standard C
   language.

   To compile the programs just type 'make'.

Installation - executables

   After compilation the executable files are copied into the directory 'web/bin'.

   The executable files remain in the 'src' directory and are called
   'planetsplitter', 'router' and 'filedumper'.  They can be copied to any
   location and need no special installation environment.

Installation - example web page

   The directory 'web' contains a set of files that can be used to create a
   working set of web pages with interfaces to the routing algorithm.

   The files in the 'web' directory will require copying to a location that is
   accessible by a web server.  After copying the files some of them may need to
   be edited; search through the files for lines that contain the words "EDIT
   THIS" and make appropriate edits.

Configuration of web files

   The assumption in this description is that the whole of the directory called
   'web' is copied into a directory that is accessible by an Apache web server.

    **************************************************************************
    **** This is not a secure configuration but an easy one to configure. ****
    **** Only the directory 'www' should be accessible by the web server. ****
    **** Do not use this configuration unmodified in a public web server. ****
    **************************************************************************

   The directory structure is as follows:

   web/
    |
    + /bin/                    <- The Routino executable files.
    |
    + /data/                   <- The Routino database.
    |
    + /results/                <- An empty directory to store the results.
    |
    + /www/                    <- The files that must be available to the web
        |                         server are below this level.
        |
        + /openlayers/         <- A directory to hold the OpenLayers scripts.
        |
        + /routino/            <- The main HTML, Javascript, CSS and CGI files.


   The directory 'bin' will be filled by running the compilation process.  For a
   secure installation the 'bin' directory should be outside of the web server,
   the file 'www/routino/paths.pl' contains the path to the 'bin' directory.

   The directory 'data' must contain the Routino database.  This can be created
   by downloading the OSM files for the region of interest and running the
   planetsplitter program.  There is a script in the directory that will
   download the OSM files and create the required database.  The script should
   be edited to set the names of the files to be downloaded.  For a secure
   installation the 'data' directory should be outside of the web server, the
   file 'www/routino/paths.pl' contains the path to the 'data' directory.

   The directory 'results' is a temporary directory that it used to hold the GPX
   and text files generated by the Routino router.  The directory must be
   writable by the web server process since it is the CGI scripts that are run
   by the web server that writes the results here.  For a secure installation
   the 'results' directory should be outside of the web server, the file
   'www/routino/paths.pl' contains the path to the 'results' directory.

   The directory 'www' and its sub-directories are the only ones that must be
   within the web server accessible directory.

   The directory 'www/openlayers' must be filled with the openlayers Javascript
   library that can be downloaded from http://www.openlayers.org/.  (This
   version of Routino has been tested with OpenLayers library version 2.7).  The
   files must be installed so that the file 'www/openlayers/OpenLayers.js' and
   the directories 'www/openlayers/img/', 'www/openlayers/theme/' all exist.
   There is a script in the directory that will automatically download and
   organise the files.

   The directory 'routino' contains the main HTML, Javascript and CSS files as
   well as the CGI scripts that perform the server-side functions.  The
   description below lists all of the files that contain editable information.

   paths.pl - This contains the names of the directories that contain the
              executable files, router database and temporary results.

   router.pl - This file contains the filename prefix for the routing database
               files (only needed if planetsplitter is run with the --prefix
               option).

   router.js - The parameters in this file control the boundary of the visible
               map (defaults to UK), the minimum and maximum zoom levels
               (defaults to between 4 and 15 inclusive) and the source of map
               tiles (defaults to the main OpenStreetMap tile server).

   visualiser.js - The same parameters as in router.js are in this file.

Configuration of web server

   The file 'www/routino/.htaccess' contains all of the Apache configuration
   options that are required to get the example web pages running.  The only
   problem is that because of the way that the "AllowOverride" option works one
   of the configuration options has been commented out.  This must be enabled in
   the main Apache server configuration file.


--------

Copyright 2008,2009 Andrew M. Bishop.