destination-access/doc/INSTALL.txt

                           Routino : Installation
                           ======================


Pre-Requisites
--------------

   The programs are written in standard C language with minimal external
   requirements so only a small set of development tools are required
   (gcc, make).

   There is some support for multi-threading that uses pthreads and
   additional development libraries for this may be required. The
   mutli-threading can be disabled at compile time if required by
   commenting out a couple of lines in the file 'src/Makefile'.

   To use the built-in file decompression functions the zlib (or libz) and
   bzip2 (or libbz2) development libraries are also required. These can
   each be disabled by commenting out a couple of lines in the file
   'src/Makefile'.

   To use the web page interface an http server is required. Instructions
   below are for Apache but any server that supports CGIs should work.

   The web pages use the Perl scripting language and a number of the
   default Perl modules. To use the search function on the router web page
   the additional Perl module "JSON::PP" must be installed.


Compilation
-----------

   To compile the programs just type 'make' at the top level of the source
   tree.

   This program has been written to run on Linux, no cross-platform
   compatibility has been specifically included but on the other hand
   other platforms have not knowingly been excluded either.

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


Installation
------------

   After compilation the executable files are copied into the directory
   web/bin and the default XML configuration files are copied into the
   directory web/data. This is in preparation for using the supplied
   example web pages but is also a useful location to copy the files from
   for normal use.

   The executable files are called 'planetsplitter', 'router' and
   'filedumper' (also 'tagmodifier' for debugging tag modifications). They
   can be copied to any location and need no special installation
   environment.

   The default configuration files are called 'profiles.xml',
   'tagging.xml' and 'translations.xml'. The names of the configuration
   files can be specified on the command line but by default are also
   looked for in the directory that contains the routing database.


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 'mapprops.js' (to
   set the map properties).


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 (when compiled).
    |
    + /data/                   <- The Routino database and default configuration
    |                             files.
    |
    + /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.
            |
            + /documentation/  <- The HTML version of the Routino documentation.

   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 and is also the
   default location for the configuration files. The routing database is
   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 need
   to 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 versions 2.11 and 2.12). 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 the files, create an optimised "OpenLayers.js" and copy the
   files to the required locations.

   The directory 'www/routino' contains the main HTML, Javascript and CSS
   files as well as the CGI scripts that perform the server-side routing
   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; the
          prefix for the routing database; and the names of the
          executables.

   mapprops.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), the source of map
          tiles (defaults to the main OpenStreetMap tile server) and the
          number of waypoints allowed (defaults to 9).

   The directory www/routino/documentation contains the HTML version of
   the Routino documentation.


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-2012 Andrew M. Bishop.
1	Routino : Installation
2	======================
3
4
5	Pre-Requisites
6	--------------
7
8	The programs are written in standard C language with minimal external
9	requirements so only a small set of development tools are required
10	(gcc, make).
11
12	There is some support for multi-threading that uses pthreads and
13	additional development libraries for this may be required. The
14	mutli-threading can be disabled at compile time if required by
15	commenting out a couple of lines in the file 'src/Makefile'.
16
17	To use the built-in file decompression functions the zlib (or libz) and
18	bzip2 (or libbz2) development libraries are also required. These can
19	each be disabled by commenting out a couple of lines in the file
20	'src/Makefile'.
21
22	To use the web page interface an http server is required. Instructions
23	below are for Apache but any server that supports CGIs should work.
24
25	The web pages use the Perl scripting language and a number of the
26	default Perl modules. To use the search function on the router web page
27	the additional Perl module "JSON::PP" must be installed.
28
29
30	Compilation
31	-----------
32
33	To compile the programs just type 'make' at the top level of the source
34	tree.
35
36	This program has been written to run on Linux, no cross-platform
37	compatibility has been specifically included but on the other hand
38	other platforms have not knowingly been excluded either.
39
40	Any information on improving the compilation process on anything other
41	than x86 Linux is welcome.
42
43
44	Installation
45	------------
46
47	After compilation the executable files are copied into the directory
48	web/bin and the default XML configuration files are copied into the
49	directory web/data. This is in preparation for using the supplied
50	example web pages but is also a useful location to copy the files from
51	for normal use.
52
53	The executable files are called 'planetsplitter', 'router' and
54	'filedumper' (also 'tagmodifier' for debugging tag modifications). They
55	can be copied to any location and need no special installation
56	environment.
57
58	The default configuration files are called 'profiles.xml',
59	'tagging.xml' and 'translations.xml'. The names of the configuration
60	files can be specified on the command line but by default are also
61	looked for in the directory that contains the routing database.
62
63
64	Example Web Page
65	----------------
66
67	The directory 'web' contains a set of files that can be used to create
68	a working set of web pages with interfaces to the routing algorithm.
69
70	The files in the 'web' directory will require copying to a location
71	that is accessible by a web server. After copying the files some of
72	them need to be edited; search through the files for lines that contain
73	the words "EDIT THIS" and make appropriate edits. The files that need
74	editing are 'paths.pl' (to set the directory paths) and 'mapprops.js' (to
75	set the map properties).
76
77
78	Configuration of web files
79	--------------------------
80
81	The assumption in this description is that the whole of the directory
82	called web is copied into a directory that is accessible by an Apache
83	web server.
84
85	**************************************************************************
86	** This is not a secure configuration but an easy one to configure. **
87	** Only the directory 'www' should be accessible by the web server. **
88	** Do not use this configuration unmodified in a public web server. **
89	**************************************************************************
90
91	The directory structure is as follows:
92
93	web/
94	\|
95	+ /bin/ <- The Routino executable files (when compiled).
96	\|
97	+ /data/ <- The Routino database and default configuration
98	\| files.
99	\|
100	+ /results/ <- An empty directory to store the results.
101	\|
102	+ /www/ <- The files that must be available to the web
103	\| server are below this level.
104	\|
105	+ /openlayers/ <- A directory to hold the OpenLayers scripts.
106	\|
107	+ /routino/ <- The main HTML, Javascript, CSS and CGI files.
108	\|
109	+ /documentation/ <- The HTML version of the Routino documentation.
110
111	The directory 'bin' will be filled by running the compilation process.
112	For a secure installation the 'bin' directory should be outside of the
113	web server, the file 'www/routino/paths.pl' contains the path to the
114	'bin' directory.
115
116	The directory 'data' must contain the Routino database and is also the
117	default location for the configuration files. The routing database is
118	created by downloading the OSM files for the region of interest and
119	running the 'planetsplitter' program. There is a script in the
120	directory that will download the OSM files and create the required
121	database. The script should be edited to set the names of the files to
122	be downloaded. For a secure installation the 'data' directory should
123	be outside of the web server, the file 'www/routino/paths.pl' contains
124	the path to the 'data' directory.
125
126	The directory 'results' is a temporary directory that it used to hold
127	the GPX and text files generated by the Routino router. The directory
128	must be writable by the web server process since it is the CGI scripts
129	that are run by the web server that writes the results here. For a
130	secure installation the results directory should be outside of the web
131	server, the file 'www/routino/paths.pl' contains the path to the
132	results directory.
133
134	The directory 'www' and its sub-directories are the only ones that need
135	to be within the web server accessible directory.
136
137	The directory 'www/openlayers' must be filled with the openlayers
138	Javascript library that can be downloaded from
139	http://www.openlayers.org/. (This version of Routino has been tested
140	with OpenLayers library versions 2.11 and 2.12). The files must be
141	installed so that the file 'www/openlayers/OpenLayers.js' and the
142	directories 'www/openlayers/img/', 'www/openlayers/theme/' all
143	exist. There is a script in the directory that will automatically
144	download the files, create an optimised "OpenLayers.js" and copy the
145	files to the required locations.
146
147	The directory 'www/routino' contains the main HTML, Javascript and CSS
148	files as well as the CGI scripts that perform the server-side routing
149	functions. The description below lists all of the files that contain
150	editable information.
151
152	paths.pl
153	This contains the names of the directories that contain the
154	executable files, router database and temporary results; the
155	prefix for the routing database; and the names of the
156	executables.
157
158	mapprops.js
159	The parameters in this file control the boundary of the visible
160	map (defaults to UK), the minimum and maximum zoom levels
161	(defaults to between 4 and 15 inclusive), the source of map
162	tiles (defaults to the main OpenStreetMap tile server) and the
163	number of waypoints allowed (defaults to 9).
164
165	The directory www/routino/documentation contains the HTML version of
166	the Routino documentation.
167
168
169	Configuration of web server
170
171	The file 'www/routino/.htaccess' contains all of the Apache
172	configuration options that are required to get the example web pages
173	running. The only problem is that because of the way that the
174	"AllowOverride" option works one of the configuration options has been
175	commented out. This must be enabled in the main Apache server
176	configuration file.
177
178
179	--------
180
181	Copyright 2008-2012 Andrew M. Bishop.