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 need to be
   edited; search through the files for lines that contain the words "EDIT THIS"
   and make appropriate edits.  The files that need editing are "paths.pl" (to
   set the directory paths) and "router.js" and "visualiser.js" to limit the
   range of the visible map (latitude, longitude and zoom).


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