destination-access/doc/INSTALL-MS-WIN.txt

                   Routino : Installation on MS Windows
                   ====================================


Using Cygwin
------------

   Cygwin is a large collection of GNU and Open Source tools which provide
   functionality similar to a Linux distribution on Windows. A Cygwin DLL
   provides substantial POSIX API functionality therefore providing direct
   compatibility for most UNIX source code.

   Since Cygwin aims to replicate a Linux-like system on Windows it is the
   simplest method of compiling Routino. The disadvantage is that all
   programs compiled with Cygwin require a number of runtime Cygwin
   libraries which may introduce a runtime speed penalty.

   The installer for Cygwin can be downloaded from http://cygwin.org/;
   there are 32-bit and 64-bit versions available. For compiling Routino
   the Cygwin installer should be run and the following packages selected
   (any dependencies will be automatically be selected at the next step):

     * base packages
     * gcc-core (in 'Devel' menu)
     * make (in 'Devel' menu)
     * libbz2-devel (in 'Libs' menu)
     * zlib-devel (in 'Libs' menu)
     * perl (in 'Perl' menu)

   To compile Routino open the "Cygwin Terminal" change to the Routino
   source directory and compile using the make command.

   The programs that are compiled 'planetsplitter', 'router' will require the
   Cygwin runtime to be able to run them. The library 'libroutino.so' should
   be usable with other Cygwin compiled programs.


Native Compilation
------------------

   Routino has limited support in the source code for compiling on
   Microsoft Windows. This includes a set of functions that can replace
   the mmap() and munmap() UNIX functions which are not available on
   Microsoft Windows.

   The source code should be downloaded, either as a release version file
   or from subversion - no instructions are provided for this step. The
   release versions include some files (mainly the web icons) which are
   not included in the subversion source (and which may be difficult to
   create on Windows).

Using Microsoft Visual C
- - - - - - - - - - - -

   The Routino source code (for the router at least) has been modified so
   that it will compile with the Microsoft Visual C compiler.

   Compiling Routino with MSVC is not supported directly since there is
   only support for using Makefiles in Routino. The files that need to be
   compiled for the Routino router can be found from the Makefile in the
   src directory listed in the 'ROUTER_OBJ' variable.

   To compile the router in slim mode the pre-processor definition 'SLIM=0'
   must be set and for non-slim mode 'SLIM=1' must be set.

   The default directory for the Routino data files must be set in the
   'ROUTINO_DATADIR' pre-processor variable. If the router command line
   '--data' option is going to be used then this variable can be set to
   any value.

   Since Microsoft Visual C does not fully support the C99 standard it is
   necessary to tell the compiler how to handle the inline functions. This
   can be done by passing in the command line option '-Dinline=__inline' to
   the C compiler.

Using MinGW
- - - - - -

   MinGW is the "Minimalist GNU for Windows" which includes some of the
   common GNU programs; principally gcc and related programs for software
   development.

   The installer for MinGW can be downloaded from 'http://mingw.org/'. For
   compiling Routino the MinGW installer should be run and the following
   packages selected:
     * mingw-base
     * msys-base
     * mingw32-pthreads-w32
     * mingw32-libz (dev package)
     * msys-perl

   To compile Routino open a DOS command window and set the path to the
   installed MinGW and MSYS software. For example if MinGW was installed
   in the 'C:/MinGW' directory then the path needs to be set to
   'C:\MinGW\bin;C:\MinGW\MSYS\1.0\bin'.

   From within this DOS command window change to the Routino source
   directory and compile using the MinGW version of make with this command
   'mingw32-make'.

   After compiling Routino a set of library files are created ('routino.dll',
   'routino.def' and 'routino.lib'). These should be usable for linking with
   programs compiled with MSVC.

Using MinGW-W64
- - - - - - - -

   MinGW-w64 is an alernative implementation of the same concept as MinGW
   but allows for compilation to 32-bit or 64-bit executables.

   The website for MinGW-w64 is 'http://mingw-w64.org/' but the downloads
   are available from 'http://win-builds.org/'. Installation of MinGW-w64 is
   slightly different from that for MinGW but a similar set of packages
   will be required.

   The compilation method for MinGW-w64 is the same as for MinGW and the
   same files will be compiled, the only difference is that by default a
   64-bit version will be created.

Limitations
- - - - - -

   A native Microsoft Windows compilation of Routino is more complicated
   than compiling on Linux, other UNIX system or Cygwin. This is probably
   not an option if you are unfamiliar with software development on
   Microsoft Windows.

   The size of files that can be accessed with an MSVC or MinGW (32-bit)
   compiled version of Routino is limited to 32-bits (less than 4 GB). The
   MinGW-w64 compiler on 64-bit is able to handle larger files (bigger
   than 4 GB).

   The Windows operating system does not have a function equivalent to the
   'fork()' function on UNIX. This means that it is not possible to use the
   planetsplitter program's built-in file decompression with an MSVC or
   MinGW compiled version of Routino.


Example Web Pages
-----------------

   No instructions are available for using the Routino example web pages
   with the Microsoft Web server (IIS).

   For information on setting up Apache see the "Example Web Pages"
   section of the main installation instructions.


--------

