trunk/doc/INSTALL.txt

                        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.8).  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,2010 Andrew M. Bishop.
1	Program Compilation / Installation
2	==================================
3
4	Compilation
5
6	This program has been written to run on Linux, no cross-platform
7	compatibility has been specifically included but on the other hand nothing
8	platform specific has been included.
9
10	Any information on improving the compilation process on anything other than
11	32-bit x86 Linux is welcome.
12
13	No external libraries are required and the programs are written in standard C
14	language.
15
16	To compile the programs just type 'make'.
17
18	Installation - executables
19
20	After compilation the executable files are copied into the directory 'web/bin'.
21
22	The executable files remain in the 'src' directory and are called
23	'planetsplitter', 'router' and 'filedumper'. They can be copied to any
24	location and need no special installation environment.
25
26	Installation - example web page
27
28	The directory 'web' contains a set of files that can be used to create a
29	working set of web pages with interfaces to the routing algorithm.
30
31	The files in the 'web' directory will require copying to a location that is
32	accessible by a web server. After copying the files some of them may need to
33	be edited; search through the files for lines that contain the words "EDIT
34	THIS" and make appropriate edits.
35
36	Configuration of web files
37
38	The assumption in this description is that the whole of the directory called
39	'web' is copied into a directory that is accessible by an Apache web server.
40
41	**************************************************************************
42	** This is not a secure configuration but an easy one to configure. **
43	** Only the directory 'www' should be accessible by the web server. **
44	** Do not use this configuration unmodified in a public web server. **
45	**************************************************************************
46
47	The directory structure is as follows:
48
49	web/
50	\|
51	+ /bin/ <- The Routino executable files.
52	\|
53	+ /data/ <- The Routino database.
54	\|
55	+ /results/ <- An empty directory to store the results.
56	\|
57	+ /www/ <- The files that must be available to the web
58	\| server are below this level.
59	\|
60	+ /openlayers/ <- A directory to hold the OpenLayers scripts.
61	\|
62	+ /routino/ <- The main HTML, Javascript, CSS and CGI files.
63
64
65	The directory 'bin' will be filled by running the compilation process. For a
66	secure installation the 'bin' directory should be outside of the web server,
67	the file 'www/routino/paths.pl' contains the path to the 'bin' directory.
68
69	The directory 'data' must contain the Routino database. This can be created
70	by downloading the OSM files for the region of interest and running the
71	planetsplitter program. There is a script in the directory that will
72	download the OSM files and create the required database. The script should
73	be edited to set the names of the files to be downloaded. For a secure
74	installation the 'data' directory should be outside of the web server, the
75	file 'www/routino/paths.pl' contains the path to the 'data' directory.
76
77	The directory 'results' is a temporary directory that it used to hold the GPX
78	and text files generated by the Routino router. The directory must be
79	writable by the web server process since it is the CGI scripts that are run
80	by the web server that writes the results here. For a secure installation
81	the 'results' directory should be outside of the web server, the file
82	'www/routino/paths.pl' contains the path to the 'results' directory.
83
84	The directory 'www' and its sub-directories are the only ones that must be
85	within the web server accessible directory.
86
87	The directory 'www/openlayers' must be filled with the openlayers Javascript
88	library that can be downloaded from http://www.openlayers.org/. (This
89	version of Routino has been tested with OpenLayers library version 2.8). The
90	files must be installed so that the file 'www/openlayers/OpenLayers.js' and
91	the directories 'www/openlayers/img/', 'www/openlayers/theme/' all exist.
92	There is a script in the directory that will automatically download and
93	organise the files.
94
95	The directory 'routino' contains the main HTML, Javascript and CSS files as
96	well as the CGI scripts that perform the server-side functions. The
97	description below lists all of the files that contain editable information.
98
99	paths.pl - This contains the names of the directories that contain the
100	executable files, router database and temporary results.
101
102	router.pl - This file contains the filename prefix for the routing database
103	files (only needed if planetsplitter is run with the --prefix
104	option).
105
106	router.js - The parameters in this file control the boundary of the visible
107	map (defaults to UK), the minimum and maximum zoom levels
108	(defaults to between 4 and 15 inclusive) and the source of map
109	tiles (defaults to the main OpenStreetMap tile server).
110
111	visualiser.js - The same parameters as in router.js are in this file.
112
113	Configuration of web server
114
115	The file 'www/routino/.htaccess' contains all of the Apache configuration
116	options that are required to get the example web pages running. The only
117	problem is that because of the way that the "AllowOverride" option works one
118	of the configuration options has been commented out. This must be enabled in
119	the main Apache server configuration file.
120
121
122	--------
123
124	Copyright 2008,2009,2010 Andrew M. Bishop.