Copyright 2008-2015 Andrew M. Bishop.
1	Routino : Installation on MS Windows
2	====================================
3
4
5	Using Cygwin
6	------------
7
8	Cygwin is a large collection of GNU and Open Source tools which provide
9	functionality similar to a Linux distribution on Windows. A Cygwin DLL
10	provides substantial POSIX API functionality therefore providing direct
11	compatibility for most UNIX source code.
12
13	Since Cygwin aims to replicate a Linux-like system on Windows it is the
14	simplest method of compiling Routino. The disadvantage is that all
15	programs compiled with Cygwin require a number of runtime Cygwin
16	libraries which may introduce a runtime speed penalty.
17
18	The installer for Cygwin can be downloaded from http://cygwin.org/;
19	there are 32-bit and 64-bit versions available. For compiling Routino
20	the Cygwin installer should be run and the following packages selected
21	(any dependencies will be automatically be selected at the next step):
22
23	* base packages
24	* gcc-core (in 'Devel' menu)
25	* make (in 'Devel' menu)
26	* libbz2-devel (in 'Libs' menu)
27	* zlib-devel (in 'Libs' menu)
28	* perl (in 'Perl' menu)
29
30	To compile Routino open the "Cygwin Terminal" change to the Routino
31	source directory and compile using the make command.
32
33	The programs that are compiled 'planetsplitter', 'router' will require the
34	Cygwin runtime to be able to run them. The library 'libroutino.so' should
35	be usable with other Cygwin compiled programs.
36
37
38	Native Compilation
39	------------------
40
41	Routino has limited support in the source code for compiling on
42	Microsoft Windows. This includes a set of functions that can replace
43	the mmap() and munmap() UNIX functions which are not available on
44	Microsoft Windows.
45
46	The source code should be downloaded, either as a release version file
47	or from subversion - no instructions are provided for this step. The
48	release versions include some files (mainly the web icons) which are
49	not included in the subversion source (and which may be difficult to
50	create on Windows).
51
52	Using Microsoft Visual C
53	- - - - - - - - - - - -
54
55	The Routino source code (for the router at least) has been modified so
56	that it will compile with the Microsoft Visual C compiler.
57
58	Compiling Routino with MSVC is not supported directly since there is
59	only support for using Makefiles in Routino. The files that need to be
60	compiled for the Routino router can be found from the Makefile in the
61	src directory listed in the 'ROUTER_OBJ' variable.
62
63	To compile the router in slim mode the pre-processor definition 'SLIM=0'
64	must be set and for non-slim mode 'SLIM=1' must be set.
65
66	The default directory for the Routino data files must be set in the
67	'ROUTINO_DATADIR' pre-processor variable. If the router command line
68	'--data' option is going to be used then this variable can be set to
69	any value.
70
71	Since Microsoft Visual C does not fully support the C99 standard it is
72	necessary to tell the compiler how to handle the inline functions. This
73	can be done by passing in the command line option '-Dinline=__inline' to
74	the C compiler.
75
76	Using MinGW
77	- - - - - -
78
79	MinGW is the "Minimalist GNU for Windows" which includes some of the
80	common GNU programs; principally gcc and related programs for software
81	development.
82
83	The installer for MinGW can be downloaded from 'http://mingw.org/'. For
84	compiling Routino the MinGW installer should be run and the following
85	packages selected:
86	* mingw-base
87	* msys-base
88	* mingw32-pthreads-w32
89	* mingw32-libz (dev package)
90	* msys-perl
91
92	To compile Routino open a DOS command window and set the path to the
93	installed MinGW and MSYS software. For example if MinGW was installed
94	in the 'C:/MinGW' directory then the path needs to be set to
95	'C:\MinGW\bin;C:\MinGW\MSYS\1.0\bin'.
96
97	From within this DOS command window change to the Routino source
98	directory and compile using the MinGW version of make with this command
99	'mingw32-make'.
100
101	After compiling Routino a set of library files are created ('routino.dll',
102	'routino.def' and 'routino.lib'). These should be usable for linking with
103	programs compiled with MSVC.
104
105	Using MinGW-W64
106	- - - - - - - -
107
108	MinGW-w64 is an alernative implementation of the same concept as MinGW
109	but allows for compilation to 32-bit or 64-bit executables.
110
111	The website for MinGW-w64 is 'http://mingw-w64.org/' but the downloads
112	are available from 'http://win-builds.org/'. Installation of MinGW-w64 is
113	slightly different from that for MinGW but a similar set of packages
114	will be required.
115
116	The compilation method for MinGW-w64 is the same as for MinGW and the
117	same files will be compiled, the only difference is that by default a
118	64-bit version will be created.
119
120	Limitations
121	- - - - - -
122
123	A native Microsoft Windows compilation of Routino is more complicated
124	than compiling on Linux, other UNIX system or Cygwin. This is probably
125	not an option if you are unfamiliar with software development on
126	Microsoft Windows.
127
128	The size of files that can be accessed with an MSVC or MinGW (32-bit)
129	compiled version of Routino is limited to 32-bits (less than 4 GB). The
130	MinGW-w64 compiler on 64-bit is able to handle larger files (bigger
131	than 4 GB).
132
133	The Windows operating system does not have a function equivalent to the
134	'fork()' function on UNIX. This means that it is not possible to use the
135	planetsplitter program's built-in file decompression with an MSVC or
136	MinGW compiled version of Routino.
137
138
139	Example Web Pages
140	-----------------
141
142	No instructions are available for using the Routino example web pages
143	with the Microsoft Web server (IIS).
144
145	For information on setting up Apache see the "Example Web Pages"
146	section of the main installation instructions.
147
148
149	--------
150
151	Copyright 2008-2015 Andrew M. Bishop.